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.