docs: present Shacraft Core and its documentation in English

This commit is contained in:
Emil
2026-09-14 17:58:30 +03:00
parent b6ba064339
commit 26748912c6
18 changed files with 643 additions and 620 deletions
+22 -22
View File
@@ -1,31 +1,31 @@
# Состояние проекта
# Project status
Обновлено 2026-09-14. Реализован и локально проверен весь согласованный профиль MVP. Рабочая папка: `/home/emil/Desktop/shacraft-core`. Исходный план сохранён до реализации коммитом `ddfcef2`; результаты старой облачной среды не использовались как доказательство.
Updated 2026-09-14. The agreed local MVP profile is implemented and verified. The original plan was committed before implementation as `ddfcef2`; claims from the previous cloud environment were not used as evidence. The verified implementation is commit `b6ba064`, published at [emil28092005/shacraft-core](https://github.com/emil28092005/shacraft-core). Its GitHub Actions run passed. Subsequent documentation changes do not change the runtime.
## Готово
## Implemented
- Самостоятельное ядро 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, сохранение оригинала, атомарная публикация, отчёты о потерях/преобразованиях, перенос игровых правок блоков и сущностей.
- Independent Rust core: compact sections, a bounded shared LRU, durable edits and history, immutable snapshots, independent worlds, revisions/idempotency, undo, and reset.
- Separate authoritative server with a 20 Hz game loop, movement/shape/reach validation, bounded queues, and persistent settings and entities.
- Custom browser WebGL2 client: building, a catalog, players/entities, chat, worlds, package downloads, and diagnostics. It does not depend on an existing game engine. The MVP interface currently uses Russian text; repository documentation is in English.
- Separate stdio MCP server: 17 tools, 4 resources, a building prompt, plans/commit, PNG previews, and verification through an independent MCP SDK.
- Complete Java 26.2 catalog: 1,196 blocks, 32,366 states, 158 entity types, DataVersion 4903. Collision shapes are measured through the source API, rendering templates are independently authored, and contextual cases are marked.
- Packages: exact versions, dependency graphs, SHA-256 hashes/sizes, private server files, and a verified client cache. Working WASM `on_jump`, custom block definitions, and original textures/shader/audio.
- Spleef: two independent arenas sharing a map, countdown, elimination, winner/draw, reset, spectators, persistent rules, and recovery after interruption. A lobby and a gallery of 1,197 samples.
- Anvil and Sponge v3 import/export: typed NBT, original preservation, atomic output publication, loss/conversion reports, and transfer of block and entity edits made in Shacraft.
## Проверено
## Verified
84 Rust-теста, 6 JS-тестов, fmt и Clippy без предупреждений; 14 групп реальных HTTP/WebSocket-сценариев, отдельная MCP SDK-сессия, SIGKILL и восстановление. Экспорты прочитаны официальными Java 26.2 codecs и независимым NBT-читателем. Клиент осмотрен в реальном браузере; подтверждены отрисовка, поиск состояний, переход в галерею, догрузка материалов, повторное соединение и кэш ресурсов.
84 Rust tests, 6 JavaScript tests, formatting, and Clippy without warnings; 14 groups of real HTTP/WebSocket scenarios, a separate MCP SDK session, SIGKILL, and recovery. Exports were read by the official Java 26.2 codecs and an independent NBT reader. The client was inspected in a real browser: rendering, state search, gallery navigation, material loading, reconnection, and resource caching were confirmed.
Финальный release-стенд: 100 пустующих экземпляров карты — 50.50 МиБ RSS; 10 движущихся клиентов — максимум 59.65 МиБ RSS/VmHWM, p95 выборки работы тика 7.33–9.54 мс. Это ограниченный локальный профиль, не сравнение с Paper. Команды и доказательства — [VERIFICATION](VERIFICATION.md).
Final release benchmark: 100 idle map instances used 50.50 MiB RSS; 10 moving clients reached a maximum of 59.65 MiB RSS/VmHWM, with sampled tick-work p95 of 7.33–9.54 ms. This is a bounded local profile, not a comparison with Paper. Commands and evidence are in [VERIFICATION](VERIFICATION.md).
## Точные границы
## Exact boundaries
- Это самостоятельная миниигровая платформа с каталогом 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 не заявляются пройденными.
- Лаунчер, аккаунты, продакшен и существующие серверы — последующая интеграция. Ничего не опубликовано и не развёрнуто на удалённых машинах.
- This is an independent minigame platform with a Minecraft catalog, not a complete vanilla simulation: no full AI, redstone, inventories, or fluid simulation. Context-dependent shapes are marked; models do not reproduce the vanilla assets.
- `exact` conservatively refuses export after edits; `best-effort` reflects changes and produces a report. Anvil and `.schem` conversion does not translate all biome/block-entity semantics; source data is archived. Version, size, and context limits are documented in [interop.md](interop.md).
- Block history is stored on disk without automatic deletion. Undo accepts only the current target edit. Preview plans are ephemeral and expire after five minutes. Entity/rule metadata has its own revision; its API does not claim the core's idempotency journal.
- The playable range with f32 physics is ±32700; storage and conversion support the core's ±30 million coordinates. Several bounded structures control memory use; there is no single hard RSS cap.
- Linux x86_64 and local workloads have been tested. A long production soak, power-loss testing, all operating systems, and an exported-world playtest in a running Minecraft game have not been claimed as passed.
- Launcher integration, accounts, production deployment, and existing servers are future integration work. The source repository is public; the game server has not been deployed to a remote machine.
Контракты компонентов: SERVER.md, MCP.md, CONTENT.md, PACKAGES.md, interop.md. Исходники и release-бинарные файлы упаковывает `scripts/make_release.py`; в архивы не входят токены, локальные миры и Minecraft JAR.
Component contracts: [SERVER](SERVER.md), [MCP](MCP.md), [CONTENT](CONTENT.md), [PACKAGES](PACKAGES.md), and [interop](interop.md). `scripts/make_release.py` packages source and release binaries. Archives exclude tokens, local runtime worlds, and the Minecraft JAR.