shacraft-core/docs/PLAN.md

# Development plan

This plan was written before implementation. Each stage ends with a reproducible result in the local repository. `docs/STATUS.md` is updated after verification. An interface, a stub, a catalog of names, or a successful compilation does not make an item complete.

Current progress: stages 0–6 are implemented for the local MVP profile. The components are integrated; actual checks, load limits, and compatibility limitations are documented in STATUS and VERIFICATION. The original stage order is preserved below.

## Stage 0. Preserve context and review the design

- Record the original requirements, decisions, contracts, and acceptance criteria.
- Record compatibility data sources and licensing constraints.
- Separate the components so that storage, compatibility, the network server, and the client can be developed independently.
- Agree on error handling, coordinates, revisions, operation limits, and the diagnostic format.

Deliverable: documents in `docs/` and a list of decisions, with no silent reduction in scope.

## Stage 1. Core and verifiable memory management

- A Rust workspace; coordinates that handle negative values correctly; a registry of canonical block states.
- Sections of 16×16×16 cells: a uniform state or a palette with packed indices. No separate object for each block.
- A custom versioned storage format, bounded cache, and unloading to disk; reads do not modify the world.
- Independent instances of a shared map. Editing or resetting one instance does not affect others; the base snapshot has precise semantics.
- Atomic edits with a recovery journal, revisions, and idempotency. History and undo reside on disk with bounded RAM use.
- Checks for section boundaries, packing, world isolation, retries, conflicts, persistence, and crash recovery. Measurements comparing shared-map storage with copies.

Deliverable: an independent library and reproducible tests/measurements. This is not yet the complete MVP.

## Stage 2. Server and minimal client: an end-to-end scenario

- The server owns the world and simulation: a fixed tick, server-side movement/collisions, and interaction validation.
- A versioned protocol: connection, initial snapshot, block changes, players, world switching, errors, and reconnection.
- Limits on player count, world radius, messages, action rates, and queues. A slow client cannot increase server memory without bound.
- A test client with a custom renderer, camera, controls, blocks, simple entities, and connection states. The server remains graphics-free.
- Two independent clients see the same changes. Restarts preserve the world. Joining and leaving do not leak entities or background tasks.

Deliverable: a runnable local networked sandbox. A small material set is acceptable on the first pass; it does not satisfy the full-catalog requirement.

## Stage 3. Control API and dedicated MCP

- A shared API for reading, editing, history, and diagnostics; MCP runs as a separate process over stdio.
- Material search, bounded region reads, batch construction and templates, preview/commit, and undo that protects other edits.
- Resources describing coordinates and capabilities; structured responses and clear errors.
- Visual feedback: an image with an explicit rendering type and revision; a topographic preview is not presented as a game-client screenshot.
- Test worlds, entities, arena management, and metrics. Control API authorization; the token never enters client code or logs.
- A real MCP session: initialize → list → build → inspect/capture → undo; a connected client sees the result.

Deliverable: a complete automated construction workflow with verification of the result.

## Stage 4. Content and bidirectional compatibility

- Verify the complete catalog source specifically for Java 26.2; generate it reproducibly and retain data provenance and version.
- Implement shapes, collisions, and rendering for block families; track unsupported features separately. Base entity definitions and persistent properties.
- Import Anvil/NBT in chunks with a bounded memory budget; handle dimensions and additional NBT.
- Export worlds to the target version; an accuracy mode and explicit substitutions, sidecars for unsupported data, and correct provenance invalidation after edits.
- `.schem` import/export; test fixtures; reopen exports with an independent reader and, when the target game is available, with the game itself.

Deliverable: verified interchange of the declared data with a coverage report. A complete list of names without shapes/data does not complete this stage.

## Stage 5. Unified packages and a complete minigame

- A versioned manifest with dependencies, client/server parts, sizes, hashes, licenses, and capabilities.
- A small set of original base assets. Verified client resource downloads and caching; required resources are separate from optional quality enhancements.
- The first extension through the unified format, with working client and server behavior. Declarative configuration is not described as a full environment for arbitrary modules.
- Spleef: waiting → countdown → play → elimination → winner → reset. Multiple independent arenas use a shared map.
- Repeated matches, disconnects, joining during play, returning to the lobby, and settings that survive restarts.

Deliverable: friends can play a complete match, and another developer can add an extension through a documented interface.

## Stage 6. Acceptance, measurements, and delivery

- Check every criterion in `ACCEPTANCE.md`; keep a separate record of actual coverage and limitations.
- Measure RSS/peak memory, section storage, caches, network queues, p95/p99 tick time, and behavior after repeated matches and restarts.
- Compare with Paper only when a comparable test setup is available. Until then, publish the project's own figures without claims about multiplicative improvements.
- Startup instructions, MCP configuration, API/package-format documentation, licenses, the source archive checksum, and the Git commit.
- Production publishing and launcher changes are separate integration work after local verification.

Deliverable: a reproducible local MVP release with an accurate report, a source archive, and known limitations.

## Working order after planning

Start with stage 1. Protocol and client preparation against the agreed contract, as well as catalog/converter research, can proceed in parallel. Integrating these parts, changing shared interfaces, and verification happen sequentially. Save the result after every stage; do not leave the only copy in a disposable environment.