Complete local voxel MVP with server, client, MCP, packages and world interchange

This commit is contained in:
Emil
2026-09-14 17:35:17 +03:00
parent cf8d1aae2e
commit b6ba064339
98 changed files with 58116 additions and 194 deletions
+21 -39
View File
@@ -1,49 +1,31 @@
# Состояние проекта
Обновлено: 2026-09-14. Рабочая папка: `/home/emil/Desktop/shacraft-core`.
Обновлено 2026-09-14. Реализован и локально проверен весь согласованный профиль MVP. Рабочая папка: `/home/emil/Desktop/shacraft-core`. Исходный план сохранён до реализации коммитом `ddfcef2`; результаты старой облачной среды не использовались как доказательство.
## Завершено: планирование и первый этап хранения
## Готово
План сохранён **до реализации**, отдельным Git-коммитом `ddfcef2`. Исходники старой облачной среды не восстановлены и не использованы как доказательство работы новой реализации.
- Самостоятельное ядро Rust: компактные секции, общий ограниченный LRU, долговечные правки и история, immutable snapshots, независимые миры, revision/idempotency, undo/reset.
- Отдельный авторитетный сервер с игровым циклом 20 Гц, проверкой движения/форм/дальности, ограниченными очередями, сохраняемыми настройками и сущностями.
- Собственный браузерный WebGL2-клиент: строительство, каталог, игроки/сущности, чат, миры, загрузка пакетов и диагностика. Нет зависимости от готового игрового движка.
- Настоящий отдельный stdio MCP: 17 инструментов, 4 ресурса, строительный prompt, планы/commit, визуальный PNG и проверка через независимый MCP SDK.
- Полный каталог Java 26.2: 1 196 блоков, 32 366 состояний, 158 сущностей, DataVersion 4903. Коллизии измерены через официальный API, модели авторские; контекстные случаи отмечены.
- Пакеты: точные версии, граф зависимостей, SHA-256/размеры, приватные серверные файлы, проверяемый клиентский кэш. Действующий WASM `on_jump`, пользовательские определения блоков и собственные текстуры/шейдер/звук.
- Spleef: две независимые арены общей карты, отсчёт, выбывание, победитель/ничья, сброс, spectators, сохраняемые правила, восстановление после прерывания. Лобби и галерея 1 197 образцов.
- Anvil и Sponge v3 import/export: типизированный NBT, сохранение оригинала, атомарная публикация, отчёты о потерях/преобразованиях, перенос игровых правок блоков и сущностей.
Работают две crate:
## Проверено
- `shacraft-core`: versioned codec секций 16³ (uniform/palette/dense), компактный LRU, долговечный реестр, SQLite/WAL/FULL, блокировка второго писателя, неизменяемые снимки, независимые экземпляры, атомарные edit, revision/idempotency, undo/reset и явная уборка недостижимых blobs.
- `shacraft-tools`: локальная JSON-lines сессия для тестирования API, demo, stats и воспроизводимый storage benchmark. Это не MCP и не игровой сервер.
84 Rust-теста, 6 JS-тестов, fmt и Clippy без предупреждений; 14 групп реальных HTTP/WebSocket-сценариев, отдельная MCP SDK-сессия, SIGKILL и восстановление. Экспорты прочитаны официальными Java 26.2 codecs и независимым NBT-читателем. Клиент осмотрен в реальном браузере; подтверждены отрисовка, поиск состояний, переход в галерею, догрузка материалов, повторное соединение и кэш ресурсов.
Проверено на Linux x86_64 с Rust 1.96.0:
Финальный release-стенд: 100 пустующих экземпляров карты — 50.50 МиБ RSS; 10 движущихся клиентов — максимум 59.65 МиБ RSS/VmHWM, p95 выборки работы тика 7.33–9.54 мс. Это ограниченный локальный профиль, не сравнение с Paper. Команды и доказательства — [VERIFICATION](VERIFICATION.md).
- `cargo fmt` и Clippy с запретом предупреждений.
- 29 Rust-тестов: 11 codec, 8 black-box контрактов, 10 хранения.
- Отдельные процессы: 80 подтверждённых правок → SIGKILL → восстановление реестра/данных/replay; прерывание транзакции на 32768 ячеек → отсутствие частичного состояния → безопасный повтор.
- Вытеснение различных секций при превышении кэша; однородная секция остаётся компактной и в RAM.
- Release demo и синтетический benchmark: 256 секций, 100 независимых экземпляров, чтение сверх кэша, edit/reset каждого экземпляра.
## Точные границы
Команды и результаты: [DEVELOPMENT](DEVELOPMENT.md), [VERIFICATION](VERIFICATION.md), `docs/verification/`.
- Это самостоятельная миниигровая платформа с каталогом Minecraft, не полная ванильная симуляция: нет полного AI, redstone, инвентарей или симуляции жидкостей. Формы с зависимостью от контекста помечены; модели не повторяют ванильные ассеты.
- `exact` консервативно отказывает после правок; `best-effort` отражает изменения и выдаёт отчёт. Между Anvil и `.schem` не вся семантика биомов/block entities преобразуется — исходные данные архивируются. Ограничения версий, размеров и контекстов описаны в interop.md.
- История блоков хранится на диске без автоматического удаления. Undo допускает только текущую целевую правку. Preview-планы эфемерны, 5 минут. Метаданные сущностей/правил имеют отдельную ревизию; их API не заявляет журнал идемпотентности ядра.
- Предел игрового пространства с f32-физикой — ±32700; хранение и конвертер поддерживают координаты ядра ±30 миллионов. Память ограничивается несколькими структурами, а не одним магическим RSS-лимитом.
- Проверены Linux x86_64 и локальная нагрузка. Длительный продакшен soak, аппаратное отключение питания, все ОС и игровой плейтест экспорта в запущенном Minecraft не заявляются пройденными.
- Лаунчер, аккаунты, продакшен и существующие серверы — последующая интеграция. Ничего не опубликовано и не развёрнуто на удалённых машинах.
## Следующий этап: сервер и тестовый клиент
1. Добавить crate сервера с игровым циклом отдельно от долговечных редакторских транзакций. Не выполнять SQL/FULL commit каждого игрового ввода.
2. Уточнить протокол resync, подписку без разрыва между снимком и изменениями, переключение миров и лимиты очередей.
3. Реализовать серверные движение/коллизии/взаимодействия и минимальный WebGL2-клиент по решению D003.
4. Пройти сценарий двух клиентов с общими блоками и независимыми мирами.
5. Затем подключить собственный MCP через общий Control API, полный каталог и конвертер согласно PLAN.
## Ограничения первого этапа
- Полный MVP ещё не завершён. Нет игрового сервера, графического клиента, MCP, каталога 26.2, конвертера, системы исполняемых модулей и миниигры.
- Undo консервативный: только целевая правка на текущей ревизии, без последующих операций. Каждый новый успешный edit, включая no-op, повышает ревизию. Retry не повышает.
- История остаётся на диске без автоматического удаления. GC ограничивает число удалённых blobs, но не время сканирования. Он не удаляет историю/снимки и не уменьшает физический файл через VACUUM.
- Реестр строк находится в RAM: максимум 262144 состояния по 512 ASCII-байт. Кэш секций не является лимитом всей памяти процесса. SQLite page-cache budget — настройка движка, не жёсткий RSS-лимит.
- Benchmark проверяет хранение, не игроков/тики/полный каталог и не сравнительную экономию относительно Paper.
- SIGKILL не имитирует отключение питания и отказы накопителя. Платформы вне Linux пока не проверены.
- Продакшен, существующий лаунчер и удалённые репозитории не изменялись.
## Правила продолжения
- Перед работой прочитать REQUIREMENTS, PLAN, DECISIONS, CONTRACT и этот файл.
- Новые результаты подтверждать командами, тестами или видимым поведением; старый облачный отчёт не использовать как доказательство.
- Не помечать весь MVP готовым по завершению одного этапа.
- Отмечать точные ограничения контента, конвертера, клиента, модулей и безопасности.
- Команды запуска и проверки сохранять в репозитории; изменения коммитить в локальный Git после проверки.
- Не помещать токены, данные реальных игроков и проприетарные ассеты в Git и архивы.
Контракты компонентов: SERVER.md, MCP.md, CONTENT.md, PACKAGES.md, interop.md. Исходники и release-бинарные файлы упаковывает `scripts/make_release.py`; в архивы не входят токены, локальные миры и Minecraft JAR.