Emil_Shanaty/shacraft-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: present Shacraft Core and its documentation in English

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files
docs/VERIFICATION.md
+26 -26
View File
@@ -1,8 +1,8 @@
# Проверка локального MVP
# Local MVP verification
Дата: 2026-09-14. Стенд: Linux x86_64, AMD Ryzen 7 1700, Rust/Cargo 1.96.0, Node 22.22.3, Python 3.14.4. Точные версии — [environment.json](verification/environment.json). Исходная ревизия выпуска фиксируется в `RELEASE.json` каждого архива.
Date: 2026-09-14. Test environment: Linux x86_64, AMD Ryzen 7 1700, Rust/Cargo 1.96.0, Node.js 22.22.3, Python 3.14.4. Exact versions are recorded in [environment.json](verification/environment.json). Each release archive records its source revision in `RELEASE.json`. The verified implementation is `b6ba064`; the subsequent English documentation update does not alter runtime files. Raw machine reports and historical command output are preserved as recorded.
## Автоматические проверки
## Automated checks
```bash
bash scripts/verify.sh
@@ -12,49 +12,49 @@ node scripts/check_mcp.mjs --binary target/release/shacraft-server --output arti
node scripts/benchmark_server.mjs --binary target/release/shacraft-server --output artifacts/server-benchmark-final.json
```
`verify.sh` завершился с кодом 0: fmt, Clippy `-D warnings`, **84 Rust-теста** (core 30, content 11, compat 17, MCP 8, server/WASM 18), **6 JS-тестов**, отдельная аварийная проверка хранилища и debug HTTP/WebSocket-сценарий. [Полный журнал](verification/mvp-checks.txt).
`verify.sh` exited with code 0: formatting, Clippy with `-D warnings`, **84 Rust tests** (core 30, content 11, compat 17, MCP 8, server/WASM 18), **6 JavaScript tests**, a separate storage crash check, and debug HTTP/WebSocket scenarios. [Full log](verification/mvp-checks.txt).
Release-прогон прошёл **14 групп**: проверка ресурсов/авторизации, несовместимый manifest, два клиента, авторитетное движение, недостижимая правка, реальные break/place, последовательные ревизии, late join, immutable template/изоляция, чат, события сущностей, reconnect, полный Spleef и reset, удаление отключённых игроков, **SIGKILL → восстановление блоков, свойств сущностей и настроек**. [Отчёт](verification/server-e2e.json).
The release run passed **14 scenario groups**, covering resource/authentication checks, an incompatible manifest, two clients, authoritative movement, unreachable edits, real break/place actions, sequential revisions, late join, immutable templates/isolation, chat, entity events, reconnection, complete Spleef and reset, disconnected-player cleanup, and **SIGKILL followed by recovery of blocks, entity properties, and settings**. [Report](verification/server-e2e.json).
Настоящий MCP SDK 1.30.0 прошёл initialize/notification/ping, 17 schemas, 4 resources, prompt, durable edit/replay/conflict/undo, plan/commit/retry, PNG image content, entities CRUD, настройки, metrics/reset. [Отчёт SDK](verification/mcp-sdk.json). Для воспроизведения установить независимый клиент:
The independent MCP SDK 1.30.0 passed initialize/notification/ping, 17 tool schemas, 4 resources, the prompt, durable edit/replay/conflict/undo, plan/commit/retry, PNG image content, entity CRUD, settings, metrics, and reset. [SDK report](verification/mcp-sdk.json). Install the independent client to reproduce this check:
```bash
npm install --prefix artifacts/mcp-sdk --no-package-lock @modelcontextprotocol/sdk@1.30.0
SHACRAFT_MCP_SDK="$PWD/artifacts/mcp-sdk/node_modules/@modelcontextprotocol/sdk" node scripts/check_mcp.mjs --binary target/release/shacraft-server --output artifacts/mcp-sdk.json
```
В репозитории нет зависимости рабочего клиента от Node/MCP SDK. Они нужны только проверке.
The game client does not depend on Node.js or the MCP SDK; they are verification dependencies. The initial published implementation also passed [GitHub Actions](https://github.com/emil28092005/shacraft-core/actions/runs/34857228288).
## Каталог и совместимость
## Catalog and interoperability
Каталог сравнивается с независимой проекцией официальных отчётов по всем каноническим состояниям, properties/defaults и множеству сущностей. Отдельно проверены геометрия, ориентации плит/ступеней/дверей, контекстные случаи, entity dimensions. Повторный полный генератор отчётов/API и авторских ресурсов воспроизвёл файлы побайтно: [reproducibility](verification/catalog-reproducibility.json).
The catalog is compared with an independent projection of the official reports across every canonical state, property/default, and entity type. Geometry, slab/stair/door orientations, contextual cases, and entity dimensions are checked separately. Repeating the full report/API extraction and original asset generation reproduced the files byte for byte: [reproducibility report](verification/catalog-reproducibility.json).
17 converter-тестов покрывают типизированный NBT, compression modes/external chunks, палитры, negative coordinates, unknown data, offset/3D biomes, удаление stale chest data, original checksums, no-overwrite, invalid input, создание/перемещение/удаление сущностей и отдельный entity fingerprint.
The 17 converter tests cover typed NBT, compression modes/external chunks, palettes, negative coordinates, unknown data, offsets/3D biomes, removal of stale chest data, original checksums, no-overwrite behavior, invalid input, entity creation/movement/deletion, and a separate entity fingerprint.
Официальный Java 26.2 прочитал exact (1 chunk, 3 блока, 1 сущность), edited (2 chunks, 3 блока, 1 сущность) и новый экспорт (2 chunks, 2 блока). nbtlib 2.0.4 проверил Sponge-теги и их числовые типы. [Машиночитаемый результат](verification/interop.json), [команды и ограничения](interop.md). Использовались публичные codecs без запуска Minecraft-сервера и без принятия EULA.
The official Java 26.2 codecs read the exact export (1 chunk, 3 blocks, 1 entity), edited export (2 chunks, 3 blocks, 1 entity), and new export (2 chunks, 2 blocks). nbtlib 2.0.4 checked Sponge tags and their numeric types. [Machine-readable results](verification/interop.json), [commands and limits](interop.md). These checks invoked public codecs without launching the Minecraft game/server; they were not gameplay tests.
## Память и тик
## Memory and tick work
Бюджеты записаны в скрипте **до прогона**: 256 МиБ для процесса с 10 клиентами, p95 выборки работы тика ≤50 мс. Полный каталог включён. Один сервер содержит 5 служебных/демонстрационных миров и 1, 10, затем 100 дополнительных immutable forks лобби. Активные этапы: 10 клиентов в одной области общего мира и в отдельных мирах, движение/прыжок с вводом 20 Гц, по 15 секунд; метрики каждые 100 мс. Затем все клиенты отключаются. Linux VmHWM дополнительно фиксирует пик процесса, включая промежутки между выборками.
Budgets were recorded in the script **before the run**: 256 MiB for the server process with 10 clients, and sampled tick-work p95 ≤50 ms. The full catalog was enabled. One server contained 5 built-in/demo worlds and 1, 10, then 100 additional immutable lobby forks. Active phases ran 10 clients in one shared-world region and in separate worlds, with movement/jump input at 20 Hz for 15 seconds each; metrics were sampled every 100 ms. All clients then disconnected. Linux VmHWM also captured the process peak, including intervals between samples.
Финальный прогон:
Final run:
- 1 / 10 / 100 пустующих forks: максимальный RSS **50.28 / 50.35 / 50.50 МиБ**.
- 10 клиентов в общем мире: RSS/VmHWM **57.00 МиБ**, p95 работы тика **9.54 мс**.
- 10 клиентов в 10 мирах: RSS/VmHWM **59.65 МиБ**, p95 **7.33 мс**.
- После отключения: 0 игроков и 0 активных миров; RSS остаётся **59.65 МиБ** из-за удерживаемого кэша/аллокатора. Нулевое число активных миров не означает нулевой RSS.
- Ограничение кэша выполнено во всех выборках, исходящие очереди и активные миры измерены. Оба заранее заданных бюджета пройдены.
- 1 / 10 / 100 idle forks: maximum RSS **50.28 / 50.35 / 50.50 MiB**.
- 10 clients in one shared world: RSS/VmHWM **57.00 MiB**, tick-work p95 **9.54 ms**.
- 10 clients in 10 worlds: RSS/VmHWM **59.65 MiB**, p95 **7.33 ms**.
- After disconnect: 0 players and 0 active worlds; RSS remained **59.65 MiB** because of retained cache/allocator memory. Zero active worlds does not mean zero RSS.
- The cache limit was respected in every sample; outgoing queues and active worlds were measured. Both budgets set before the run passed.
[Полные фазы и исходные выборки](verification/server-benchmark.json). p95 рассчитан по выборке последней работы тика, не по сетевой задержке и не по всей непрерывной последовательности тиков. Это короткий локальный тест движения; нагрузка ванильных механик, тысячи игроков и бесконечные пользовательские миры не включены. С Paper/NeoForge результат не сравнивался.
[Full phases and raw samples](verification/server-benchmark.json). The p95 is calculated from samples of the last tick's work, not network latency or the complete continuous sequence of ticks. This is a short local movement test; vanilla simulation workloads, thousands of players, and unbounded user worlds are not included. No comparison with Paper/NeoForge was performed.
Отдельный storage benchmark этапа 1 сохраняется в [storage-benchmark.json](verification/storage-benchmark.json): 256 уникальных секций, кэш 8, 100 forks, обход сверх кэша и независимые edit/reset. После создания forks число immutable blobs осталось 256. Это синтетический профиль ядра с двумя состояниями, отдельный от полного сервера.
The separate stage-one storage benchmark is preserved in [storage-benchmark.json](verification/storage-benchmark.json): 256 unique sections, a cache of 8, 100 forks, traversal beyond cache capacity, and independent edit/reset operations. The immutable blob count remained 256 after fork creation. This is a synthetic core profile with two block states, separate from the full server benchmark.
## Браузер и поставка
## Browser and distribution
[Браузерный протокол проверки](verification/browser.md) фиксирует реальные снимки/DOM, каталог, неполные формы, сущности, чистое подключение без полного registry, галерею, повторное соединение и проверенный ресурсный кэш. На этом стенде наблюдались 144 FPS; переносить это число на другие устройства нельзя.
The [browser verification record](verification/browser.md) describes real screenshots/DOM inspection, the catalog, partial shapes, entities, a fresh connection without the full registry, the gallery, reconnection, and the verified resource cache. This setup showed 144 FPS; that number should not be extrapolated to other devices.
`python3 scripts/make_release.py` и вариант `--binaries` создают архив из чистого Git-коммита, добавляют `RELEASE.json` с SHA-256 каждого файла и проверяют каждый файл при повторном чтении архива. Соседний `.sha256` проверяет весь архив. Поставка проверяется повторной распаковкой, offline Cargo-проверкой исходников и запуском извлечённого Linux-бинарного файла с ресурсами из архива. Итоговый журнал упаковки находится рядом с архивами в `artifacts/`.
`python3 scripts/make_release.py` and its `--binaries` variant create an archive from a clean Git commit, add `RELEASE.json` with each file's SHA-256, and verify every file by rereading the archive. An adjacent `.sha256` file checks the entire archive. The `b6ba064` source and Linux binary archives were extracted again, every manifest entry was verified, an offline Cargo source check passed with cached dependencies, and the extracted Linux server started successfully using resources from its archive. Its health endpoint, default worlds, client page, and public resource hashes were verified. The packaging and extraction verification reports are stored alongside the local archives under `artifacts/`.
## Границы приёмки
## Acceptance boundaries
Основные рубежи A-CORE/SERVER/CLIENT/MCP/SPLEEF подтверждены перечисленными тестами и браузерным осмотром. B-CONTENT, B-PACKAGES, B-INTEROP, B-PERSISTENCE выполнены в документированном профиле. B-MEMORY подтверждён указанной нагрузкой, а не произвольным масштабом. Более широкие пункты исходного ACCEPTANCE (долгий soak, все игровые контексты Minecraft, все варианты внешних миров и реальный Minecraft-плейтест) не объявляются пройденными. Заявления о полной ванильной симуляции, аппаратной отказоустойчивости или экономии относительно Paper отсутствуют.
The primary A-CORE/SERVER/CLIENT/MCP/SPLEEF milestones are supported by the tests and browser inspection listed above. B-CONTENT, B-PACKAGES, B-INTEROP, and B-PERSISTENCE are implemented within the documented profile. B-MEMORY is supported by the specified workload, not arbitrary scale. The broader items in the original [ACCEPTANCE](ACCEPTANCE.md) document (a long soak, all Minecraft gameplay contexts, all external-world variants, and a real Minecraft playtest) are not claimed as passed. There is no claim of complete vanilla simulation, hardware fault tolerance, or memory savings relative to Paper.