65 lines
3.5 KiB
Markdown
65 lines
3.5 KiB
Markdown
# Development and storage tools
|
|
|
|
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
|
|
|
|
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
|
|
bash scripts/verify.sh
|
|
```
|
|
|
|
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` 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` 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 session
|
|
|
|
```bash
|
|
target/debug/shacraft-tools --data data/manual --cache 8 session
|
|
```
|
|
|
|
Send one JSON command per line:
|
|
|
|
```json
|
|
{"op":"register","state":"shacraft:stone"}
|
|
{"op":"create","name":"world"}
|
|
{"op":"registry"}
|
|
{"op":"revision","world":"world"}
|
|
{"op":"get","world":"world","pos":[-1,0,0]}
|
|
{"op":"stats"}
|
|
```
|
|
|
|
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}]}
|
|
{"op":"undo","world":"world","expected_revision":1,"operation_id":"undo-first","target_operation":"first-stone"}
|
|
{"op":"reset","world":"world","expected_revision":2,"operation_id":"reset-world"}
|
|
```
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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.
|