# 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.