docs: present Shacraft Core and its documentation in English

docs/PLAN.md

@@ -1,80 +1,80 @@
-# План разработки
+# Development plan
 
-План составлен до реализации. Каждый этап заканчивается воспроизводимым результатом в локальном репозитории. `docs/STATUS.md` обновляется после проверок. Пункт не считается выполненным по наличию интерфейса, заглушки, каталога имён или успешной компиляции.
+This plan was written before implementation. Each stage ends with a reproducible result in the local repository. `docs/STATUS.md` is updated after verification. An interface, a stub, a catalog of names, or a successful compilation does not make an item complete.
 
-Текущий прогресс: этапы 0–6 реализованы для локального профиля MVP. Компоненты интегрированы; фактические проверки, пределы нагрузки и ограничения совместимости описаны в STATUS и VERIFICATION. Исходный порядок этапов ниже сохранён.
+Current progress: stages 0–6 are implemented for the local MVP profile. The components are integrated; actual checks, load limits, and compatibility limitations are documented in STATUS and VERIFICATION. The original stage order is preserved below.
 
-## Этап 0. Сохранить контекст и проверить проектирование
+## Stage 0. Preserve context and review the design
 
-- Записать исходные требования, решения, контракты и критерии приёмки.
-- Зафиксировать источники данных совместимости и ограничения лицензий.
-- Разделить компоненты так, чтобы можно было независимо разрабатывать хранение, совместимость, сетевой сервер и клиент.
-- Согласовать обработку ошибок, координаты, ревизии, ограничения операций и формат диагностики.
+- Record the original requirements, decisions, contracts, and acceptance criteria.
+- Record compatibility data sources and licensing constraints.
+- Separate the components so that storage, compatibility, the network server, and the client can be developed independently.
+- Agree on error handling, coordinates, revisions, operation limits, and the diagnostic format.
 
-Выход: документы в `docs/`; список решений без молчаливого сокращения объёма.
+Deliverable: documents in `docs/` and a list of decisions, with no silent reduction in scope.
 
-## Этап 1. Ядро и доказуемое управление памятью
+## Stage 1. Core and verifiable memory management
 
-- Rust workspace; координаты с корректными отрицательными значениями; реестр канонических состояний блоков.
-- Секции 16×16×16: единообразное состояние или палитра и упакованные индексы. Отсутствие отдельного объекта на каждый блок.
-- Собственный версионированный формат хранения, ограниченный кэш, выгрузка на диск; операции чтения не изменяют мир.
-- Независимые экземпляры общей карты. Изменение/сброс одного экземпляра не влияет на другие; снимок основы имеет чёткую семантику.
-- Атомарные правки с журналом восстановления, ревизиями и идемпотентностью. История и undo хранятся на диске с ограниченным потреблением RAM.
-- Проверки границ секций, упаковки, изоляции миров, повторов, конфликтов, сохранения и восстановления после сбоя. Измерение хранения общей карты против копий.
+- A Rust workspace; coordinates that handle negative values correctly; a registry of canonical block states.
+- Sections of 16×16×16 cells: a uniform state or a palette with packed indices. No separate object for each block.
+- A custom versioned storage format, bounded cache, and unloading to disk; reads do not modify the world.
+- Independent instances of a shared map. Editing or resetting one instance does not affect others; the base snapshot has precise semantics.
+- Atomic edits with a recovery journal, revisions, and idempotency. History and undo reside on disk with bounded RAM use.
+- Checks for section boundaries, packing, world isolation, retries, conflicts, persistence, and crash recovery. Measurements comparing shared-map storage with copies.
 
-Выход: самостоятельная библиотека и воспроизводимые тесты/измерения. Это ещё не весь MVP.
+Deliverable: an independent library and reproducible tests/measurements. This is not yet the complete MVP.
 
-## Этап 2. Сервер и минимальный клиент — сквозной сценарий
+## Stage 2. Server and minimal client: an end-to-end scenario
 
-- Сервер владеет миром и симуляцией; фиксированный тик, серверные движение/столкновения и проверка взаимодействий.
-- Версионированный протокол: подключение, начальный снимок, изменения блоков, игроки, переход между мирами, ошибки и восстановление подключения.
-- Лимиты числа игроков, радиуса мира, сообщений, частоты действий и очередей. Медленный клиент не увеличивает память сервера без ограничения.
-- Тестовый клиент: собственный рендерер, камера, управление, блоки, простые сущности, состояния соединения. Сервер остаётся без графики.
-- Два независимых клиента видят одинаковые изменения. Перезапуск сохраняет мир. Подключение и выход не оставляют сущности и фоновые задачи.
+- The server owns the world and simulation: a fixed tick, server-side movement/collisions, and interaction validation.
+- A versioned protocol: connection, initial snapshot, block changes, players, world switching, errors, and reconnection.
+- Limits on player count, world radius, messages, action rates, and queues. A slow client cannot increase server memory without bound.
+- A test client with a custom renderer, camera, controls, blocks, simple entities, and connection states. The server remains graphics-free.
+- Two independent clients see the same changes. Restarts preserve the world. Joining and leaving do not leak entities or background tasks.
 
-Выход: запускаемая локальная сетевая песочница. На первом проходе допустим небольшой набор материалов; это не выполнение требования полного каталога.
+Deliverable: a runnable local networked sandbox. A small material set is acceptable on the first pass; it does not satisfy the full-catalog requirement.
 
-## Этап 3. Control API и собственный MCP
+## Stage 3. Control API and dedicated MCP
 
-- Общий API чтения, редактирования, истории и диагностики; MCP — отдельный процесс с stdio.
-- Поиск материалов, чтение ограниченной области, пакетное строительство и шаблоны, preview/commit, undo с защитой от чужих изменений.
-- Ресурсы с системой координат и возможностями; структурированные ответы и понятные ошибки.
-- Визуальная обратная связь: снимок с явно указанными типом отображения и ревизией; топографический preview не объявляется снимком игрового клиента.
-- Тестовые миры, сущности, управление аренами и метрики. Авторизация управляющего API; токен не попадает в клиентский код и журнал.
-- Реальная MCP-сессия: initialize → list → build → inspect/capture → undo; параллельный клиент видит результат.
+- A shared API for reading, editing, history, and diagnostics; MCP runs as a separate process over stdio.
+- Material search, bounded region reads, batch construction and templates, preview/commit, and undo that protects other edits.
+- Resources describing coordinates and capabilities; structured responses and clear errors.
+- Visual feedback: an image with an explicit rendering type and revision; a topographic preview is not presented as a game-client screenshot.
+- Test worlds, entities, arena management, and metrics. Control API authorization; the token never enters client code or logs.
+- A real MCP session: initialize → list → build → inspect/capture → undo; a connected client sees the result.
 
-Выход: законченный цикл автоматизированного строительства с проверкой результата.
+Deliverable: a complete automated construction workflow with verification of the result.
 
-## Этап 4. Контент и двусторонняя совместимость
+## Stage 4. Content and bidirectional compatibility
 
-- Проверить полный источник каталога именно Java 26.2; генерировать воспроизводимо, хранить происхождение и версию данных.
-- Реализовать формы, коллизии и отображение семейств блоков; отдельно учитывать неподдерживаемые особенности. Базовые определения сущностей и сохраняемые свойства.
-- Импорт Anvil/NBT по частям с ограниченным бюджетом памяти; обработка измерений и дополнительного NBT.
-- Экспорт мира в целевую версию; режим точности и явных замен, sidecar для неподдерживаемых данных, корректное инвалидирование происхождения после правок.
-- `.schem` import/export; тестовые fixtures; повторное открытие экспортированных данных независимым читателем и, при доступности целевой игры, самой игрой.
+- Verify the complete catalog source specifically for Java 26.2; generate it reproducibly and retain data provenance and version.
+- Implement shapes, collisions, and rendering for block families; track unsupported features separately. Base entity definitions and persistent properties.
+- Import Anvil/NBT in chunks with a bounded memory budget; handle dimensions and additional NBT.
+- Export worlds to the target version; an accuracy mode and explicit substitutions, sidecars for unsupported data, and correct provenance invalidation after edits.
+- `.schem` import/export; test fixtures; reopen exports with an independent reader and, when the target game is available, with the game itself.
 
-Выход: проверенный обмен заявленными данными с отчётом покрытия. Полный каталог имён без форм/данных не закрывает этот этап.
+Deliverable: verified interchange of the declared data with a coverage report. A complete list of names without shapes/data does not complete this stage.
 
-## Этап 5. Единые пакеты и законченная миниигра
+## Stage 5. Unified packages and a complete minigame
 
-- Версионированный манифест с зависимостями, клиентскими/серверными частями, размерами, хешами, лицензиями и возможностями.
-- Небольшой собственный базовый набор ассетов. Проверяемая загрузка клиентских ресурсов и кэш; обязательные ресурсы отделены от необязательного качества.
-- Первое расширение через единый формат, работающий клиентский и серверный сценарий. Декларативная конфигурация не называется полноценной средой произвольных модулей.
-- Spleef: ожидание → отсчёт → игра → выбывание → победитель → сброс. Несколько независимых арен используют общую карту.
-- Повторные матчи, отключения, вход во время игры, переход в лобби, сохранение настроек после перезапуска.
+- A versioned manifest with dependencies, client/server parts, sizes, hashes, licenses, and capabilities.
+- A small set of original base assets. Verified client resource downloads and caching; required resources are separate from optional quality enhancements.
+- The first extension through the unified format, with working client and server behavior. Declarative configuration is not described as a full environment for arbitrary modules.
+- Spleef: waiting → countdown → play → elimination → winner → reset. Multiple independent arenas use a shared map.
+- Repeated matches, disconnects, joining during play, returning to the lobby, and settings that survive restarts.
 
-Выход: друзья могут сыграть законченный матч, а другой разработчик — добавить документированное расширение.
+Deliverable: friends can play a complete match, and another developer can add an extension through a documented interface.
 
-## Этап 6. Приёмка, измерения и поставка
+## Stage 6. Acceptance, measurements, and delivery
 
-- Проверить все критерии `ACCEPTANCE.md`; отдельный список фактического покрытия и ограничений.
-- Измерить RSS/пик памяти, хранение секций, кэши, сетевые очереди, p95/p99 тика, поведение после многократных матчей и перезапуска.
-- Сравнение с Paper проводить только при доступном сопоставимом стенде. До этого публиковать собственные числа без заявлений о кратности выигрыша.
-- Инструкции запуска, конфигурация MCP, описание API/формата пакетов, лицензии, контрольная сумма исходного архива, Git-коммит.
-- Продакшен-публикация и изменение лаунчера — отдельная интеграционная работа после локальной проверки.
+- Check every criterion in `ACCEPTANCE.md`; keep a separate record of actual coverage and limitations.
+- Measure RSS/peak memory, section storage, caches, network queues, p95/p99 tick time, and behavior after repeated matches and restarts.
+- Compare with Paper only when a comparable test setup is available. Until then, publish the project's own figures without claims about multiplicative improvements.
+- Startup instructions, MCP configuration, API/package-format documentation, licenses, the source archive checksum, and the Git commit.
+- Production publishing and launcher changes are separate integration work after local verification.
 
-Выход: воспроизводимый локальный релиз MVP с честным отчётом, исходным архивом и известными ограничениями.
+Deliverable: a reproducible local MVP release with an accurate report, a source archive, and known limitations.
 
-## Рабочий порядок после планирования
+## Working order after planning
 
-Сначала этап 1. Параллельно с ним можно готовить протокол и клиент по согласованному контракту, изучать каталог/конвертер. Подключение этих частей, изменения общих интерфейсов и проверки выполняются последовательно. После каждого этапа — сохранить результат; не оставлять единственную копию в одноразовой среде.
+Start with stage 1. Protocol and client preparation against the agreed contract, as well as catalog/converter research, can proceed in parallel. Integrating these parts, changing shared interfaces, and verification happen sequentially. Save the result after every stage; do not leave the only copy in a disposable environment.