Files
Neutron/docs/checkpoint/retained-player-body.md
T

6.4 KiB
Raw Blame History

Retained player: body reset and ordinary-load scalar boundary

2026-10-26. Original EXE SHA256 f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8. Preferred-base EXE VAs below map to raw offset VA−400000; the helper independently maps PE sections. Originals remain untouched. Static recovery, isolated component execution and port tests are separate evidence categories.

Continuation: uncontrolled body/fire and cutscene preparation are now implemented in a bounded C3 chunk; see control-phase-implementation.md. Full wrapper/base policies, body response and scene scheduling remain separate gates.

Closed callback chain

Read retained-streamer.md, retained-return-cleanup.md and retained-companion.md alongside this report. Together they close the bounded no-selected-gadget/jetpack route path through deferred load, property read, generic Init, Jimmy PostLoad and final control preparation. The property reader does named descriptor writes without an implicit constructor/reset callback. Route game Init28 resolves44D4E0→4587F0→470540. Game control118 resolves475A40, which writes global5099E4; it does not itself reset Jimmy's movement mode.

Generic Init470540 re-applies authored vectors through virtual getters/setters:

Quantity Authored interface field / getter Live field / setter Init caller / physics consumer
Acceleration 3C..48 /11C→471290 164..170 /274→471BD0 4706EA→47070F;479F01 reads270→471B70,479F4A adds acceleration×dt to velocity
Queued impulse 4C..58 /124→4712E0 174..180 /288→471CC0 47071E→470743;479EBB reads284→471C60,479EE5 adds it,479EF2 clears via28C→471C90
Velocity 7C..88 /13C→4713D0 1A4..1B0 /2C0→471F70 4707BA→4707DF;479F8D reads2BC→471F10

All copied vectors have four float components. These are authored→live copies, not unconditional zero writes and not arbitrary preservation of the prior live body. Route GAM JIM1 records do not contain these authored vector properties; their source constructor/class defaults remain distinct from property extraction. The port currently initializes its provisional body vectors to zero.

Jimmy PostLoad's common tail424472 grants control;42447D invokes410→42AFC0. 42AFC3 calls43A750, which clears speed608 at43A758 and invokes2C4(0,0,0) at 43A764..43A76C. Target471F40 writes velocity1A4/1A8/1AC; it does not overwrite the fourth component1B0. Complete148 stops the saved sound, then the derived preparation requests STOP animation. Neither null control nor this preparation means all scene physics stops. Uncontrolled-body scheduling remains a next chunk.

Generic Init also clears274/278/27C and298; these are separate cached fields, not the acceleration/impulse vectors above. Do not confuse a virtual slot number with a same-numbered member offset.

Bounded retained-state contract

State Boundary behavior and evidence
Movement mode complete7C4/interface704 Constructor zero is not repeated; absent from route GAM, generic Init and resolved no-gadget/jetpack cleanup/PostLoad writes. Retain.
Jump hold complete874/interface7B4 Same bounded absence after closing property/control paths. Retain; later state0 takeoff resets it independently.
Owned fire timer complete6C0/interface600 Fire retained object; generic28/40C do not reset it; jetpack cleanup does not own it. Retain. First grounded fire tick421FE9 zeros it before subtracting dt.
Jump state complete7E8/interface728 PostLoad42378B resets WORD to0. Do not carry with mode/hold.
Speed608, turn614, scalar618, destination yaw61C Jimmy Init437890 clears first three and captures authored logical Euler.Y; final preparation clears speed again.
Body vectors, support, radius, collision contacts Re-apply their own initialization/PostLoad policy; not copied in the scalar container. Source radius60/factor1.265 reasserted. Full registration/response remains open.
Selected gadget Cleanup and destination selection have their own state machine; not persisted by this scalar container.
Goddard/shadow Identity survives; Init/PostLoad restore specific authored AI, waypoint, target, rotation/resource/visibility state. No blanket AI or shadow-state carry.

This is a boundary contract. A first destination controller/effect callback can change the same scalar immediately. Observing the timer after grounding is not a test of whether the loader reset it. Other gadget cleanup branches explicitly change movement mode; other level tails remain unported and need separate proof. The full ordinary loader and original route have not been executed end to end.

Port implementation and verification

PlayerLevelState carries only mode/hold/fire in memory for LV1B/VR04/LEV1 and selected gadget−1/3. Apply follows new scene construction and precedes scene playback. Destination jump state starts0; body, presentation and debug settings initialize independently. Noclip does not capture a carry state. Unsupported levels/gadget cases use the existing reconstruction policy, explicitly unproven. TSK/CLI/debug checkpoint load gets no scalar container; no wire format changed. R reset remains the authorized modern reset, clearing these transient fields.

Movement tests use nondefault mode/hold/fire sentinels, then independently verify body/jump reset, airborne first tick, grounded release/effect reset, unsupported scope and explicit reset. The GPU practice/RETURN fixture seeds nondefault values and asserts the actual cross-scene bridge before the destination's first tick. These are port regressions, not original cadence or whole-route fidelity evidence.

Static helper: python3 tools/binary/retained_player_body.py ../Original. Two evidence tests guard26 instruction sites and16 virtual targets. The C probe maps an isolated copied EXE without entry point/import initialization, calls the original vector leaf accessors and43A750 with sound handle−1, and compares all other sentinel bytes. Synthetic fixture vtables use byte-guarded source targets in a rebased copy; selected paths use no absolute globals or unresolved imports. The isolated Wine32 probe passes; it is intentionally narrower than full Init/PostLoad. Runtime probe outcome and full integration/package evidence are in progress.md.

Remaining: body registration4623D0, original support/response and cadence, uncontrolled controller/fire phases, exact registry traversal of newly appended helpers, other selected gadgets/level tails and original end-to-end comparison.