Files
Neutron/.planning/research/ARCHITECTURE.md
T

14 KiB
Raw Blame History

Reconstruction Architecture and Dependency Gates

Project: Neutron GamePort
Researched: 2026-11-12
Scope: Local repository research for the remaining full reconstruction; no binary analysis, source execution, implementation changes or new runtime verification.

Recommendation

Extend the existing explicit scene composition and recovered component architecture. Preserve the distinction between a recovered algorithm, a synthetic original-component comparison, a live scene adapter and verified whole-game behavior. Complete movement and interacting lifetimes before expanding gameplay. The architecture already supports playable scenes; replacing it with a new engine or a speculative universal solver would discard the source-order contracts that existing evidence establishes.

This is a dependency analysis of current project reports and selected code, not independent certification of their original-binary findings. The generic CLI confidence classifier returns LOW for the curated provider label; it has no repository-evidence provider. Therefore the conclusions below state their documentary basis and limits rather than claiming a provider-certified HIGH confidence result.

Existing Boundaries to Preserve

Owner Existing responsibility Remaining architectural obligation
Program.Main / RenderSession Persistent native window/Vulkan device and session diagnostics; scene replacement Keep resource replacement separate from original object retention; retain explicit cleanup and native ownership
Program.Run Concrete scene composition, held input, fixed-step policy and callback scheduling Extend actual per-object registry order, live mutation and phase ownership rather than treating grouped updates as original semantics
LabSimulation / PlayerSceneBinding Player body/controller/fire/control boundaries; fresh versus retained input ordering; script and vehicle bridges Preserve independent control, body and effect eligibility, retained scalar ownership and authored transform publications
OriginalBodyPhysics, static/dynamic/pair/normal components Bounded recovered numeric and callback contracts Admit only actor states whose membership, callbacks, live reads and helper lifetime have been recovered
SceneDirector / interactions / tasks Script actions, task broadcasts, cutscene control, contacts and transitions Recover remaining real derived callbacks, action acceptance/completion and complete progression consumers
Assets / offline extractors Original-format decoding and prepared render/audio resources Preserve source identity/material metadata, explicit missing resources and immutable originals
Application visuals / renderer Morphs, sprites, UI, camera projection and Vulkan resources Replace named approximations with source-backed transforms, playback, materials, layers and render states
SceneAudio / SdlAudio Scene music/speech/effects and native stream ownership Separate original handle/bank/software clocks from SDL transport; complete positional/lifecycle policies

Source: codebase architecture, coverage, implementation ledger.

Physical Scene Admission Is the Immediate Gate

The physical list and the ordinary object registry have separate ownership. Common registration repeats transform/zero/Init work and appends without identity deduplication; Jimmy's outer 49E guard encloses the whole bridge. A scene-wide two-pass Init/PostLoad abstraction or a snapshot of registry membership would disagree with the recorded same-pass appended-child behavior. Serialized class counts and vtable identities cannot be treated as actual active-body counts.

The registration report inventories all 72 VR04 records/13 interfaces and compares 12 original-component registration/loader cases. Generated-helper edges are catalogued, but constructor/re-entry, conditional creation, removal, activation and retained LOAD/RETURN membership still need full ownership traces. The next integration must recover the actual ordered participants, not simply append every serialized actor or infer eligibility from its presence in the GAM file.

Normal response is also distinct from pair enter/stay/leave notification. Thirty original/C# normal-contact snapshots establish inherited response, Jimmy's ordinary bypass, live accessor order and bounded derived endpoints. Soldier mode10's complete 174 call is only a recorded endpoint; its RNG/action/target policy remains open. The grappler-related Jimmy 204 endpoint is likewise not a recovered universal cleanup policy.

The dynamic query/reclip components already compare empty and populated synthetic contexts, but sequential fixed actors are not a live mutable dispatcher. Post-callback inhibition, geometry permission, radius and 42C reads must stay live; callback root mutation can be overwritten by final query-local publication. Do not cache constructor values or insert an unevidenced context reset. Preserve old nearest/hit/last-polygon state where recovered.

Integration order: real derived responses and game/task consumers → helper activation/removal/re-entry and fresh/retained physical order → shared mutable query context/accessors → bounded response adapter for explicitly supported VR04 states → route and platform verification → broader special-material actors and lab/outside admission.

Sources: registration, helpers, normal contacts, dynamic context, populated reclip, pair lifecycle.

Camera, Animation and Retained State

  • Shared camera state: The source report establishes a shared viewport eye read by both scripted camera writes and follow input, strict DEFAULT snapping only above distance1000, and aim computed from the pre-update eye. Current Program.cs selects director versus simulation cameras and LabSimulation retains its own CameraEye; partial gadget bridges do not establish complete shared viewport semantics. Model the owner explicitly after validating the remaining callers. Keep projection, layer masks/fog, noclip and modern orbit policy separate.
  • Animation: Existing morph assets and deterministic visual checks do not establish the original action acceptance, playback clock, repeat/end events or interruption policy. Recover these across jump/land/STOP/talk/skip/control return before relying on them to drive actor transitions or progression. The port's fixed60Hz simulation policy must not become an assumed oracle for every original animation or script clock.
  • Retained scene state: Ordinary LOAD/RETURN, TSK loading, debug reset and fresh direct-GAM startup are different paths. Preserve original tasks/items/root state separately from session diagnostics and scene GPU/audio recreation. Current bounded retained player scalars are not permission to carry arbitrary helpers, timers, modes or handles through every transition.
  • Sound clocks: Original software elapsed/duration, strict completion boundaries, repeat and bank ownership govern cutscene behavior; transport queue-empty and dummy-stream success prove narrower properties. Integrate source channel state before broad playback-dependent script completion.

Sources: camera handoff, coverage, implementation ledger C5–C8, next-work plan.

Solved Checkpoints Versus Remaining Work

Reuse as established bounded work Still required
C1 pre-task objective notification and C2 per-actor Carl task override Other real derived task/contact policies and full progression
Controlled player body-before-callback order, fresh/retained input distinction Broader object scheduler, mutable helpers and actor-specific eligibility
TSK-backed first-story retained Jimmy ordering correction; first-neutral/300-idle regression Whole-original Carl runtime reference and native Windows comparison; broader handoffs
Static camera ray/FIFO/wall-first adapter and per-level far limits Complete shared eye/aim handoff, special follow branches and visual comparison
VR04 ordinary source static body and bounded body publication/mode components Dynamic registry/response, successful Jimmy hazards/climbs, lab/outside source admission
Dynamic query and populated reclip component comparisons Real actors/accessors and shared ordered scene context
Bounded gadget/vehicle scenes and retained scalar bridges Broader levels, special interactions, helper cleanup and arbitrary save/load lifetimes

Historical prose in next-work-plan.md still says the Carl correction has not begun; later updates and docs/tasks.md establish that the source startup-order classification and port correction are already implemented. Do not reopen that defect as untouched work or add an invented leveling reset. Similarly, the old C4 kernel-only checkpoint has been superseded by ordinary-body integration and later component reports, while its broader admission gate remains.

Dependency Order for the Full Reconstruction

  1. Close the movement/route checkpoint: real callbacks, helper lifetime/physical order, shared reclip, animation/control/camera handoffs and an integrated lab→VR04→lab→outside regression. Retain the existing playable baseline until each replacement gate closes.
  2. Complete shared actor/gameplay contracts: source damage/hazards, AI/action/RNG, interactions, gadgets/vehicles and their activation/cleanup. Derive scope from original resources and consumers; existing bounded scenes are reusable implementations, not proof of universal support.
  3. Complete original progression and persistence: load/RETURN and task/item state, every reachable level/mission, authored scripts and win/loss paths. Add full menu/configuration/save UI once their state ownership is recovered. Level inspection/rendering is insufficient.
  4. Complete presentation and audio contracts: animation/pivots, material/light/fog/alpha/culling/layers, shared camera and UI; bank/handle clocks, positional mixing and effects. Independent static research can run alongside earlier work, but live integration must respect gameplay and lifetime dependencies.
  5. Verify complete journeys and release packages: original comparison across representative and full-game routes, native Linux and native Windows gameplay/input/audio/rendering, offline package resource/provenance checks and reproducible discrepancy triage.

These are dependency groups, not a demand to defer all rendering/audio work until the end. Resolve a presentation or sound contract earlier when it blocks a verified gameplay route. Keep the roadmap within the selected standard granularity while allowing phase plans to subdivide evidence gates.

Verification Architecture

For each admitted capability, maintain an evidence chain: authoritative binary/asset identity → addresses/offsets and REA Evidence or documented provider gap → bounded source contract/probe → managed regression → live scene replay → native platform/package result → whole-original comparison where observable. Preserve complete snapshots and hashes locally. A successful level render, synthetic callback endpoint or cross-publish closes only its named gate.

Use deterministic source/component checks for phase and numeric differences; GPU readbacks for pose/camera/material differences; actual SDL input for integrated ownership and controls; physical/native audio checks for audible behavior; original-format round-trips and live reload for persistence. Define a discrepancy ledger with original/port scenario, first divergence, evidence, fix and remaining uncertainty. Never certify full fidelity from matching a few constants or rendered scenes.

Both packages must identify a clean verified runtime commit and contain matching original/prepared resources. Execute from a standalone directory without source/SDK/development-library paths. Reverify original hashes. Windows cross-publish, Wine compatibility, historical user reports and new native Windows execution remain separate receipts. Push only source/tools/docs to approved Gitea; original assets, generated traces and packages stay local.

Open Questions for Phase Research

  • Complete soldier RNG/action/target response and real enter/stay/leave task effects.
  • Constructor-only/conditional helper activation, cleanup mutation and retained physical ordering.
  • General live/reentrant scalar getter and shared context ownership beyond fixed synthetic probes.
  • Successful Jimmy FENCE/LADDER/hazard paths and multi-frame mode/animation effects.
  • Complete shared viewport handoff, source aim quantization and special follow branches.
  • Playback clocks/end callbacks, original sound bank lifecycle and full save/menu callers.
  • A usable whole-original reference environment and current native Windows verification.

Sources and Limits

Primary local planning inputs: PROJECT.md, architecture map, tasks, coverage, implementation ledger, and next-work plan. Selected current code checks: src/GamePort/Program.cs camera selection and src/GamePort/Game/LabSimulation.cs camera ownership. Specialized evidence reports are linked beside their findings above.

No original files were modified or executed. No current build, platform execution or original-runtime comparison was performed for this report. Architectural recommendations are inference from documented contracts; exact remaining original behavior must be recovered in phase-specific investigation.