Files
Neutron/docs/decisions.md
T

397 lines
29 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Decisions
User workflow update (2026-11-05): completed, verified milestones are now pushed
to the existing `Gitea` remote at `https://gitea.unixnight.com/UnixNight/Neutron.git`
on `main`. This explicit user instruction supersedes earlier local-only Git
restrictions in prompt.MD and AGENTS.md. Builds/tests remain local; original
assets and generated packages stay excluded.
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, commit code/docs/tools only. The original
no-remote rule is superseded by the user workflow update below.
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.
34. **Compose body response only inside recovered contact coverage.** Preserve
signed material database IDs in collision metadata and reject legacy prepared
data lacking identities. An ordinary-only adapter may start with VR04, whose
static materials have no special Player374 policies; lab/outside contain
special contacts. The tested grid dispatcher is an isolated component until
body/landing/friction order and root visuals are compared; dynamic reclip
must explicitly own shared nearest/last-polygon state. Keep source published
speed160 separate from controller608. Geometry-off gravity cancellation must
not be reinterpreted as an ordinary prior-grounded jump rule.
35. **Enable the tested static body subset in VR04.** Compose verified traversal,
support and friction using original body-reference outputs. Reject special
scenes/provisional dynamic resolver and keep lab/outside on the baseline.
Preserve source60/100 radius changes through both sphere response and support;
restore60 in the later Jimmy wrapper. Published speed160 survives control
preparation separately from controller608. No dynamic-door geometry does not
establish absence of other source dynamic actor classes. Modern feet/sole and
noclip admission remain explicit policies; this is not whole-tutorial fidelity.
36. **Keep gadget display, equipped mode and owned effects distinct.** The user
parked collision work and requested gameplay gadgets. Integrate original
group0 resources/state and default item3 first: its display index is3 but raw
mode remains−1. Do not treat the default shrink-ray/jetpack as special mode3
or call Bubble mode0 Scooter. Reuse original heading, strict multi-target
gates and nonloop soldier morph; ordinary hits award10 through the score/save
owner. Expiry restores authored/reset AIState, not pre-hit dynamic mode.
Keep modern full-panel pause, upright effect transform, additive branch and
blended-depth policy explicit. Other gadgets, full AI and warning-audio
lifecycle remain independent evidence gates, not guessed feature completion.
37. **Preserve timed gadget and cleanup ownership.** Invisible's seven-second
recharge/active clocks run after movement with any nonnull controlled pointer;
raw-null pause is distinct from cleanup. CAM/MCA default DeactivateInv to1
and explicitly release named Jimmy before target validation, independently
of raw-owner438. Keep failed display2/raw−1 selection, source blend flashing,
original meter art and companion body flags separate from AI activation.
Energy scalar and warning latch share one session owner; raw saved/refill
assignment is not a helper-driven warning rearm. Full enemy sensing,
suppression globals, graphics options and canvas alignment remain explicit.
38. **Integrate Bubble's controller and body together.** Mode2 is persistent and
has fire throttle, its own turn cap and direct300/900 supported bounce; it
must not enter the ordinary550/jetpack table. Pass radius160/factor.415 to the
tested static body, preserve queued work/root and restore source650 maximum
on cleanup. VR01's floor111 has a retained-material callback even in air, so
implement that bounded policy with original bypass/debounce/material ordering.
Original Canv1 remains an independently updated sprite with full RGBA fade,
not invented sphere geometry. Keep the render bridge, generic camera/Euler,
other damage states and retained helper lifetime explicit. Bubble practice
precedes live equip; menu gating reads raw mode, not display selection.
39. **Keep Baseball ownership beyond selection.** Preserve the original20-slot
ring, pending release after cleanup, prior-capture label and source release
cost/sound order. Landing queues a full impulse before support clears Y;
use a ball-specific profile rather than Jimmy callbacks. VR07 target state
belongs to source instances despite duplicate tags, with strict parent hit
threshold and conditional collision activation. Exact TIME glyph binding
replaces the temporary font policy. Keep current sphere-pair discovery,
angular reflection, mouse/analog aim and helper retention across loads explicit.
40. **Save Scooter recovery before implementing it.** Its separate C3DJEEP actor,
mount/control handoff and wheel-dependent drive/support cannot be represented
by a Jimmy mode or an invented constant wheel count. Preserve the source
report/exporter and close wheel bodies before live Scooter integration.
41. **Use supplied jn-engine as research, not a replacement runtime.** Same EXE
declaration and415 byte-identical shared assets support cross-indexing its
class specs/decompiler bodies and adapting bounded tests. Different declared
OMT2.dll, mixed pointer bases, forced prototypes and explicit native gameplay
tunings require independent checks. Retain C#/.NET10/SDL3/Vulkan and REA byte
evidence. Capture tooling/derived scenes are present; raw OMTC, analysed
Ghidra database and proposed gameplay state traces are not. Record offered
permission before source import. Assessment: reviews/jn-engine-survey.md.
42. **Verify vehicle arithmetic before connecting live ownership.** RocketFlight
preserves per-callback input acceleration, support/brake ordering and retained
vertical-command publication, compared with28 isolated copied-original cases.
Radius50 is collision size, not render scale; rates650/−650 are acceleration,
not assigned velocity. Do not substitute Jimmy's body/camera for aircraft
callbacks or claim the scalar component is a live Rocketship. Resolve owned
versus placed properties, passenger/effect lifetime and control/camera phase
before VR02 integration. Grappler's geometry/material/swing contract likewise
forbids nearest-hook/direct-pull replacement. See gameplay/rocketship-component.md.
43. **Compose the owned Rocketship in boundedVR02.** Preserve source registration
order, rider static-body work, separate raw control/menu permission and
named-Jimmy cleanup.1E4 is a dynamic-pair flag, not an integration gate.
Dedicated source callbacks, Euler seam, maneuvers, LOOK-to-eye camera and
passenger/flame pivots replace provisional movement/render assumptions.
Require source/probe admission for other materials/levels; no nearest-ship,
invented boost or direct vertical-velocity substitute.96 isolated component
observations support contracts; live SDL/Vulkan replay verifies the port,
not whole-original or native Windows fidelity. See gameplay/rocketship-live.md.
44. **Identify field consumers before assigning render semantics.** Rocketship's
four impact writes are first-material diffuse RGBA, not shape scale. The
copied suffix probe validated numeric values but its synthetic buffer and
historical `scale` label did not establish their meaning. Constructor and
actual DLL renderer consumers now guard the contract. Use a ship-only red
material flash with unit geometry; regress vertex positions as well as values.
See gameplay/rocketship-impact-render.md.
45. **Keep inspection in the gameplay coordinate convention.** A right-handed
view/perspective pair can render a valid frame while mirroring a positive-Z
source scene relative to gameplay. OrbitCamera now owns the matching
left-handed view/projection; apply the shared Vulkan Y correction only once.
Regress screen right/up and depth across camera poses, not frame presence
alone. The modern inspector is separate from recovered original camera logic.
46. **Keep Grappler cursor/attachment and input/normal gates distinct.** The leaf
attachment helper lacks cursor filters, but aim's earlier true return ends
active input before that helper. Do not interpret it as a rejection bypass.
Attached input may return early while ordinary Jimmy frame publication still
runs. Compare isolated sqrt/first-scale/reel/damping with original snippets
before composing body/camera/helper ownership; do not invent250 clamps or a
detach impulse. GrapplerMotion remains isolated until those gates close.
47. **Keep Grappler query metadata and component boundaries explicit.** Capture
the actual first selected polygon/material with its hit. Preserve root versus
swing-pivot origins, quick-magnitude constraint order and strict>60 contact
detach. Native aim/constraint/post-base suffix probes do not establish the
full body context, base contact, camera or helper lifecycle; close those
contracts before liveVR08. See gameplay/grappler-query.md.
48. **Bound Grappler's shared collision and persistent helper state.** Reuse the
preceding source-body sphere context in attached47B4B0, including stale last
polygon callbacks; support/ray metadata is separate. Keep scalar memory at
session scope and helper/audio state at scene scope. Explicit RETURN cleanup
is recovered; ordinary reconstructed-scene disposal is a modern safety
boundary. Preserve first geometry scale across reattach/reequip/load. Camera
offsets are locals consumed by separate ground/air branches, not world poses.
Exact SWING uses its own source-pivot draw. See gameplay/grappler-live.md.
46. **Scooter owns a vehicle body and real wheel supports.** Normal item4 selection
summons at Goddard; strict later contact mounts. Keep scalar/live velocity/
pending impulse and body/input/frame/wheel phases distinct. Enable bounded
VR05 and outsideLEV1 from the normal owned tile. Use source body150/.2,
four narrow wheel offsets, explicit prevent-lowering/bounce overrides,
face-only camera clip and exact unscaled art. Preserve parked Jimmy collision.
Native component comparison, managed integration and port rendering establish
separate coverage; no complete original/Windows parity is inferred.
47. **Fix Scooter handoff consumers and sound channel processing.** Preserve
copied dismount Euler, then run source Goddard X/Z leveling with.3 factors
in the supported follow bridge. Preserve the nominal engine pitch command,
then apply recovered47D9D0 positional frequency/history and DX bounds.
Use shared listener state for mounted/parked/script cameras; global audio
cadence and attenuation remain separate. See the focused gameplay reports.
48. **Stabilize Jimmy from authoritative components while preserving the playable baseline.**
Use JN's original decompiler index as leads only. Integrate source ground/air
input, velocity, full-axis base facing and precise jump hold/gravity after
copied-original comparison. Preserve retained targets and keyboard-turn latch;
facing runs without raw input ownership. Require real support polygon338 for
downward ground pressure; do not translate capsule Grounded into that state.
The failed stair route and successful compatibility rerun are retained evidence.
Keep ordinary air pitch/actor-root visual bridge together as the next chunk,
and special/root-changing/dynamic body behavior behind independent gates.
See gameplay/jimmy-movement-stabilization.md.
49. **Keep air input, facing and the logical-root visual bridge together.**
Pitch seeds are retained apply-owned fields, not per-input mode constants.
Init clears destination Euler/dirty independently of current full STRT Euler.
Publish full authored/current XYZ and enable ordinary pitch/turn lean with
source hierarchical rotation/degree caching. Retain upright foot alignment
as an explicit local model correction around the logical root; do not call it
an original pivot offset or mutate source geometry/body support. Defer OMT's
final approximate-angle model decomposition with its measured seam mismatch.
Broader special/dynamic collision retains separate gates. See jimmy-air-bridge.md.
50. **Preserve contact-owned root and body modes instead of treating world-off as noclip.**
Keep current/previous full Vec4, anchor and source integration/support/
collision/world/alternate gates independently. Only fresh XYZW equality permits
publication of the original candidate; callback roots do not inherit stale
falling displacement/clamp. Landing callback root/anchor/acceleration/impulse/
modes persist, while cached velocity/support publication follows afterward.
World-off still integrates and may support; collision-off has its own hold/
translation branch. Preserve inactive-path context. Retain the lab/outside
capsule until real Jimmy callbacks and multi-frame/dynamic ownership are proven.
See checkpoint/body-contact-implementation.md.
51. **Camera orientation preparation replaces the facing destination too.**
Source CAM/MCA flatten current and game+274 destination to current yaw with
pitch/roll0; direct writes preserve facing dirty. Reset both on that existing
preparation boundary, not on every input lock/STOP/DEFAULT.20 isolated native
cases verify this state ownership. Neutral grounded input instead retains
residual destination bank in seven source trajectories; no unproven universal
landing snap is added. Another whole-frame writer or original quirk remains
open. See gameplay/jimmy-rotation-handoff.md and its two source reports.
52. **Recover full cutscene lifecycle before further symptom fixes.**
User redirects work to decompilation first after confirming a distinct
post-skip idle bank. Preserve the current runtime/packages; diagnose and
document original entry/contact/skip/control/input ordering before resetting
movement fields or changing the scheduler. Current source/component findings
do not yet explain the whole-original upright return. See
gameplay/jimmy-cutscene-decompilation.md for the recovery gate.
53. **Observe the actual original handoff when composed source matches the port.**
292 new bounded original-code cases do not establish another movement reset;
fresh input-before-player composition itself restores bank. Retain the user's
upright-original requirement without inventing an owner/DEFAULT/animation reset.
Use the copied-original read-only observer to measure actual route state and
registry membership. Its successful Wine32 attach is tool validation, while
MAIN-only black frames are not gameplay evidence. Keep runtime/packages fixed
until the source/differential gate closes. See gameplay/jimmy-cutscene-lifecycle.md.
54. **Classify successful TSK story entry as retained-player order.**
Source application startup loads backgroundLevel1D/Jimmy; successful TSK
destination requests use an existing controlled C3DJIMMY and the ordinary
selective teardown/reuse path. The new level game follows that retained node,
including first playable New Game. Program's carriedSave-only test was too
narrow. Include TSK-backed story entry, keep fresh direct-scene simulations,
and preserve rotation/movement algorithms. Baseline first-neutral input
republishes−10° bank; corrected startup order stays upright through300 idle
ticks. Original runtime/native Windows comparison remains distinct. See
gameplay/main-menu-player-lifetime.md.
55. **Retain source pair ownership before admitting a replacement scene loop.**
47A430 uses physical registration order, live callbacks and eligibility gates
that preserve old contacts. Sphere47CA90 checks only the earlier actor's
exclusions; successful responses precede independent membership notifications.
The28-case original/C# component implements that bounded contract with an
explicit box solver. Keep it outside live gameplay until full registration,
real actor callbacks and shared reclip dependencies close. Render visibility
and raw-control flags are not substitutes for physical eligibility. See
checkpoint/pair-lifecycle.md.