Files

12 KiB

Reconstruction Pitfalls

Project: Neutron GamePort Reviewed: 2026-11-12 Scope: Remaining full reconstruction; local documentation review only. No new original-binary investigation, execution, build or runtime comparison was performed.

Evidence and confidence

The risks below are cross-referenced repository findings, not externally researched ecosystem claims. Their supporting source/component observations have the bounds specified in the linked reports; their implications for phase ordering are planning inferences. Whole-game accuracy is unverified. The generic classify-confidence --provider curated --verified seam returned LOW for this local-source provider; that label must not be mistaken for a new certification of the original experiments. Use the underlying receipts and their explicit execution scope when deciding admission.

Critical pitfalls

1. Promoting component parity into live gameplay fidelity

Failure: A matching pair, normal-response or reclip fixture is wired into every scene as though actual actors, registry membership and task effects were recovered.

Warning signs: Completion claims cite only fixture counts; synthetic callback endpoints are described as real soldier/Jimmy policies; serialized GAM records become the active physical-body count.

Prevention: Require actual class construction, activation, physical order, derived response, enter/stay/leave consumers and shared context before expanding each live adapter. Keep lab/outside capsule compatibility until its replacement dependencies close. Compare complete callback events, flags and state snapshots, not just final positions. Soldier complete174 and Jimmy204 remain record-only endpoints in the normal-contact report.

Phase implication: Physical lifecycle and derived callbacks precede broad actor, enemy and gadget collision expansion.

Sources: normal contacts, physical registration, pair lifecycle, coverage.

2. Fixing symptoms by changing legitimate original movement

Failure: A universal angle reset, added damping or imported tuned movement masks an ownership/scheduling divergence and removes original behavior.

Warning signs: Ordinary landing bank is called a bug; fresh direct-scene and TSK-backed retained entry are given the same input order; JN-Engine's tuned movement becomes the oracle.

Prevention: Preserve current movement and the successful first-story TSK retained-input correction. Trace the first divergent owner and caller phase before changing arithmetic. Recheck neutral return, sustained idle, held input, both turn directions, natural/skip completion and repeated scenes. External decompiler indexes provide leads only.

Phase implication: Movement, control/animation ownership and route handoffs remain the first implementation checkpoint. The Carl initialization correction is existing work, not an untouched future fix.

Sources: menu/player lifetime, movement stabilization, next-work plan updates.

3. Flattening physical registration and retained lifetime

Failure: Deduplication, snapshot traversal or a generic reset silently changes ordering across fresh load, retained LOAD and RETURN.

Warning signs: Constructor registrations are treated as final active membership; Init and PostLoad run as two global passes; setting a flag is treated as deleting a node; helper reuse/cleanup is assumed from a constructor edge.

Prevention: Keep ordinary registry and physical list independent. Common registration can append an existing pointer; Jimmy's outer guard is separate. Preserve Init-before-parent-append and per-object Init/PostLoad traversal that can visit new tails. Recover actual helper removal, activation and re-entry before representing retained lists. Compare complete ordered lists across scene transitions.

Phase implication: Lifecycle closure must precede arbitrary retained saves, general dynamic contacts and full-level progression admission.

Sources: registration, generated helpers, dynamic context.

4. Caching values across source callbacks

Failure: A refactor snapshots radius, inhibition, geometry permission or velocity before callbacks, changing subsequent reclip and final publication.

Warning signs: Accessors become constructor constants; a callback's root edit is assumed to survive final local-root publication; collision mode and class-specific controller state share an enum or layout.

Prevention: Preserve source getter order and independent fields. Test callbacks that mutate radius, flags, Y velocity and roots, plus retained old-hit/last-polygon behavior. Distinguish XYZ writes from full XYZW setters. Do not apply inherited reflection to Jimmy ordinary374, which takes its own material-policy path.

Phase implication: Response adapters require live getter and ownership contracts before integration.

Sources: normal contacts, populated reclip.

5. Treating mathematically equivalent arithmetic as source equivalent

Failure: Double promotion, normalization changes, reordered operations, triangle winding fixes or a faster broadphase alter strict branches, ties and accumulated state.

Warning signs: Double intermediates are called an x87 emulator; only root tolerance is checked; duplicated source cell visits are removed; heading wraps or unclamped damping are normalized to conventional behavior.

Prevention: Preserve evidenced float-store boundaries, kernel A,C,B winding, strict comparisons and traversal order. Record the first exact differing field and kernel argument. Widening precision or optimizing needs new differential evidence; degenerate inputs outside the bounded contract remain explicit unknowns.

Phase implication: Preserve numeric probes throughout collision, actors and rendering-transform work; optimize after equivalence and measured need.

Sources: dynamic reclip, normal contacts, codebase concerns.

6. Mistaking successful rendering or audio transport for original presentation

Failure: Zero Vulkan errors, identical port screenshots or SDL dummy-stream success are reported as visual/audible parity.

Warning signs: Merged far-plane policy implies per-layer fog/clipping fidelity; queue-empty replaces the original software sound clock; fixed 60 Hz is called recovered original scheduling; a correct transform kernel implies exact final OMT visual decomposition.

Prevention: Compare original reference frames and sound intervals at identified states. Keep lighting/fog/material/blend/culling, sprite/pivot/decomposition, morph clocks, camera handoff, sound-bank/channel duration/attenuation and physical listening as separate targets. Retain device-independent numeric and transport checks, but report their narrower guarantees.

Phase implication: Presentation and audio need source-specific recovery and integrated comparisons; start reference acquisition early rather than leaving all fidelity checks until release.

Sources: coverage, compatibility, air bridge.

7. Shipping a different revision from the one verified

Failure: Current source, historical GPU tests and an older local package are merged into one completion claim; Wine is presented as native Windows verification.

Warning signs: No exact package identity; user Windows reports attributed to an agent-run current build; startup black frames treated as a playable original reference; source-only changes inherit old SDL coverage.

Prevention: Bind every receipt to source commit, package provenance, resource hashes, platform, scenario and validation setting. Run the same integrated route/control/window/audio checks on clean standalone Linux and native Windows packages. Keep original-component Wine32, port Wine64, whole-original reference and native Windows evidence separate. A blocked original runtime comparison remains an open release obligation.

Phase implication: Reference/native Windows access is an early dependency; final full-game acceptance requires current integrated evidence, not a cross-publish alone.

Sources: progress, compatibility, codebase concerns.

Further risks during full reconstruction

Risk Warning sign Prevention / roadmap consequence
Asset inventory mistaken for playable coverage All GAMs parse, therefore all levels are called complete Track each original route, mechanic, actor and script consumer through implementation and runtime verification.
Unsupported missing-content conclusion Level3B/E GAMs described as missing, or absent OMTs called a proven fatal normal-game blocker GAMs exist; distinguish their referenced absent archives from proven reachability. Investigate hardcoded/serialized routes without inventing substitutes. See resource evidence.
Save round-trip mistaken for load fidelity Binary equality substitutes for repeated task/entity callbacks and retained scene ownership Recover full original load UI, callback multiplicity, placement and helper lifetimes; test loading at real progression boundaries. See coverage SAVE.
Invalid copied-code evidence accepted Partial captures or relocation scans are counted as source behavior Preserve full REA replies, source/probe hashes, reviewed operand mappings and completion markers; exclude invalid captures. Provider errors remain errors. See normal contacts.
Original evidence altered or published Extraction/probes target Original, or package files enter source commits Generated copies/output only; verify all 539 baseline hashes, stage explicit source/docs paths and keep assets/packages local.
Old narratives override newer receipts A solved Carl bug is reopened from an older section Follow dated continuation updates and exact receipt scope; reconcile current reports before planning changes.

Phase-specific gates

  1. Core movement/lifetimes: preserve baseline, close real response/helper/state owners and validate lab → VR04 → lab → outside before expansion.
  2. Actors/gadgets/combat: recover actual callbacks, RNG/action policies, activation and physical order before broader admission; bounded training-scene behavior is not full-game coverage.
  3. Progression/save/menu: exercise complete authored routes, fresh/load/RETURN paths and task callbacks; do not equate parsable resources with playable progression.
  4. Rendering/audio/UI: obtain observable original references, then address named state/clock/transform differences with isolated and integrated evidence.
  5. Release: identify exact clean builds and resource manifests; verify full original content and native Linux/Windows behavior, with no unverified fidelity claims hidden by successful packaging.

These gates are dependency recommendations inferred from current findings. They are not new binary findings or implementation approvals.