shacraft-core/docs/PLAN.md

# План разработки

План составлен до реализации. Каждый этап заканчивается воспроизводимым результатом в локальном репозитории. `docs/STATUS.md` обновляется после проверок. Пункт не считается выполненным по наличию интерфейса, заглушки, каталога имён или успешной компиляции.

## Этап 0. Сохранить контекст и проверить проектирование

- Записать исходные требования, решения, контракты и критерии приёмки.
- Зафиксировать источники данных совместимости и ограничения лицензий.
- Разделить компоненты так, чтобы можно было независимо разрабатывать хранение, совместимость, сетевой сервер и клиент.
- Согласовать обработку ошибок, координаты, ревизии, ограничения операций и формат диагностики.

Выход: документы в `docs/`; список решений без молчаливого сокращения объёма.

## Этап 1. Ядро и доказуемое управление памятью

- Rust workspace; координаты с корректными отрицательными значениями; реестр канонических состояний блоков.
- Секции 16×16×16: единообразное состояние или палитра и упакованные индексы. Отсутствие отдельного объекта на каждый блок.
- Собственный версионированный формат хранения, ограниченный кэш, выгрузка на диск; операции чтения не изменяют мир.
- Независимые экземпляры общей карты. Изменение/сброс одного экземпляра не влияет на другие; снимок основы имеет чёткую семантику.
- Атомарные правки с журналом восстановления, ревизиями и идемпотентностью. История и undo хранятся на диске с ограниченным потреблением RAM.
- Проверки границ секций, упаковки, изоляции миров, повторов, конфликтов, сохранения и восстановления после сбоя. Измерение хранения общей карты против копий.

Выход: самостоятельная библиотека и воспроизводимые тесты/измерения. Это ещё не весь MVP.

## Этап 2. Сервер и минимальный клиент — сквозной сценарий

- Сервер владеет миром и симуляцией; фиксированный тик, серверные движение/столкновения и проверка взаимодействий.
- Версионированный протокол: подключение, начальный снимок, изменения блоков, игроки, переход между мирами, ошибки и восстановление подключения.
- Лимиты числа игроков, радиуса мира, сообщений, частоты действий и очередей. Медленный клиент не увеличивает память сервера без ограничения.
- Тестовый клиент: собственный рендерер, камера, управление, блоки, простые сущности, состояния соединения. Сервер остаётся без графики.
- Два независимых клиента видят одинаковые изменения. Перезапуск сохраняет мир. Подключение и выход не оставляют сущности и фоновые задачи.

Выход: запускаемая локальная сетевая песочница. На первом проходе допустим небольшой набор материалов; это не выполнение требования полного каталога.

## Этап 3. Control API и собственный MCP

- Общий API чтения, редактирования, истории и диагностики; MCP — отдельный процесс с stdio.
- Поиск материалов, чтение ограниченной области, пакетное строительство и шаблоны, preview/commit, undo с защитой от чужих изменений.
- Ресурсы с системой координат и возможностями; структурированные ответы и понятные ошибки.
- Визуальная обратная связь: снимок с явно указанными типом отображения и ревизией; топографический preview не объявляется снимком игрового клиента.
- Тестовые миры, сущности, управление аренами и метрики. Авторизация управляющего API; токен не попадает в клиентский код и журнал.
- Реальная MCP-сессия: initialize → list → build → inspect/capture → undo; параллельный клиент видит результат.

Выход: законченный цикл автоматизированного строительства с проверкой результата.

## Этап 4. Контент и двусторонняя совместимость

- Проверить полный источник каталога именно Java 26.2; генерировать воспроизводимо, хранить происхождение и версию данных.
- Реализовать формы, коллизии и отображение семейств блоков; отдельно учитывать неподдерживаемые особенности. Базовые определения сущностей и сохраняемые свойства.
- Импорт Anvil/NBT по частям с ограниченным бюджетом памяти; обработка измерений и дополнительного NBT.
- Экспорт мира в целевую версию; режим точности и явных замен, sidecar для неподдерживаемых данных, корректное инвалидирование происхождения после правок.
- `.schem` import/export; тестовые fixtures; повторное открытие экспортированных данных независимым читателем и, при доступности целевой игры, самой игрой.

Выход: проверенный обмен заявленными данными с отчётом покрытия. Полный каталог имён без форм/данных не закрывает этот этап.

## Этап 5. Единые пакеты и законченная миниигра

- Версионированный манифест с зависимостями, клиентскими/серверными частями, размерами, хешами, лицензиями и возможностями.
- Небольшой собственный базовый набор ассетов. Проверяемая загрузка клиентских ресурсов и кэш; обязательные ресурсы отделены от необязательного качества.
- Первое расширение через единый формат, работающий клиентский и серверный сценарий. Декларативная конфигурация не называется полноценной средой произвольных модулей.
- Spleef: ожидание → отсчёт → игра → выбывание → победитель → сброс. Несколько независимых арен используют общую карту.
- Повторные матчи, отключения, вход во время игры, переход в лобби, сохранение настроек после перезапуска.

Выход: друзья могут сыграть законченный матч, а другой разработчик — добавить документированное расширение.

## Этап 6. Приёмка, измерения и поставка

- Проверить все критерии `ACCEPTANCE.md`; отдельный список фактического покрытия и ограничений.
- Измерить RSS/пик памяти, хранение секций, кэши, сетевые очереди, p95/p99 тика, поведение после многократных матчей и перезапуска.
- Сравнение с Paper проводить только при доступном сопоставимом стенде. До этого публиковать собственные числа без заявлений о кратности выигрыша.
- Инструкции запуска, конфигурация MCP, описание API/формата пакетов, лицензии, контрольная сумма исходного архива, Git-коммит.
- Продакшен-публикация и изменение лаунчера — отдельная интеграционная работа после локальной проверки.

Выход: воспроизводимый локальный релиз MVP с честным отчётом, исходным архивом и известными ограничениями.

## Рабочий порядок после планирования

Сначала этап 1. Параллельно с ним можно готовить протокол и клиент по согласованному контракту, изучать каталог/конвертер. Подключение этих частей, изменения общих интерфейсов и проверки выполняются последовательно. После каждого этапа — сохранить результат; не оставлять единственную копию в одноразовой среде.