Files
Neutron/docs/decisions.md
T

141 lines
11 KiB
Markdown

# 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.