Files
Neutron/docs/decisions.md
T

13 KiB

Decisions

  1. Preserve input directory. Keep Original in place, baseline all file hashes, generate outputs elsewhere. No legacy binary execution in the source directory.

  2. Nested local repository. Workspace .git is reserved and not a functioning repository. Initialize GamePort/.git, no remotes, commit code/docs/tools only.

  3. Evidence-first data recovery. Native x86 executable does not imply little endian formats: GAM and OMT use big endian metadata. Require bounded readers, full consumption and real original-file regressions.

  4. Initial scene. NewGame.tsk starts LV1B and player GAM references STARTEXP. Prioritize that scene; use smaller VR01 for data/render verification. The LV1B LABEXP start trigger means simple camera spawning is insufficient for fidelity.

  5. Local dependencies. Missing SDK/native tools installed under .tools or /tmp after approved official downloads, without assuming root or altering host.

  6. Useful parallelism. Three independent agents own binary/rendering, asset recovery and infrastructure, while primary owns gameplay data and integration. Shared runtime/format changes must be coordinated. No external coordination.

  7. Honest compatibility. Build, headless Vulkan frame, SDL presentation, gameplay fidelity and native Windows execution are separate evidence categories.

  8. Preview ground contact and idle clarity. User testing exposed floor overlap and a misleading animated-default description. Original idle vertices are identical; do not invent idle motion. Expose moving source clips explicitly. Until original actor transforms/collision settling are recovered, apply one model-only floor correction derived from standing soles and visible geometry, with explicit preview labeling and regression tests. Preserve GAM/ASE data and per-frame morph displacement; this is not the original collision algorithm.

  9. Controllable lab before complete scene. Integrate evidence-backed no-gadget walking/jumping/camera now, with separate stateful simulation and explicit provisional source-triangle capsule collision. Rendering does not set the number of movement calls: use60Hz until original cadence is recovered. Preserve source GAM/ASE positions; keep physical feet, inferred actor-root height and visual pivot separate. Include invisible geometry rather than inventing visibility masks. Document the skipped intro, missing interactions, transient jump-state simplification, animation timing and close-wall camera limitation. Test against source geometry and build both packages without calling this a faithful full scene.

  10. Source-driven scene interpreter. Preserve synchronous AI action dispatch, original camera formulas and audio-duration advancement rather than adding a fixed intro timer or completingSCENE on intro end. Separate task activation, sprite playback, draw visibility and physical collision. Report unrecovered behavior explicitly. Preserve unknown TSK fields and original checkpoint resume; no claim of arbitrary-position/full-state save support.

  11. Separate supplied records from required content. All35 GAM entity files exist;33 have matching OMT geometry archives. Level3B/Level3E GAMs contain the same four entities apart from their level code, with no incoming serialized GAM transition or supplied save selecting them. Their original classes name absent OMT archives, but registration alone does not prove normal gameplay use. Record unavailable geometry without substitution; do not classify it as a reconstruction blocker or request more files unless progression requires it.

  12. Preserve source physics boundaries. Recovered quick magnitude, support trace, radii/factors and3DUD broadphase/triangle ordering stay separate from provisional wall/capsule response. Check isolated original DLL results without executing or modifying originals in place. Keep visual soles distinct from logical root75.9.

  13. Correct prototype names from original evidence. The pickup tagged SHRINKRAY is the jet pack in original objective art and inventory slot0/3 code. Practice0 entersVR04/PHONEBOOTH with current GAM/STRT return context. Do not invent a shrink-ray weapon or VR01 mapping. Later recovery identifies TSK StoredVector as the separate transition departure root; see decision17.

  14. Compose original UI and effect assets. Draw source640x480 UI in a separate depth-disabled overlay; retain clipped original coordinates. Use exact default SoundEffects.omt identities for lab effects, preserve encoded RIFF resources and document unsupported decoders. Do not substitute editor fonts/audio banks.

  15. Default recovered scene play. Start the integrated lab story/interactions by default; retain --inspect and deterministic smoke modes. Passing direct-contact tests does not establish navigation, original fidelity or full-game completion.

  16. Use recovered control and UI lifetimes. MCA PlayerControlled restores its target at completion; active valid shots clear control. O changes the objective animation timer rather than gadget layout. Reset air-turn state at the recovered grounded/released branch. Use per-level geometry-layer far limits; the current merged renderer uses their maximum until separate layer masks are implemented. Source evidence and regression limits are recorded in the focused analysis docs.

  17. Keep transition restoration separate from pickup checkpoints. Source RETURN flags preserve the departure root at+9A8, restore player/companion position and suppress STRT once. Serialize only the proven root in StoredVector; carry pending RETURN in memory. Retain authored STRT yaw and ordinary fresh-save spawning. Pickup42AF00's+1E38/+1E48 is a different, still-unconsumed capture.

  18. Apply terrain eligibility at shape registration. Source level loaders skip NC-prefixed shape names. Use prepared shape metadata for player and actor terrain queries; retain rendered geometry and null-material proxies. Do not infer a generic water-material rule or full water gameplay from this finding.

  19. Keep user-requested debug tools explicit. F1 opens a modern diagnostic menu with code-generated glyphs, separate from recovered UI assets. Pause gameplay and audio together, capture held input until release and stage SCENE edits until Enter. Invoke existing source-state consumers for actions; offer only prepared geometry and source startpoints. No debug behavior is attributed to the original. Force Control is a persistent debug override over authored ownership, with FALSE restoring the current scripted state. Reset/new scene clears it, and source music handoff continues to use authored ownership.

  20. Keep live diagnostics passive and session-owned. F2 and the F1 Live Overlay action change visibility without pausing gameplay/audio. Preserve this setting across scene rebuilds in memory, independently of TSK state. Reuse the existing font/buffers, give F1 display priority and measure wall-frame intervals separately from simulation ticks. Report the rendered camera/projection, not a guessed mode.

  21. Own presentation at application lifetime. Replace scene GPU resources transactionally, retaining the SDL window, Vulkan core and user window state. Size changes may recreate targets/swapchain. Per-level audio/gameplay remain separate; source fades are still open.

  22. Uniform UI with anchors. Preserve4:3 source positions, center modal/F1 canvases and anchor objectives bottom/right and F2 top-left. Map logical input through actual drawable dimensions with double precision for strict bounds. This is authorized modern widescreen policy, not original algorithm recovery.

  23. Pause feature expansion for architecture recovery. Preserve clean69d0187 as a local tag and independent package copies. Use the lab/tutorial/return/ outside route to map state owners, callers, phases and persistence before more gameplay. checkpoint/ supersedes older architecture/priority summaries. Evidence probes and directly evidenced corrections are permitted. A documented, gated implementation plan ends the investigation checkpoint; continue through it without waiting to understand every level.

  24. Separate task objective and entity phases. Original45FB5B selects the objective before task record mutation45FB7F and entity dispatch45FBD9. Expose pre-assignment notification rather than relying on subscriber registration order. Preserve repeated/missing assignment dispatch. Source loader's additional task callbacks/PostLoad are a distinct lifecycle question, not implied by this fix.

  25. Consume prior player motion before callbacks. Split controlled player physics, input, controller and fire effect phases. Fresh input precedes Jimmy; retained Jimmy/fire precede the appended destination game/input. Track this relation explicitly across scene continuations. Mode-based input and the player's grounded-release reset are separate boundaries. Keep fixed60Hz, capsule/support and other grouped scene callbacks explicit approximations.

  26. Use the source static camera predicate on proven route scenes. Build sparse grids in source shape/polygon order, prefer the first wall-grid hit, then the first all-grid hit. Use the individual source segment kernel without nearest reduction; apply source desired-eye weighting and gain before follow interpolation. Only LV1B/VR04/LEV1 filters are proven. Shared camera handoff, special follow/input state and exact x87 boundaries remain separate work.

  27. Apply gadget availability at level entry. Source PostLoad enables eight group0 gadgets4→1, then disables owned1→4 in VR01..08. Preserve unknown states, item8 and group1. This is availability, not acquisition or save normalization; snapshots/constructors retain raw wire data. VR04's source jetpack bypass remains.

  28. Expose implemented systems through modern debug tools. The user explicitly requests expansion and noclip during the gameplay feature pause. Preserve General-page controls; add Player/Systems pages and F3 flight. Keep authored control ownership separate from flight and bypass player contact triggers. Clear pending motion/held input at toggles, retain an entry escape position, and reset transient overrides on scene rebuild. Mute by stream gain so clocks continue. Debug checkpoint uses the existing TSK/start progression contract, never pretends to save live physics/cutscene state. These are investigation features with port verification, not recovered original behavior.

  29. Persist bounded retained scalars independently of resets. Ordinary route loads keep movement mode, jump-hold and owned-fire timer in a separate memory container for proven no-gadget/jetpack states. Reset jump/body/presentation through their own boundaries; do not serialize these fields in TSK or carry them through debug checkpoint load. Unsupported levels/gadget cleanup remain the existing explicit approximation until traced. First destination ticks can change retained values; boundary and post-tick tests are different.

  30. Read full PostLoad tails before asserting final availability. The prior common-prefix interpretation was incomplete. Each VR01..08 re-enables its practice gadget after the shared disable pass; LV1B disables1/7. Correct the implementation and expectations from the later dispatch/call evidence and retain the earlier report as a scoped historical audit with a correction.

  31. Control identity gates movement, not the whole player. Run eligible body physics and owned fire while raw control is absent; skip input/controller tail. Preserve queued work and distinct resets. Apply source-specific ordered preparations at CAM/MCA/AI activation; initial MCA target-none returns without completion, and later shots do not repeat preparation. STOP notification follows body clear. Authored transforms update the real player body. Keep modern Force/Noclip and frame pauses separate from raw ownership. Other wrapper/class callbacks and collision remain evidence gates rather than empty-input guesses.

  32. Use local REA as an additional static evidence source. Keep Ghidra/JDK and process environment local, analyze generated copies, retain complete Evidence/profile/hash/snapshots and close owned sessions. CLI avoids changing the existing MCP registration. Unknown procedure definitions remain unknown; they do not invalidate byte/vtable evidence or imply missing game code.

  33. Integrate collision in verified boundaries. Preserve source sphere kernel nearest state/face/edge semantics as an isolated component with original-code probe references. Keep live capsule replacement gated on traversal, callbacks, support/friction and dynamic response. Independently correct the proven Jimmy overhead wrapper using its root ray and mode-specific cancellation, retaining fresh/retained input order. Modern camera debug controls affect camera queries only. Do not reinterpret this partial correction as complete original physics.