docs: present Shacraft Core and its documentation in English
This commit is contained in:
Emil
+16
-17
@@ -1,43 +1,42 @@
|
||||
# Разработка и воспроизведение первого этапа
|
||||
# Development and storage tools
|
||||
|
||||
Это инструменты проверки хранилища. Здесь ещё нет игрового сервера, графического клиента или MCP. Локальный JSON-lines интерфейс CLI не является MCP.
|
||||
This guide documents the storage tools introduced in the first implementation stage. The current workspace also includes a game server, graphical client, and MCP server; see [README](../README.md) and [STATUS](STATUS.md). The local JSON-lines CLI described below is a storage development interface, not MCP.
|
||||
|
||||
## Сборка и проверки
|
||||
## Build and checks
|
||||
|
||||
Нужны Rust/Cargo 1.96.0, C-компилятор для bundled SQLite, Python 3 для проверки аварийного завершения. После загрузки зависимостей `Cargo.lock` фиксирует их версии.
|
||||
Requirements: Rust/Cargo 1.96.0, a C compiler for bundled SQLite, Python 3 for crash testing, and Node.js 22+ for JavaScript and network checks. `Cargo.lock` pins dependency versions. Run these commands from the repository root:
|
||||
|
||||
```bash
|
||||
cd /home/emil/Desktop/shacraft-core
|
||||
bash scripts/verify.sh
|
||||
```
|
||||
|
||||
Проверка запускает форматирование, Clippy, Rust-тесты, сборку CLI и отдельные процессы. `check_storage.py` создаёт только временные миры и принудительно завершает только собственный дочерний процесс.
|
||||
The script checks formatting, runs Clippy and Rust tests, builds the workspace, and runs storage crash checks, JavaScript tests, and HTTP/WebSocket scenarios. `check_storage.py` creates temporary worlds and forcibly terminates only its own child process.
|
||||
|
||||
## Демонстрация хранения
|
||||
## Storage demonstration
|
||||
|
||||
```bash
|
||||
cargo run -p shacraft-tools -- --data data/demo demo
|
||||
cargo run -p shacraft-tools -- --data data/demo stats
|
||||
```
|
||||
|
||||
`demo` требует пустое хранилище. Создаёт карту пола и два независимых экземпляра, изменяет один, проверяет изоляцию, выполняет undo и reset. Повторный запуск в непустой каталог отклоняется. Для нового прогона укажите другое имя каталога.
|
||||
`demo` requires an empty store. It creates a floor map and two independent instances, edits one, checks isolation, and exercises undo and reset. Running it again in a nonempty directory is rejected. Use a new directory name for another run.
|
||||
|
||||
## Измерение
|
||||
## Measurement
|
||||
|
||||
```bash
|
||||
cargo build --release -p shacraft-tools
|
||||
target/release/shacraft-tools --data data/bench-001 --cache 8 benchmark --sections 256 --worlds 100
|
||||
```
|
||||
|
||||
`benchmark` также требует пустое хранилище. Он создаёт 256 различных секций, 100 экземпляров, проходит по данным сверх вместимости кэша и изменяет/сбрасывает каждый экземпляр. В JSON выводятся отдельные измерения RSS/пика всего процесса (на Linux), метрики хранения, длительности и размеры файлов. Данные теста синтетические; игроков, сетевого тика и фоновой симуляции нет. Эти числа не доказывают выигрыш относительно Paper.
|
||||
`benchmark` also requires an empty store. It creates 256 distinct sections and 100 instances, traverses more data than the cache can hold, and edits/resets each instance. Its JSON output separates whole-process RSS/peak measurements on Linux, storage metrics, durations, and file sizes. This is synthetic test data: no players, network ticks, or background simulation. These numbers do not establish an advantage over Paper.
|
||||
|
||||
## JSON-lines сессия
|
||||
## JSON-lines session
|
||||
|
||||
```bash
|
||||
target/debug/shacraft-tools --data data/manual --cache 8 session
|
||||
```
|
||||
|
||||
По одной JSON-команде на строку:
|
||||
Send one JSON command per line:
|
||||
|
||||
```json
|
||||
{"op":"register","state":"shacraft:stone"}
|
||||
@@ -48,7 +47,7 @@ target/debug/shacraft-tools --data data/manual --cache 8 session
|
||||
{"op":"stats"}
|
||||
```
|
||||
|
||||
Сначала получите реальный ID блока и текущую ревизию, затем передайте их в `edit`:
|
||||
First obtain the actual block ID and current revision, then pass them to `edit`:
|
||||
|
||||
```json
|
||||
{"op":"edit","world":"world","expected_revision":0,"operation_id":"first-stone","changes":[{"pos":[-1,0,0],"block":1}]}
|
||||
@@ -56,10 +55,10 @@ target/debug/shacraft-tools --data data/manual --cache 8 session
|
||||
{"op":"reset","world":"world","expected_revision":2,"operation_id":"reset-world"}
|
||||
```
|
||||
|
||||
ID 1 в этом примере допустим только если ответ регистрации действительно вернул 1. Ответ каждой команды имеет `ok` и `result` либо `error`. Успешный ответ записи выдаётся после возврата долговечного API. Максимальная входная строка — 8 MiB; ограничения на число блоков и объём области действуют дополнительно.
|
||||
ID 1 is valid in this example only if registration actually returned 1. Each response contains `ok` and either `result` or `error`. A successful write response is sent after the durable API returns. The maximum input line is 8 MiB; block-count and region-volume limits also apply.
|
||||
|
||||
## Продолжение разработки
|
||||
## Further development
|
||||
|
||||
Прочитайте STATUS и PLAN. Новые компоненты добавляйте в workspace только вместе с реализацией и командами проверки. Не создавайте пустые исполняемые файлы, которые лишь выводят «готово». Публичный протокол пока проектируется в CONTRACT; окончание первого этапа хранения не закрывает последующие этапы.
|
||||
Read [STATUS](STATUS.md) and [PLAN](PLAN.md). Add workspace components together with their implementation and verification commands. Do not add empty executables that merely print a success message. Current API boundaries are documented in [CONTRACT](CONTRACT.md) and the component-specific documents; completing the storage stage alone does not establish completion of subsequent stages.
|
||||
|
||||
Для живого SQLite-хранилища нельзя считать копию одного `worlds.sqlite3` полной резервной копией: актуальные данные могут быть в WAL. Перед ручным копированием остановите владеющий процесс либо используйте будущий согласованный backup API. Исходный архив проекта намеренно не содержит рабочие миры.
|
||||
Copying only `worlds.sqlite3` from a live SQLite store is not a complete backup: current data may still be in the WAL. Stop the owning process before manually copying it, or use a future coordinated backup API. Source archives intentionally exclude runtime worlds.
|
||||
|
||||
Reference in New Issue
Block a user