Files
Neutron/.planning/ROADMAP.md
T

15 KiB
Raw Blame History

Roadmap: Neutron GamePort

Overview

Complete the remaining original game as faithfully as possible, building on the existing runtime and bounded implementations. Eight delivery boundaries separate reference access, movement ownership, real actor consumers, gadget use, complete progression, player-facing persistence, presentation closure and native acceptance. Each phase uses playable slices: recover the source contract, integrate it into its intended scenario, and verify the resulting behavior. No original-required content is deferred outside this reconstruction.

Delivery and Evidence Rules

  • Preserve the original inventory throughout every phase; use separate generated copies for execution and analysis. Phase 1 owns the preservation baseline; all later phases keep checking it.
  • Every acceptance receipt identifies source/package/resource revision and platform. Static recovery, inference, compilation, copied-original component execution, port runtime, Wine and whole-original/native Windows comparisons are distinct.
  • Reference access and native Windows verification start in Phase 1 and continue throughout. If access is unavailable, keep EVID-02/EVID-04 and affected comparison criteria open. Phase 2 and other independently source-backed recovery may proceed on the available ledger/baseline; this exception does not mark Phase 1 complete or waive final acceptance.
  • Movement stabilization precedes gameplay expansion. Before broader source collision admission, establish actual derived responses, ordered physical membership, helper activation/cleanup and shared mutable reclip. Preserve the lab/outside capsule until its replacement gate closes.
  • The TSK-backed first-story startup-order correction is implemented. Preserve it and legitimate landing bank; do not invent orientation resets or substitute third-party movement tuning.
  • Rendering, audio, menus and persistence needed by an earlier playable slice are integrated there. Their later owning phase closes full-game coverage rather than authorizing temporary invented behavior.
  • Derive comparison tolerances from original evidence per system. Missing comparison evidence stays an acceptance dependency, not a parity claim. REA Evidence and authoritative bytes govern future binary investigations.

Phases

Integer phases are planned work; decimal phases may be inserted for urgent recovered dependencies. Independent investigations may run in parallel with exclusive ownership, while integration follows the dependencies below.

  • Phase 1: Reproducible Fidelity Baseline - Compare identified original and port routes with preserved assets and current native-platform receipts.
  • Phase 2: Faithful Movement and Scene Handoffs - Stabilize Jimmy, real contacts, animation and retained ownership in the integrated lab/tutorial/outside route.
  • Phase 3: Original Actors, Hazards and Combat - Make intended NPC/enemy encounters and their consequences playable.
  • Phase 4: Complete Gadget and Vehicle Use - Acquire and use all original gadgets/vehicles against real consumers across intended lifetimes.
  • Phase 5: Complete Campaign and Optional Routes - Traverse all original-required content and reach original outcomes through normal progression.
  • Phase 6: Original Frontend and Save/Resume - Use original menus/options and resume equivalent gameplay through player-facing persistence.
  • Phase 7: Original Visual and Audible Presentation - Close rendering, playback, camera and sound differences across complete gameplay.
  • Phase 8: Full-Game Native Acceptance and Delivery - Verify standalone Linux/Windows packages against original journeys and publish verified source documentation.

Phase Details

Phase 1: Reproducible Fidelity Baseline

Goal: Testers can reproduce identified original/port comparison scenarios and understand exactly what the current reconstruction proves on each native platform. Mode: mvp Depends on: Nothing (existing codebase and evidence are the starting point). Requirements: EVID-01, EVID-02, EVID-03, EVID-04 Success Criteria (what must be TRUE):

  1. A reviewer can verify every original against the recorded inventory and run investigation/reference copies without altering the original installation.
  2. A tester can reproduce identified whole-original reference scenarios from an isolated generated installation and inspect corresponding input/events, images and audio where applicable; unavailable execution keeps this criterion open.
  3. A reviewer can trace every full-game capability from original evidence through current implementation, platform receipts, discrepancies and its remaining acceptance condition.
  4. Testers can repeat the same baseline movement/route scenarios on native Linux and native Windows with exact revision identities; Wine/cross-publish receipts remain separately labeled and cannot close missing native execution. Plans: 1/7 plans executed Wave 1
  • 01-01-PLAN.md

Wave 2 (blocked on Wave 1 completion)

  • 01-02-PLAN.md
  • 01-03-PLAN.md
  • 01-04-PLAN.md

Wave 3 (blocked on Wave 2 completion)

  • 01-05-PLAN.md

Wave 4 (blocked on Wave 3 completion)

  • 01-06-PLAN.md

Wave 5 (blocked on Wave 4 completion)

  • 01-07-PLAN.md

Phase 2: Faithful Movement and Scene Handoffs

Goal: Players move, contact the world and return from scripts/scenes with the original movement, animation, camera and state ownership intact. Mode: mvp Depends on: Phase 1 baseline/ledger and available reference evidence; independently source-backed work may proceed under the access exception above. Requirements: MOVE-01, MOVE-02, MOVE-03, MOVE-04, MOVE-05 Success Criteria (what must be TRUE):

  1. Players reproduce evidenced Jimmy movement/facing/jump/effect modes using original-supported input devices across tested frame rates without changing significant source arithmetic or timing.
  2. Players and participating bodies experience evidenced static/dynamic support, walls, ceilings and special contacts through real responses; full state/event comparisons establish helper membership, live callback reads and shared reclip before any wider solver admission.
  3. Movement, landing, talk and control changes accept, interrupt and complete actions/animations with the original clocks and outcomes.
  4. Camera/input/control ownership and retained/reset state remain faithful across fresh entry, scripts, pause, LOAD and RETURN, including the implemented TSK startup order and original landing bank.
  5. Players complete lab → VR04 → lab → outside with natural/skipped conversations, banked jumps, held input, landing/idle and gadget cleanup; integrated port/native receipts and available original comparisons identify remaining differences explicitly. Plans: TBD

Phase 3: Original Actors, Hazards and Combat

Goal: Players encounter original NPC/enemy behavior and receive the correct gameplay consequences through real scene interactions. Mode: mvp Depends on: Phase 2; actor-specific membership/response contracts must precede each live admission. Requirements: ACT-01, ACT-02, ACT-03 Success Criteria (what must be TRUE):

  1. Players encounter each original-required NPC/enemy class in its intended scenes with evidenced sensing, movement, action/RNG decisions and animation rather than generic placeholder policies.
  2. Combat and hazards produce original health, damage, immunity, death and recovery outcomes for players and affected actors during normal play.
  3. Real enter/stay/leave and special interactions produce the correct ordered task, score, control and class-specific effects, including callback mutations and repeated contacts. Plans: TBD

Phase 4: Complete Gadget and Vehicle Use

Goal: Players acquire and use every original gadget and vehicle through intended gameplay paths, consumers and scene lifetimes. Mode: mvp Depends on: Phases 2 and 3; required normal acquisition routes are integrated with each gadget slice before Phase 5 closes complete campaign coverage. Requirements: GAD-01, GAD-02, GAD-03, GAD-04 Success Criteria (what must be TRUE):

  1. Players acquire/select every original gadget/item through its evidenced normal gameplay path, with original availability, inventory and energy behavior; debug grants alone do not satisfy acquisition.
  2. Every gadget can be aimed/activated/fired against its intended actor/object consumers with the evidenced states, projectiles and effects, while already verified bounded features keep working.
  3. Players summon, mount, operate and dismount original vehicles in supported modes with faithful input, collision, passenger and camera behavior.
  4. Interruptions, death, scripts, LOAD/RETURN and supported save/resume preserve or clear gadget, vehicle and companion state exactly at evidenced lifetime boundaries. Plans: TBD

Phase 5: Complete Campaign and Optional Routes

Goal: Players traverse all original-required campaign and optional content and reach original outcomes through ordinary progression. Mode: mvp Depends on: Phases 2–4; integrate any prerequisite frontend/persistence behavior within each route slice. Requirements: CAMP-01, CAMP-02, CAMP-03, CAMP-04 Success Criteria (what must be TRUE):

  1. Players enter/traverse every evidenced reachable campaign, optional and practice level using its original assets and correct entrance/exit rules.
  2. Authored scripts/cutscenes, missions, tasks, objectives, collectibles and level mechanisms advance in the original order through normal play.
  3. Players complete every original campaign route and evidenced optional branch through its original completion/win/loss outcome without debug grants, warps or substituted progression.
  4. Reviewers can account for every supplied level/resource as reachable, evidenced unused/unreachable, or an unresolved dependency; missing archives are investigated for actual reachability rather than silently substituted or assumed fatal. Plans: TBD UI hint: yes

Phase 6: Original Frontend and Save/Resume

Goal: Players use the original frontend/options and save/resume completed gameplay with equivalent progression and retained state. Mode: mvp Depends on: Phases 2–5; save/configuration callers needed by earlier slices are recovered and integrated earlier. Requirements: UI-01, UI-02, SAVE-01, SAVE-02 Success Criteria (what must be TRUE):

  1. Players use original startup, new-game, menu, pause, objective/HUD, prompt and ending flows with evidenced input/timing; modern diagnostics are distinguishable from original UI.
  2. Players change and persist original-supported input/display/audio configuration with faithful defaults and bounds.
  3. Players save/load/resume through original player-facing workflows with correct checkpoints, tasks, inventory, health/energy and progression, preserving required original-format fields.
  4. Fresh start, repeated load, scene return and resumed play preserve the appropriate actor/helper/companion/gadget/script/camera state and produce equivalent continued gameplay, not merely matching serialized bytes. Plans: TBD UI hint: yes

Phase 7: Original Visual and Audible Presentation

Goal: Players see and hear the original authored presentation across complete gameplay, with remaining visual/audio differences resolved through identified comparisons. Mode: mvp Depends on: Phases 2–6 and original reference access from Phase 1; blocking presentation contracts are integrated with earlier slices. Requirements: VIS-01, VIS-02, VIS-03, AUD-01, AUD-02 Success Criteria (what must be TRUE):

  1. Original geometry, textures, hierarchy/pivots, morphs, sprites, animation and UI appear at faithful authored positions and playback timing in matched gameplay/reference captures.
  2. Lighting, materials, fog, texture stages/sampling, blend/alpha/depth/culling and render layers match the evidenced original behavior through Vulkan equivalents, using justified system-specific comparison tolerances.
  3. Gameplay/script camera framing, projection, clipping, aspect handling and transitions preserve the authored scene without distortion.
  4. Players hear the original music/speech/contextual banks and events with correct timing, priorities, loops and interruption through gameplay and scene changes.
  5. Physical audible checks and matched event/listener observations confirm volume, panning, attenuation, positional/frequency behavior and camera/listener ownership; dummy streams alone do not establish fidelity. Plans: TBD UI hint: yes

Phase 8: Full-Game Native Acceptance and Delivery

Goal: Players can run reproducible offline packages on native Linux and Windows and complete the original game with current full-game fidelity evidence. Mode: mvp Depends on: Phases 1–7; all original/native comparison acceptance dependencies must close for full completion. Requirements: REL-01, REL-02, REL-03, REL-04 Success Criteria (what must be TRUE):

  1. Clean self-contained Linux x64 and Windows x64 packages run offline without SDK/development paths or the original installation, carrying the required SDL3, resources and shaders.
  2. Current packages complete integrated campaign/optional-content scenarios and physical input/audio/window/focus/resize/fullscreen/lifecycle checks on both native platforms with exact source/package identities and Vulkan diagnostics.
  3. A final original-versus-port discrepancy audit covers gameplay, timing, visuals, audio and progression; unresolved original-required differences or unavailable comparisons remain visible and prevent unsupported full-fidelity completion claims.
  4. Maintainers reproduce local builds/tests/packages and find current compatibility/evidence/limitations; verified source/tools/docs are pushed to existing Gitea while originals, generated traces and packages remain local, and original hashes still match. Plans: TBD

Progress

Execution follows 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8, subject to the explicit reference-access exception and earlier prerequisite integration. Full completion cannot bypass an open phase or acceptance dependency.

Phase Plans Complete Status Completed
1. Reproducible Fidelity Baseline 1/7 In Progress -
2. Faithful Movement and Scene Handoffs 0/TBD Not started -
3. Original Actors, Hazards and Combat 0/TBD Not started -
4. Complete Gadget and Vehicle Use 0/TBD Not started -
5. Complete Campaign and Optional Routes 0/TBD Not started -
6. Original Frontend and Save/Resume 0/TBD Not started -
7. Original Visual and Audible Presentation 0/TBD Not started -
8. Full-Game Native Acceptance and Delivery 0/TBD Not started -

Coverage: 33/33 v1 requirements assigned once; all phases have 3–5 observable success criteria. Existing bounded implementation is not counted as phase completion.


Initialized: 2026-11-12 — remaining full reconstruction, playable slices