implementation-plan.md

Implementation Plan

Status: active working plan for the first playable graybox. This document converts the design docs into buildable milestones and acceptance checks.

Current Progress

• Completed: git repo initialization, Cargo workspace scaffold, sim_core, app_bevy, initial content files, JSON save/load snapshotting, deterministic hashing, regression tests, and a scripted golden-path scenario test
• Completed: app_headless runner for no-GPU simulation, scenario listing, and validated save/load execution
• Completed: cargo test and cargo clippy --workspace --all-targets -- -D warnings
• Completed: graybox client baseline with mouse-assisted active-slice placement, selection, inspect/readout panels, inventory/objective HUD, machine toggle/build-recipe controls, explicit machine diagnostics, selected-network connectivity overlay, contamination/support overlays, port/facing markers, multi-cell placement ghosts, scenario switching, and debug save/load controls
• Completed: app_headless now exposes a JSON observation/command/trace surface for agent playtesting and automated debugging, built directly on sim-owned reports instead of client-only state
• Completed: app_headless JSON output now supports summary, inspect, and full payload profiles so automated tooling can avoid hauling full save snapshots when they are not needed
• Completed: support rules are now enforced on removal/rotation, not only on placement
• Completed: objective definitions now support more than one victory shape
• Completed: sim-owned port-link reporting now drives inspect-panel route/link tracing instead of client-side compatibility guesses
• Completed: sim-owned part status/support/link summaries now drive the HUD and inspect readout instead of client-side aggregation
• Completed: sim-owned upstream/downstream item-path tracing now explains starvation and congestion chains across multiple parts
• Completed: the Bevy client now uses solid graybox cube meshes with active-slice emphasis and slice-view modes instead of debug-only wireframe cell rendering
• Completed: slice changes now animate with eased cut-plane motion and layer fade transitions instead of abrupt floor popping
• Completed: slice presentation now keeps faint structural hints above the active floor while suppressing above-layer arrows/highlights, and persistent part visuals now clean up explicitly on removal
• Completed: part rendering now has a persistent visual layer with optional per-machine GLB scene references and cube fallback, so Blender blockouts can be swapped in without relying on full-frame part respawns
• Completed: the first_slice scenario now has a stepwise tutorial that advances from authoritative sim progress and highlights current target nodes/parts in-world
• Completed: the default Bevy HUD/inspect flow has been reduced to a slimmer layout, with detailed controls/help moved behind explicit toggles
• Completed: inspect/readout now states port directions explicitly, and power-link reporting matches the actual wire-only power rules
• Completed: belts now accept item input from back/side faces while keeping a single forward output direction, enabling turns without a separate corner-belt part
• Completed: tutorial targets now use volumetric highlight shells, and machine cells get simple contact pads to read support contact without full dynamic shadows
• Completed: playtest-driven usability pass increased starter belt/wire budgets, added hold-to-rotate camera controls, and added optional ghost placement hints for stuck states
• Completed: player-facing UI pass converted the floating text layout into calmer panel cards, reduced always-on HUD noise, and made tutorial/help content mutually focused instead of stacked
• Completed: the client now exposes a dedicated build palette panel with hotbar inventory counts and a persistent placement-block explanation instead of relying only on transient status text
• Completed: the build palette now expands into selected-part details, and the inspect panel now surfaces selected-machine configuration options more explicitly for the current slice
• Completed: contained visual identity pass pushed the graybox toward warm industrial machineworks with earthy bio accents across machines, resources, overlays, lighting, and UI palette
• Completed: macOS runtime defaults now prefer Metal and a low-power adapter while keeping Bevy/wgpu environment overrides intact
• Completed: the Bevy HUD now reports the active renderer backend, device type, and adapter name at runtime
• Completed: repo documentation now includes a blockout-art contract and a content authoring guide for adding machines, items, and scenarios without reverse-engineering the schemas
• Completed: graybox visuals now include lightweight placement-drop and conveyor-flow pulse animation to improve readability without adding simulation complexity
• Completed: the Bevy client now has a minimal product shell with a start page, persistent world instances, metadata-backed world lists, manual save, autosave, and direct scenario preview bypass
• Completed: the Bevy client now has a cinematic full-factory view that widens the camera, reveals all layers, and hides the in-game panels for cleaner showcase shots
• Completed: three handcrafted scenarios now load and each has scripted completion coverage in sim_core
• Completed: save/load now rebuilds derived occupancy/power/diagnostic state and rejects invalid snapshots during load
• Completed: local compile-time/runtime launch verification up to Bevy renderer startup; sandboxed GPU access remains environment-limited
• Next focus: treat the shell as baseline-complete, run a real balance pass, then begin the first constrained asset swap pass and return to broader playtest iteration

Target Endpoint

Deliver a playable internal graybox in 4-6 weeks that proves:

• dense 3D layouts are readable and satisfying to build
• the core machine loop is fun enough to iterate on
• the simulation model is deterministic enough for command tests and save/load

The milestone is for internal use and a small number of testers, not for public presentation.

End-State Definition

The repository should contain:

• a Cargo workspace with separate simulation and Bevy app crates
• a headless runtime path for no-GPU execution and CI-style scenario runs
• data-driven machine, resource, recipe, and scenario definitions
• one or more handcrafted scenarios with clear win conditions
• deterministic simulation tests and save/load round-trip tests
• a playable graybox client with slice controls, placement, basic overlays, and debug save/load
• a minimal product shell with persistent world saves and a start page

Workstreams

1. Project skeleton

Deliverables:

• workspace Cargo.toml complete
• crates/sim_core complete
• crates/app_bevy complete
• crates/app_headless complete
• assets/data for machine, resource, recipe, and scenario content complete

Definition of done:

• cargo test runs for the workspace
• cargo run -p app_headless can load and advance scenarios without graphics
• cargo run -p app_bevy boots a window and loads content successfully where GPU access is available

2. Authoritative simulation

Deliverables:

• grid and occupancy model complete
• support validation complete
• post-placement support enforcement on removal/rotation complete
• machine instances and typed face ports complete
• route segments for belts, lift wheels, and wires baseline complete
• fixed-step tick pipeline complete
• power satisfaction pass baseline complete
• processing and buffering model baseline complete
• contamination field update logic baseline complete
• command application layer complete

Definition of done:

• the simulation can place, remove, rotate, configure, and tick machines
• identical command streams produce identical final state hashes

3. Data-driven content

Deliverables:

• RON schemas for resources, machines, recipes, build recipes, and scenarios complete
• initial content set for the first playable baseline complete
• objective variants in scenario content baseline complete
• validation checks for malformed or inconsistent data baseline complete

Definition of done:

• all first-slice content loads from external files
• broken content fails with actionable errors

4. Scenario and progression slice

Deliverables:

• one handcrafted map baseline complete
• second handcrafted map to pressure-test data and layout assumptions baseline complete
• third handcrafted map with a different vertical routing constraint baseline complete
• ore and biomass source placement complete
• starter construction kit complete
• Fabricator-based expansion using stabilized_plate baseline complete
• task prompts for early onboarding data complete, client presentation pending
• stepwise first-slice tutorial with in-world highlights baseline complete
• victory evaluation baseline complete

Definition of done:

• the player can start from the scenario state, expand the factory, and reach the objective without hidden/manual state edits

5. Bevy client

Deliverables:

• orbit camera baseline complete
• slice up/down complete
• hide-above behavior complete
• placement ghost and blocked feedback baseline complete
• machine selection and hover state complete
• time controls complete
• connectivity overlay baseline complete
• selected-network context in connectivity overlay baseline complete
• throughput overlay with explicit blocked/starved/unpowered coloring baseline complete
• contamination overlay baseline complete
• support overlay baseline complete
• inventory/objective/inspect HUD complete
• compact HUD plus optional tutorial/help panel baseline complete
• mouse-assisted placement on active slice complete
• selected-machine toggle/build recipe controls complete
• per-part diagnostics surfaced in inspect/HUD complete
• inspect panel port-link tracing for immediate route debugging baseline complete (simulation-owned)
• sim-owned state/link/support summary feeding HUD and inspect views baseline complete
• sim-owned end-to-end item-path tracing for selected-part bottleneck inspection baseline complete
• objective display supports multiple victory shapes baseline complete
• port/facing markers for selected, hovered, and ghosted machines baseline complete
• multi-cell placement ghost complete
• runtime scenario switching and startup scenario selection baseline complete
• runtime scenario reload of the current map baseline complete
• debug save/load controls complete
• persistent-world save layout plus start-page world/session flow baseline complete
• headless scenario execution and validated save/load entrypoint baseline complete
• JSON observation output, JSON command scripts, and JSONL trace export for app_headless baseline complete
• persistent part visuals with optional GLB scene swap and cube fallback baseline complete
• lightweight placement-drop and transport pulse animation baseline complete

Definition of done:

• a tester can build a working multi-level factory and diagnose failures using the client alone

6. Testing and validation

Deliverables:

• unit tests for placement, support, routing, power, processing, contamination, objectives, and fabrication partial
• regression tests for upstream starvation and downstream congestion tracing baseline complete
• save/load round-trip coverage plus validated rehydration checks complete
• deterministic command-log coverage complete
• scripted golden-path tests for each current scenario complete

Definition of done:

• the core simulation has enough automated coverage to refactor without blind breakage

Recommended Build Order

1. Scaffold the workspace and crate boundaries
2. Implement core math and grid primitives
3. Implement content loading and validation
4. Implement command application and placement rules
5. Implement power, item routes, and machine processing
6. Implement contamination and fabrication economy
7. Add save/load and deterministic hashing/tests
8. Boot the Bevy client and render a minimal scene from loaded content
9. Add placement UX, slicing, selection, and overlays
10. Tune the handcrafted scenario until the core loop is readable and completable

Explicit Defaults

• sim_core is authoritative; the Bevy client only mirrors state
• belts and lift wheels show visible route items; machine internals stay buffered and abstract
• only one explicit power family exists in the first playable
• contamination is a soft pressure, not a hard fail gate
• Fabricator outputs to a global build inventory, not physical machine-part items
• save/load is exposed through debug controls, not a polished menu

Out Of Scope For This Milestone

• enemies or combat
• first-person/avatar mode
• procedural generation
• fluids or gas logistics
• scripting/automation programming
• multiplayer
• public-demo polish pass

Immediate Next Tasks

1. Expand the simulation test suite around more lift-wheel edge cases and objective timing edge cases
2. Add more in-client controls for future configurable machines beyond the Fabricator
3. Run a first balancing pass on scenario starter inventories, build costs, and cycle timings after manual playtesting on both app_bevy and app_headless
4. Finish the pre-asset UI pass documented in docs/pre-asset-ui-pass.md
5. Start replacing graybox cubes with constrained GLB blockouts using the art spec, beginning with belt, mixer, and dynamo