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
- Core movement/lifetimes: preserve baseline, close real response/helper/state owners and validate lab → VR04 → lab → outside before expansion.
- 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.
- Progression/save/menu: exercise complete authored routes, fresh/load/RETURN paths and task callbacks; do not equate parsable resources with playable progression.
- Rendering/audio/UI: obtain observable original references, then address named state/clock/transform differences with isolated and integrated evidence.
- 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.