docs: research remaining full reconstruction
This commit is contained in:
1 parent
dd7688bce9
commit
a8dc07f9fc
5 files changed
+517
No files matched your search
@@ -0,0 +1,181 @@
|
||||
# Project Research Summary
|
||||
|
||||
**Project:** Neutron GamePort — remaining full reconstruction
|
||||
**Domain:** Evidence-led reconstruction of a legacy native 3D game
|
||||
**Researched:** 2026-11-12
|
||||
**Confidence:** High in mandated scope and existing boundaries; medium in roadmap decomposition; unresolved for complete original/runtime fidelity.
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This is an existing playable reconstruction, not a new engine project. Retain the shared C#/.NET 10, Silk.NET.Vulkan/Vulkan 1.3+ and SDL3 foundation, original-derived resources, local tooling and bounded recovered components. The user requires the remaining full game to match the original as accurately as possible. Original behavior, including quirks, takes priority over conventional movement or presentation improvements. A faithful scene is an intermediate milestone; complete campaign and supported optional-content coverage remain required.
|
||||
|
||||
The immediate implementation dependency is movement and interacting ownership: real derived actor responses, physical/helper registration and cleanup, callback-mutated fields, shared dynamic/static reclip, animation and camera handoffs. Preserve the implemented TSK-backed first-story ordering correction and legitimate landing bank. Expand existing gadgets, actors and levels only after their source admission dependencies close. Complete gameplay, progression/persistence and presentation/audio through integrated playable slices rather than treating their isolated algorithms as full scene support.
|
||||
|
||||
The largest acceptance gap is reference evidence. Existing copied-original component execution, Linux SDL/Vulkan tests, Windows cross-publishing and Wine results have useful but different scopes. Establish a usable copied-original reference environment and repeatable native Windows checks early; grow comparison coverage throughout implementation. Full-game completion requires current integrated native Linux/Windows and original-versus-port evidence, exact source/package provenance and explicit discrepancy closure. This research reviewed local documents and selected configuration/code; it did not refresh any runtime receipt or recover new binary behavior.
|
||||
|
||||
## Key Findings
|
||||
|
||||
### Recommended Stack
|
||||
|
||||
Retain the existing implementation. Repository versions are .NET 10 (`net10.0`, bootstrap SDK 10.0.402), Silk.NET.Vulkan/KHR/EXT 2.23.0 and bootstrap SDL3 3.4.2. Vulkan 1.3 is mandatory. These describe repository configuration, not newly checked upstream releases or installations. Host Vulkan loader/driver support remains necessary for self-contained packages.
|
||||
|
||||
- **C#/.NET 10:** one shared native Linux/Windows x64 runtime and managed regression programs.
|
||||
- **Silk.NET.Vulkan and GLSL/SPIR-V:** existing resource ownership and shader pipeline; extend source fixed-function equivalents instead of redesigning the look.
|
||||
- **SDL3:** existing native window/input/audio transport; original policy and timing remain project responsibilities.
|
||||
- **Python/Bash/C, REA/Ghidra and Wine:** local preparation, evidence and isolated probes. They are not online or packaged runtime dependencies. REA is required for future original-binary investigations; Wine is preliminary compatibility evidence.
|
||||
- **Local build/package scripts and hash manifests:** reuse established facilities, adding exact revision/platform/resource receipts rather than replacing infrastructure.
|
||||
|
||||
See [STACK.md](STACK.md) for configuration sources and verification capability gaps.
|
||||
|
||||
### Expected Features
|
||||
|
||||
All original-required behavior belongs in the full reconstruction scope. Existing bounded implementations are reusable progress, not grounds to omit their remaining consumers or lifetimes.
|
||||
|
||||
**Must complete:**
|
||||
|
||||
- Jimmy movement, original input, body/contact modes, animation/control and camera ownership across fresh entry, scripts, LOAD and RETURN.
|
||||
- Actual actors, enemies/AI, RNG/action policies, health/damage/hazards, combat and class-specific task/contact effects.
|
||||
- All original gadgets/vehicles and inventory/energy behavior across intended consumers and scenes, preserving currently live bounded features.
|
||||
- Reachable campaign levels, authored scripts, tasks, objectives, collectibles, branch/optional content and ending/win/loss behavior where evidenced.
|
||||
- Original frontend, HUD, options/configuration and complete runtime save/load/resume semantics.
|
||||
- Original geometry, pivots/morphs, materials, lighting/fog/alpha/depth/cull/layer behavior and camera presentation.
|
||||
- Music/speech/effects, contextual banks/channels, clocks, loops, attenuation/panning and physical audible output.
|
||||
- Offline clean packages and integrated native Linux/Windows and original-reference comparisons.
|
||||
|
||||
**No new differentiators:** Fidelity is the value. Keep existing user-authorized diagnostics distinct from original frontend/gameplay. Do not add creative mechanics, tuned replacement movement, visual modernization, online services or telemetry. No original-required category is deferred beyond the full reconstruction merely to shorten this roadmap.
|
||||
|
||||
See [FEATURES.md](FEATURES.md) for per-category existing capabilities, dependency and acceptance targets. Level3B/E GAMs exist but their referenced OMTs are absent; normal gameplay reachability is unverified, so missing geometry is not an established campaign blocker.
|
||||
|
||||
### Architecture Approach
|
||||
|
||||
Preserve explicit application composition and scheduling. `RenderSession` owns persistent native presentation; scene composition connects simulation, script/interactions, decoded resources, visual adapters and audio. Original object retention is different from GPU/audio resource recreation. Recovered components require explicit actor/scene admission, with complete registry/helper lifetime and real callback policies before broad integration.
|
||||
|
||||
Keep body/controller/fire/control clocks independent; fresh direct-GAM ordering differs from retained TSK story entry. Maintain source live getter order and separate collision modes from class-specific state. Shared camera eye/aim, animation completion and sound software clocks need their own owners rather than generic resets or transport-driven substitutes. Extend focused modules and tests without inventing a universal engine or solver.
|
||||
|
||||
See [ARCHITECTURE.md](ARCHITECTURE.md) for boundary tables, the immediate physical admission gate and solved-versus-open checkpoints.
|
||||
|
||||
### Critical Pitfalls
|
||||
|
||||
1. **Component parity promoted to live fidelity:** Require actual derived policies, active membership, helper lifetime and task effects; compare ordered full state/events before admitting new actors/scenes.
|
||||
2. **Symptom fixes erase original behavior:** Preserve legitimate landing bank and the implemented startup ordering correction. Trace the first divergent writer instead of adding leveling resets or importing third-party tuned movement.
|
||||
3. **Convenient lifecycle/numeric rewrites alter semantics:** Preserve mutable registry traversal, repeated registrations, callback-time scalar reads, retained query state, strict comparisons, winding and evidenced float-store boundaries.
|
||||
4. **Port-only visuals/audio mistaken for original parity:** Zero Vulkan errors and dummy streams prove narrower properties. Compare identified original frames, clocks, listener states and audible output.
|
||||
5. **Verification and shipped revisions diverge:** Bind receipts to exact source/package/resource identity; distinguish native Windows, Wine, component execution and whole-original runtime. Never inherit historical coverage for a changed build.
|
||||
|
||||
See [PITFALLS.md](PITFALLS.md) for warning signs, mitigation and report references.
|
||||
|
||||
## Implications for Roadmap
|
||||
|
||||
Use eight dependency-led phases at standard granularity. Each phase should contain small source-recovery → implementation → integrated-verification slices; phase boundaries do not justify delaying necessary audio, camera or reference work.
|
||||
|
||||
### Phase 1: Fidelity Baseline and Reference Access
|
||||
|
||||
**Rationale:** Later acceptance needs a trustworthy original/platform comparison path and current coverage matrix.
|
||||
**Delivers:** Revision-specific evidence/discrepancy ledger, original-reference capture route and initial native Linux/Windows scenario matrix; explicit unresolved environment limitations.
|
||||
**Addresses:** Original comparison, preservation and current baseline provenance.
|
||||
**Avoids:** Treating probes, startup frames, cross-publish or older packages as full-game reference evidence. Independent source-backed recovery can continue if reference execution is unavailable, but its acceptance gate stays open.
|
||||
|
||||
### Phase 2: Movement, Contact and Retained Ownership
|
||||
|
||||
**Rationale:** This is the existing stabilization gate before broader gameplay expansion.
|
||||
**Delivers:** Real derived response/helper/physical-order/shared-reclip contracts, supported live admission, animation/control/camera handoffs and integrated lab → VR04 → lab → outside verification.
|
||||
**Addresses:** Jimmy movement, source timing, contacts, fresh/retained/RETURN state and route ownership.
|
||||
**Avoids:** Reopening the solved Carl startup correction, generic resets and premature lab/outside capsule replacement.
|
||||
|
||||
### Phase 3: Actors, Hazards and Combat
|
||||
|
||||
**Rationale:** Gadgets and campaign scripts depend on real class consumers and actor responses.
|
||||
**Delivers:** Supported enemy/NPC sensing/action/RNG, damage/health/death/recovery, special contacts and actual task/contact side effects in playable slices.
|
||||
**Addresses:** Actor/AI/combat and level mechanics foundations.
|
||||
**Avoids:** Synthetic callbacks and generic patrols being called complete original AI.
|
||||
|
||||
### Phase 4: Gadgets, Vehicles and Interaction Coverage
|
||||
|
||||
**Rationale:** Expand on recovered actor/lifetime contracts and preserve already-live bounded gadget scenes.
|
||||
**Delivers:** Remaining original gadgets, all intended consumers and supported modes, activation/cleanup, inventory/energy and transition behavior.
|
||||
**Addresses:** Remote and other remaining functionality, broader existing gadget/vehicle use and source-supported inputs.
|
||||
**Avoids:** Fixture/F1-grant demonstrations substituted for normal gameplay acquisition/use or blanket physical admission.
|
||||
|
||||
### Phase 5: Campaign, Tasks and Level Completion
|
||||
|
||||
**Rationale:** Full progression relies on actors, interactions and gadget consumers.
|
||||
**Delivers:** All evidenced reachable campaign and optional routes, authored missions/scripts, objectives/collectibles, entrances/exits and final outcomes.
|
||||
**Addresses:** Full original content and class-specific progression consumers.
|
||||
**Avoids:** Counting parsed GAMs or rendered levels as playable completion; resolve absent-archive reachability before treating it as a blocker.
|
||||
|
||||
### Phase 6: Frontend, Configuration and Persistence
|
||||
|
||||
**Rationale:** Complete supported gameplay state must survive real player-facing save/resume and menu flows.
|
||||
**Delivers:** Original frontend/HUD/options, persisted configuration, runtime save/load and repeatable equivalent resume across supported checkpoints and retained lifetimes.
|
||||
**Addresses:** Full player workflow beyond debug tools and CLI save operations.
|
||||
**Avoids:** Binary round-trip mistaken for live load correctness; preserving unknown TSK fields does not establish their gameplay semantics. Add necessary persistence earlier when campaign slices require it.
|
||||
|
||||
### Phase 7: Visual, Animation and Audio Fidelity Closure
|
||||
|
||||
**Rationale:** Systematic final presentation closure needs representative complete gameplay, while blocking presentation contracts are recovered earlier.
|
||||
**Delivers:** Matched original/port frames and event/audio timelines; corrected rendering states, pivots, playback, camera/UI details, contextual banks/channels and audible spatial behavior.
|
||||
**Addresses:** Remaining fixed-function and original presentation/sound differences.
|
||||
**Avoids:** Modernization, assumed 60 Hz equivalence and transport/API correctness used as fidelity evidence.
|
||||
|
||||
### Phase 8: Full-Game Native Acceptance and Local Release
|
||||
|
||||
**Rationale:** Only integrated complete journeys can establish final scope and platform claims.
|
||||
**Delivers:** Current clean standalone Linux and Windows packages, full progression/optional-content comparison, physical audio/input/window checks, original hash verification and discrepancy audit.
|
||||
**Addresses:** Complete reconstruction acceptance and reproducible local delivery.
|
||||
**Avoids:** Historical receipts or Wine replacing current native Windows execution; generated packages/original assets remain local while verified source/tools/docs go to Gitea.
|
||||
|
||||
### Phase Ordering Rationale
|
||||
|
||||
Reference access starts early and comparison grows throughout the work. Movement and lifecycle gates precede expansion; actual actors precede their gadget consumers; these enable campaign and complete persistence. Presentation and audio investigations can run independently with exclusive ownership, integrating as soon as they block a gameplay slice. The final presentation and release phases close cross-cutting differences rather than postponing every fidelity check until the end.
|
||||
|
||||
### Research Flags
|
||||
|
||||
- **Phases 1–2:** Targeted environment feasibility and deep original source/runtime investigation; complete helper/response/camera/animation contracts remain open.
|
||||
- **Phases 3–6:** Phase-specific REA/asset/caller recovery is required for real actors, gadget consumers, campaign reachability and frontend/save semantics. Existing bounded implementations reduce work but do not establish remaining policies.
|
||||
- **Phase 7:** Original render/audio state and playback research is essential; reference captures determine acceptance tolerances.
|
||||
- **Phase 8:** Existing package/build patterns can be reused without ecosystem re-research. Native platform execution and original comparison are mandatory validation, not assumed standard behavior.
|
||||
|
||||
## Confidence Assessment
|
||||
|
||||
| Area | Confidence | Notes |
|
||||
|------|------------|-------|
|
||||
| Stack | High for repository foundation | Mandated by specification and corroborated by project configuration; installation/current runtime not reverified here. |
|
||||
| Features | High for full scope; medium for remaining exact behavior | Explicit user/spec scope; detailed remaining behavior still requires original evidence. |
|
||||
| Architecture | High for current boundaries; medium for proposed phase order | Multiple local reports agree; future dependency grouping is planning inference. |
|
||||
| Pitfalls | High as recorded risks | Supported by prior divergence/lifecycle reports; this review does not reproduce their experiments. |
|
||||
|
||||
**Overall confidence:** Medium for the execution roadmap, with strong documented constraints and explicit unresolved original behavior. Generic provider-classifier LOW results in dimension files do not independently certify or invalidate underlying repository evidence.
|
||||
|
||||
### Gaps to Address
|
||||
|
||||
- Working whole-original capture environment and repeatable native Windows access remain unverified dependencies.
|
||||
- Complete physical helper membership/removal/activation, derived soldier/Jimmy effects, shared mutable reclip, camera handoff and animation/sound clocks need focused investigation.
|
||||
- Full reachable content, original frontend/save callers, contextual audio and per-layer rendering remain incomplete; do not fabricate behavior from resource names.
|
||||
- Comparison tolerances must be justified per system from original observations; no blanket pixel-perfect or bit-exact whole-game claim is supported.
|
||||
- Historical reports contain superseded narratives. Prefer dated continuation evidence with exact revision/platform scope before implementation.
|
||||
|
||||
## Sources
|
||||
|
||||
### Authoritative Scope and Repository Rules
|
||||
|
||||
- [PROJECT.md](../PROJECT.md) — user-selected full remaining reconstruction and maximum-fidelity priority.
|
||||
- [prompt.MD](../../../prompt.MD) — original mission, platforms, preservation and full completion requirements.
|
||||
- [AGENTS.md](../../AGENTS.md) — current movement priority, REA requirements and Gitea/local-only artifact policy.
|
||||
|
||||
### Synthesized Research
|
||||
|
||||
- [STACK.md](STACK.md) — existing technology/configuration and verification facilities.
|
||||
- [FEATURES.md](FEATURES.md) — original-required categories, bounded existing support and acceptance gaps.
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) — ownership/admission dependencies and solved versus unresolved work.
|
||||
- [PITFALLS.md](PITFALLS.md) — fidelity risks and concrete prevention.
|
||||
|
||||
### Underlying Local Evidence Indexes
|
||||
|
||||
- [Progress](../../docs/progress.md), [compatibility](../../docs/compatibility.md), [tasks](../../docs/tasks.md) — historical implementation/runtime receipts and current limits.
|
||||
- [Coverage](../../docs/checkpoint/coverage.md), [implementation ledger](../../docs/checkpoint/implementation-plan.md), [next-work plan](../../docs/checkpoint/next-work-plan.md) — source recovery and admission gates, including later correction updates.
|
||||
- [Codebase architecture](../codebase/ARCHITECTURE.md), [concerns](../codebase/CONCERNS.md) — current source structure and risks.
|
||||
- Specialized source/probe/runtime reports are linked beside individual findings in the four dimension files. Their evidence scopes remain binding; this synthesis is not new binary or runtime evidence.
|
||||
|
||||
---
|
||||
*Research completed: 2026-11-12*
|
||||
*Ready for roadmap: yes, with unresolved verification dependencies retained explicitly.*
|
||||
Reference in new issue
Block a user