From 7d56538d9f43e5dc04998ada59fe0d815eae388f Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Thu, 12 Nov 2026 11:37:30 -0500 Subject: [PATCH] docs: initialize reconstruction project --- .planning/PROJECT.md | 81 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..24dd422 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,81 @@ +# Neutron GamePort + +## What This Is + +A faithful reconstruction of the original Windows 98 Neutron game for native Linux x64 and Windows 10/11 x64, using shared C#/.NET 10 code, Vulkan 1.3+ through Silk.NET.Vulkan, and SDL3. It preserves the original game's identity and reuses recovered original assets. The current project already implements substantial playable content; this planning effort covers the remaining full reconstruction. + +## Core Value + +Match the original game's behavior and presentation as accurately as possible, using original evidence and explicit verification to govern every reconstruction decision. + +## Requirements + +### Validated + +These are existing capabilities with bounded evidence, not claims that the whole game or all platforms are verified. See `docs/progress.md`, `docs/compatibility.md`, and the linked investigation reports for exact revisions and limits. + +- ✓ Shared .NET 10 runtime with Vulkan rendering and SDL3 window/input/audio — existing code and recorded native Linux checks. +- ✓ Original inventory and hash verification, bounded asset parsers, offline preparation and original-format GAM/TSK reading — existing tools and regressions; 539 originals comprise the recorded baseline. +- ✓ Playable lab/tutorial/outside content, script and cutscene execution, original-derived geometry, actors, HUD, music and speech — existing bounded routes and runtime checks; full original fidelity remains open. +- ✓ Recovered movement/body/collision components with isolated original-code comparisons — existing component evidence; physical registration, derived callbacks and broad live admission remain incomplete. +- ✓ Bounded implementations of several gadgets and vehicles — existing per-scene reports; broader actor interactions, levels and retained lifetimes remain open. +- ✓ Local Linux and Windows self-contained publishing and package provenance — existing scripts and recorded checks; Windows cross-publishing and Wine evidence do not establish complete native Windows compatibility. + +### Active + +- [ ] Close remaining Jimmy movement, body/contact, animation, camera and retained scene-state gaps while preserving verified baseline behavior. +- [ ] Recover physical registration, activation, helper cleanup, real actor responses and shared collision context before expanding live source solver admission. +- [ ] Complete original gameplay systems, gadgets, enemies/AI, damage, interactions and level-specific mechanics from authoritative evidence. +- [ ] Complete all original levels and progression, menus, configuration, save/load and fresh/retained/RETURN lifetimes. +- [ ] Match original rendering, materials, lighting, fog, transparency, animation, camera framing and UI behavior as closely as evidence permits. +- [ ] Complete original audio playback, banks, positional effects, timing, attenuation and lifecycle behavior. +- [ ] Establish repeatable original-versus-port comparisons, document discrepancies and resolve them in dependency order. +- [ ] Verify integrated gameplay and local release packages on native Linux and native Windows, retaining explicit evidence and remaining limitations. + +### Out of Scope + +- Creative reinterpretation, replacement movement tuning or visual modernization that changes the original identity — fidelity takes precedence. +- New gadgets or broader gameplay expansion before the current movement/route checkpoint closes — preserve the current stabilization priority. +- Runtime online services, telemetry, cloud CI, and uploads of original assets or generated packages — local operation and evidence preservation are mandatory. +- Replacing authoritative evidence with third-party reconstruction behavior — external decompiler indexes provide investigation leads only. + +## Context + +The authoritative specification is `../prompt.MD`; `../AGENTS.md` and `AGENTS.md` provide project rules and current priorities. Original binaries and assets live in `../Original/` and must never be modified or executed in place. Use generated copies and separate analysis/extraction/build output. + +The complete codebase map is in `.planning/codebase/`. Existing architecture composes a persistent presentation session with scene-local simulation, scripts, resources and audio. Recovered algorithms and isolated original-component probes coexist with bounded live adapters and explicitly modern compatibility paths. Lab/outside capsule collision must remain until the source replacement gate is satisfied. + +`docs/checkpoint/next-work-plan.md`, `docs/checkpoint/coverage.md`, `docs/checkpoint/implementation-plan.md`, and `docs/gameplay/jimmy-movement-stabilization.md` preserve the current recovery sequence. The successful TSK-backed first-story retained-input ordering correction is already documented; it must not be planned as an untouched defect or replaced by an invented orientation reset. Remaining derived actor responses, helper lifetime, collision admission, animation and camera handoffs need their own evidence gates. + +The user explicitly selected the remaining full reconstruction as the planning scope and emphasized that it must be as accurate as possible to the original. A complete playable scene is an intermediate checkpoint, not the final scope. Existing runtime and component tests do not prove complete original-game fidelity. Whole-original runtime reference capture and broader native Windows comparisons remain open according to current reports. + +## Constraints + +- **Technology:** C#/.NET 10, Silk.NET.Vulkan, Vulkan 1.3+, SDL3; one shared native Linux/Windows x64 implementation. +- **Fidelity:** Preserve original algorithms, control semantics, floating-point/store behavior where significant, timing, progression and asset identity. Record approximations and unresolved questions explicitly. +- **Evidence:** Use REA for original-binary investigations; preserve complete Evidence, addresses, file offsets, provider gaps and relevant byte cross-checks. Distinguish static recovery, inference, implementation, compilation, component execution and whole-game runtime verification. +- **Validation:** Compilation alone cannot establish completion. Require meaningful regressions and integrated runtime comparisons at the appropriate scope; native Windows verification remains distinct from cross-publish and Wine. +- **Preservation:** Verify original hashes against `docs/original-manifest.json`; keep generated data outside originals and source commits. +- **Workflow:** Local builds/tests/packages only. Commit and push completed, verified source/tools/docs to existing `Gitea/main`; do not add cloud CI or upload originals/generated packages. +- **Coordination:** At most three investigators alongside primary, exclusive file ownership, primary integration and verification. Preserve unrelated working-tree changes. + +## Key Decisions + +| Decision | Rationale | Outcome | +|----------|-----------|---------| +| Plan the remaining full reconstruction | User selected full scope rather than a movement-only milestone | Confirmed | +| Make original fidelity the governing priority | User explicitly requires accuracy as high as possible | Confirmed | +| Stabilize movement and interacting lifetimes before expansion | Current project instructions and recovery dependencies | Existing policy | +| Reuse evidence and validated implementation with bounded claims | Avoid repeating solved investigations or overstating coverage | Existing policy | +| Require original comparison and native platform evidence for final completion | Component tests and cross-builds have narrower guarantees | Pending full verification | + +## Evolution + +This document evolves at phase transitions and milestone boundaries. + +After each phase transition, move verified requirements to Validated with evidence references, record invalidated scope and new requirements, update decisions, and check that the project description remains accurate. + +After each milestone, review every section, confirm the fidelity priority, revisit deferrals and update context with actual implementation and verification status. Keep full-game completion separate from intermediate scene and component checkpoints. + +--- +*Last updated: 2026-11-12 after initialization and user scope approval*