From 9ad5a8ef6b67bd877964b7b3ba60bcaddb3edd6f Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Mon, 26 Oct 2026 03:58:52 -0400 Subject: [PATCH] Recover retained route state and complete PostLoad availability tails --- docs/architecture.md | 12 ++ docs/checkpoint/README.md | 5 + docs/checkpoint/coverage.md | 7 +- docs/checkpoint/implementation-plan.md | 19 ++ docs/checkpoint/retained-character-reset.md | 13 +- docs/checkpoint/retained-companion.md | 127 +++++++++++++ docs/checkpoint/retained-player-body.md | 90 +++++++++ docs/checkpoint/retained-return-cleanup.md | 122 ++++++++++++ docs/checkpoint/retained-streamer.md | 99 ++++++++++ docs/checkpoint/review.md | 6 +- docs/compatibility.md | 17 ++ docs/debug-menu.md | 4 +- docs/decisions.md | 13 ++ docs/progress.md | 44 ++++- docs/reverse-engineering.md | 5 + docs/tasks.md | 11 +- src/GamePort/Game/LabSimulation.cs | 18 ++ src/GamePort/Game/PlayerLevelState.cs | 15 ++ src/GamePort/Game/SceneInventory.cs | 18 +- src/GamePort/Program.cs | 42 ++++- .../GamePort.InteractionTests.csproj | 1 + tests/GamePort.InteractionTests/Program.cs | 12 +- tests/GamePort.MovementTests/Program.cs | 33 ++++ .../GamePort.PatrolTests.csproj | 1 + tests/test_checkpoint_character_reset.py | 2 +- tests/test_retained_companion.py | 54 ++++++ tests/test_retained_player_body.py | 31 ++++ tests/test_retained_return_cleanup.py | 69 +++++++ tests/test_retained_streamer.py | 52 ++++++ tools/binary/checkpoint_character_reset.py | 6 +- tools/binary/retained_body_probe.c | 81 ++++++++ tools/binary/retained_companion.py | 157 ++++++++++++++++ tools/binary/retained_player_body.py | 84 +++++++++ tools/binary/retained_return_cleanup.py | 173 ++++++++++++++++++ tools/binary/retained_streamer.py | 141 ++++++++++++++ tools/recon/reference_capture.py | 7 +- 36 files changed, 1559 insertions(+), 32 deletions(-) create mode 100644 docs/checkpoint/retained-companion.md create mode 100644 docs/checkpoint/retained-player-body.md create mode 100644 docs/checkpoint/retained-return-cleanup.md create mode 100644 docs/checkpoint/retained-streamer.md create mode 100644 src/GamePort/Game/PlayerLevelState.cs create mode 100644 tests/test_retained_companion.py create mode 100644 tests/test_retained_player_body.py create mode 100644 tests/test_retained_return_cleanup.py create mode 100644 tests/test_retained_streamer.py create mode 100644 tools/binary/retained_body_probe.c create mode 100644 tools/binary/retained_companion.py create mode 100644 tools/binary/retained_player_body.py create mode 100644 tools/binary/retained_return_cleanup.py create mode 100644 tools/binary/retained_streamer.py diff --git a/docs/architecture.md b/docs/architecture.md index 69a2b0f..f35be5b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -178,3 +178,15 @@ buffers/textures/descriptors, preserving device/surface/swapchain/layouts/pipeli and current targets. Resize/fullscreen replace size-dependent resources. Revision and native identities support checks. See presentation-and-ui.md for rollback, widescreen policy and runtime verification boundaries. + +## Bounded ordinary-load character state + +PlayerLevelState is separate from OriginalSave: it carries only mode, jump-hold +and owned-fire timer across proven LV1B/VR04/LEV1 no-gadget/jetpack transitions. +Run reconstructs destination resources/body and applies these scalars before +playback. Source jump state resets independently; TSK/debug checkpoint loads get +no transient carry container. Source retained identity does not justify persisting +all physics/AI/render fields. The detailed contract, phase limits and original +component probe are in checkpoint/retained-player-body.md; companion/shadow +resets and full availability tails have separate reports. Uncontrolled physics +and exact appended-helper traversal remain next scheduler boundaries. diff --git a/docs/checkpoint/README.md b/docs/checkpoint/README.md index 02af81f..772aadf 100644 --- a/docs/checkpoint/README.md +++ b/docs/checkpoint/README.md @@ -18,6 +18,11 @@ Implementation continuation: [level-game lifetime](level-game-lifetime.md), [retained character resets](retained-character-reset.md), and [player phase implementation](player-phase-implementation.md). These supersede the old-game-removal question and record the first C3/C5/C7 implementation chunks. +The retained-field continuation adds [property reader](retained-streamer.md), +[RETURN cleanup and full availability tails](retained-return-cleanup.md), +[player body/scalar boundary](retained-player-body.md) and +[companion/shadow resets](retained-companion.md). It corrects the earlier +availability-prefix interpretation and implements bounded route scalar carry. Evidence labels used throughout: diff --git a/docs/checkpoint/coverage.md b/docs/checkpoint/coverage.md index 6b4f909..9927d9d 100644 --- a/docs/checkpoint/coverage.md +++ b/docs/checkpoint/coverage.md @@ -14,7 +14,7 @@ runtime comparison. Coverage does not mean implementation completeness. |---|---|---|---|---| | LOOP | Viewport47E4F0 physics before registry473740, including input44DF80; second sync473770; construction order and selective retained-character/new-game ordering. Separate engine morph clock. | Player now integrates prior body state, then fresh input/player/fire or retained player/fire/input. Other systems remain grouped; fixed60Hz policy. | S/M/R. Controlled player partial order implemented; full registry/cadence and uncontrolled-body preparation open. | C3 continue other callbacks and morph/control phases; C4 support/response remains separate. | | INPUT | Game interface+8C slot3C4→44DF80→475A70 reads controlled5099E4 and calls3CC; Jimmy interface+C0→426030. | SDL arrows/jump aliases; control gate, modern debug override; mouse/controller incomplete. | S/M/R, user Windows route. Input occurs in object traversal after physics; device sampling/focus and latency open. | Trace event pump, key/mouse and focus gates alongside retained registry order. | -| MOVE |437940/439900 ground/air arithmetic; physics479D20 consumes queued impulse once before acceleration/gravity. | Recovered arithmetic placed in same-tick controller→physics; fixed dt, custom yaw/model conventions. | S/P/M/R. Local arithmetic evidence does not validate enclosing phase. | Split pending velocity/impulse only after C3 oracle. | +| MOVE |437940/439900 ground/air arithmetic; physics479D20 consumes queued impulse once before acceleration/gravity. | Controlled player consumes prior body state before callbacks; fresh/retained input order explicit. Fixed dt and custom yaw/model conventions remain. | S/P/M/R. Controlled partial phase split verified; uncontrolled/full registry and body response open. | Continue C3 uncontrolled phases, then C4 support/response. | | JET |437F90 controller;421FB0 effect; fresh constructor order places fire after Jimmy, both after global physics. States0..5, hold>.4,8s, energy. | Explicit state table with post-collision effect ticking and VR immunity. | S/M/R. Fresh same-pass countdown recovered; retained child lifecycle, sound and expiry→animation open. | Trace retained Jimmy/fire resets and phase end events before scheduler integration. | | COLL |479D20/47BD80 body response; support and quick magnitude; dynamic boxes; NC-shape registration exclusion. | Source support and box pieces around modern swept24-unit capsule, feet/root grounding and slide. | S/P/M/R. Response/masks/stairs/contact order not fully recovered; source radius60 is not port capsule24. | C4: isolate response and root convention; replace adapter behind route tests. | | ANIM | Engine morph10002DB0; linear interpolation10002F9A; game logical→OMT sync4624B0. | ASE sample timing, unconditional loop closure, pose/action aliases,1/60 advance. | S/P/M/R. Playback flags, rate, completion callbacks, transition order open. | Recover one-shot/loop/end notifications before more aliases. | @@ -23,8 +23,8 @@ runtime comparison. Coverage does not mean implementation completeness. | CAMERA | Shared viewport; strict>1000 DEFAULT snap; source eye correction/gain; first wall-grid hit then general-grid FIFO; per-level far planes. | Static source query now integrated for the three route scenes; other scenes use provisional sweep. Separate chase/script eyes and merged clip maximum remain. | S/M/R. Query/kernel/counts tested; x87 boundaries, shared handoff/previous-eye and input branches open. | C5 next shared viewport/DEFAULT and complete follow state. | | AUDIO | CAM416776..E1 stops music; DEFAULT447F12..45 restarts; bank696008 / gate4F8434; handle47D890 polls inherited software duration and repeat+30. | Separate SDL streams, floating-file-duration cutscene completion, independent per-file SFX. | S/M/R (dummy streams). Source duration/allocation/play-failure/bank/attenuation lifecycle incomplete; speakers/native Windows timing not verified. | C6: explicit bank owner and software channel-clock tests; SDL queue-empty is not the source oracle. | | UI |406F50 selector/timer;4043D9 controlled clock;407070/O edge;404D97 practice resume.44 objective flags distinct from selector. | Timed objective subset, modal practice, modern UiViewport/debug. | S/M/R. Other flags/gadgets/highlights/cursor/energy/layout transitions open; source widescreen not recovered. | Keep modern scale policy separate; recover UI dispatcher/mode gates before expanding. | -| LOAD | CEditor deferred scene request; selective teardown/reuse; Init stored+11→live+139 resolves old-game deletion; Jimmy/Goddard retained. RETURN root/flags and per-object28→40C. | Snapshot/reconstructed scene state with retained input-order identity; app-owned presentation. | S/M/R. Old-game removal closed. Per-field/helper resets and fades remain;50988A is editor R input. | C7: retained-field/route lifecycle fixtures, then state-container integration. | -| INVENTORY | PostLoad423DEF..423EC1 enables eight owned gadgets4→1, then VR01..08 disables1→4; other values/items preserved. | Availability pass now applied at level entry and verified across TSK tutorial/return; snapshots preserve raw values. | S/M/R. Full selected-gadget/UI and retained scalar state remain incomplete. | Keep availability separate from ownership, task changes and arbitrary state carry. | +| LOAD | CEditor deferred scene request; selective teardown/reuse; Init stored+11→live+139 resolves old-game deletion; Jimmy/Goddard retained. RETURN root/flags and per-object28→40C. | Reconstructed scene with retained input-order identity and bounded mode/hold/fire container; app-owned presentation. | S/P/M/R. Property stream and bounded scalar/companion resets closed; full body/helper timing and fades remain.50988A is editor R input. | Continue body registration/helper traversal and uncontrolled scheduling; other gadget/level branches remain gated. | +| INVENTORY | PostLoad common prefix enables eight owned gadgets4→1, then VR01..08 disables1→4; full tail re-enables the practice gadget. LV1B disables1/7; other wire values preserved. | Availability pass now applied at level entry and verified across TSK tutorial/return; snapshots preserve raw values. | S/M/R. Full selected-gadget/UI and other level tails remain incomplete; bounded route mode/hold/fire carry is implemented. | Keep availability separate from ownership, task changes and arbitrary state carry. | | SAVE | TSK45FEE0 writer /4603F0 reader; records, arrays, return strings, stored departure root; queued460E70→460EA0. | Original-format round-trip and CLI save, scene snapshots; no full source save UI/load lifecycle. | S/M. Source reader duplicates matching task callback then all-entity420 post-task hook; this is distinct from Jimmy placement PostLoad423A90. Current fresh-director path differs. | C7 after C1/C2; test repeated callbacks before adopting loader behavior. | | CHECKPOINT | Pickup42AF00 stores+1E38 root/+1E48 level separately from+9A8 RETURN root. | Capture exposed, not used for return; source capture consumers unknown. | S/M. Do not interpret as death/respawn until read consumer found. | Track unresolved consumer; no speculative gameplay. | @@ -41,6 +41,7 @@ runtime comparison. Coverage does not mean implementation completeness. | Pickup checkpoint complete+1E38/+1E48 | Pickup callback42AF00 writes; read consumer not proven | Do not equate with departure root or invent reset/respawn semantics. | | Music/effects/cutscene voice | CAM takes bank/voice and stops music; DEFAULT restores source defaults | Runtime bank/handle lifetime, not task ownership; current port independently opens WAVs. | | Viewport/camera target | CAM/MCA target/eye; DEFAULT snap and follow; clip/layer resource settings | Original camera handoff is shared viewport state; baseline chase and scripted cameras diverge. | +| Jimmy mode/hold/owned-fire timer | Constructor, controller/fire ticks; property/Init/PostLoad/cleanup boundaries traced for supported route states | Ordinary route container retains these scalars; jump/body reset independently. TSK/debug checkpoint load carries none. First grounded tick can clear retained mode/timer. | | Modern application presentation and debug | RenderSession keeps window/GPU; debug visibility across loads | User-authorized session policy, outside original TSK or gameplay claims. Scene audio/gameplay disposed/recreated. | ## Assumptions and symptom-level adapters to replace diff --git a/docs/checkpoint/implementation-plan.md b/docs/checkpoint/implementation-plan.md index 1b5be25..42b600b 100644 --- a/docs/checkpoint/implementation-plan.md +++ b/docs/checkpoint/implementation-plan.md @@ -81,3 +81,22 @@ allowed where it resolves a core-system question, without waiting for every leve unavailable; source full integration validated above. Package evidence recorded separately without changing runtime. Continue the remaining source-state and shared-camera/control/collision gates rather than resuming feature expansion. + +- Retained-field continuation2026-10-26: property extraction has no hidden reset + callback; generic Init re-applies authored body vectors, final preparation clears + velocity/speed, Jimmy jump state resets separately from mode/hold/fire. Bounded + route/no-gadget/jetpack PlayerLevelState now carries only those three scalars + through ordinary transitions, never TSK loads. Companion/shadow reset fields and + same-state AI guard are documented; body registration/new-helper timing remain. +- Corrected C7 prefix-only availability: full VR01..08 tails re-enable the practice + gadget0..7, so owned VR04 jetpack finishes1. LV1B disables gadgets1/7. Managed + state boundaries/unknown values and GPU practice/RETURN guard the correction. + Other level-specific selection/availability tails remain an explicit gate. + +- Retained continuation validation:84 Python,22 movement plus remaining managed + groups,26 enabled-validation GPU renders, final nondefault tutorial/RETURN + boundary replay, four final SDL dummy checks and539 original hashes pass. + Original43A750/vector leaf component probe passes in isolated Wine32; this is + separate from whole-loader/original-game/native-Windows validation. Next gates: + uncontrolled body/controller/fire scheduling, body registration/helper traversal, + C4 response/root and shared camera handoff. See progress.md for test-race details. diff --git a/docs/checkpoint/retained-character-reset.md b/docs/checkpoint/retained-character-reset.md index af7ba59..70b970c 100644 --- a/docs/checkpoint/retained-character-reset.md +++ b/docs/checkpoint/retained-character-reset.md @@ -9,6 +9,17 @@ checks individual bytes, virtual targets and source route GAM properties. This report distinguishes proven local resets from fields whose enclosing retention/property/callback semantics remain unresolved. No runtime code changed. +## Superseding continuation (2026-10-26) + +The bounded investigation below was an initial local-prefix audit. Its old claim +that VR04 finishes with jetpack state4 is incomplete: the full level-specific +PostLoad tail re-enables the practice gadget, so owned jetpack finishes state1. +LV1B additionally disables gadgets1/7. See retained-return-cleanup.md for all +VR01..08 tail calls. Runtime/tests now apply those complete tutorial/route rules. +Property callbacks and bounded scalar carry are closed by retained-streamer.md, +retained-player-body.md and retained-companion.md. Later sections preserve the +initial evidence and explicitly limited scope, not the current final-state claim. + ## Enclosing ordinary-load phases The common loader evidence remains `scene-loader.md`: selective teardown, GAM @@ -128,7 +139,7 @@ owned1→4; return lab converts4→1. The VR04 powered-jump path bypasses the no inventory state guard, so source state4 here does not imply the tutorial jetpack should fail. Lab→outside similarly normalizes these group0 entries; tasks, score and acquired-table state remain independent. The audited baseline lacked this -availability pass. Continuation now calls `SceneInventory.ApplyLevelAvailability` +availability pass. The first continuation called `SceneInventory.ApplyLevelAvailability` once on level entry, before starting the authored sequence, and preserves raw values in constructors/snapshots and arbitrary task assignments. Managed tests cover every VR01..08 code, all relevant/unknown state boundaries, both untouched diff --git a/docs/checkpoint/retained-companion.md b/docs/checkpoint/retained-companion.md new file mode 100644 index 0000000..7d51079 --- /dev/null +++ b/docs/checkpoint/retained-companion.md @@ -0,0 +1,127 @@ +# Retained Goddard and shadow: ordinary-load reset trace + +Static investigation,2026-10-26. Original EXE SHA256 +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. +All VAs below are in this EXE at preferred base400000; inspected raw offsets are +**VA−400000**, independently PE-mapped by `tools/binary/retained_companion.py`. +No original code was executed. No runtime implementation was changed. + +## Identity, caller and property boundary + +Goddard complete vtable49F920 is installed at41C866; its game-interface table +49F480 is installed at41C883 with complete+C0 receiver. Shadow complete table +4B3C1C/game-interface4B37B8 are installed at43F6A0/43F6AD, interface complete+C8. +Constructor retention/reuse writes remain as recovered in scene-loader.md: +Goddard41C99B..41C99E passes0 to470F40, and41C9C0 sets complete+C9=1. +These are constructor facts, not repeated initialization. + +The route GAMs level1b.gam/LV1B, VR04.gam/VR04 and level1.gam/LEV1 contain **no +3DOG or3SHA serialized records**. Their bounded GAM parses/hashes are emitted by +the helper. Consequently ordinary reuse on this route does not stream a new +Goddard/shadow property record. The app's per-object Init28→PostLoad40C registry +pass still runs on their retained interfaces (scene-loader.md). A fresh companion +is dynamically constructed by Jimmy PostLoad when his interface95C pointer is +null:423C6A tests it;423C98 calls Goddard constructor41C810;423CAE stores it. +Existing pointer takes423CD4..423CE2 instead, discussed below. Exact same-pass +handling of a newly appended companion remains a registry-order question. + +## Goddard Init and PostLoad + +49F480+28→41E6A0 tail-jumps407EB0. At407EB3 it calls generic4587F0;407EB8 sets +interface byteA=1;407EBC..407EC2 copies authored87C→current AIstate608; +407EC8 clears current waypoint800. Complete offsets add C0. This replaces current +AI state and waypoint, not all AI fields. In constructor41C90E/41C914, current +complete6C8 and authored complete93C both start4. + +49F480+40C→41E590 calls shared actor409480 at41E593. Its local work, in order: + +| Source VA / raw coordinate | Reset or refresh | +|---|---| +|409486 /9486|Call generic40E7B0 visibility/animation policy; not a constructor.| +|40948B..40949A /948B..949A|Resolve tag string interface6AC through474070; always assign resulting pointer to600.| +|4094A0..4094FD /94A0..94FD|Only if pointer nonnull: refresh610 from target+404 (identity) and828/82C/830 from target logical root310. Null pointer leaves those cached fields untouched locally.| +|409503..40951E /9503..951E|Snapshot current608→authored87C; invoke complete124(current608), target4089B0.| +|40952D..409552 /952D..9552|Read authored Euler via interface170→4716A0 (FC/100/104/108), write logical Euler via32C→472450 (224/228/22C/230).| +|409561..409580 /9561..9580|Read authored Euler again and copy all four words into interface274/278/27C/280. This is an Euler-cache write, not sufficient evidence to name274 a queued physical impulse.| + +The state setter4089B0 is not an unconditional state-entry callback. After its +special complete970 guard for requested states0/6,4089F8 copies current6C8 to +previous6CC and assigns requested6C8;408A18 skips transition cases when equal. +Init has already assigned current from authored, and PostLoad passes that exact +current value back. Therefore this chain does not justify replaying arbitrary AI +state-entry side effects at scene load. Intervening source callbacks could change +state; those require their own ordered fixture. + +Goddard's derived41E590 then applies level policy: + +| Source | Normal LV1B/VR04/LEV1 branch | +|---|---| +|41E598|interface918=1500 (range; exact consumer semantics remain separate). VR06 substitutes3500 at41E5EE.| +|41E608..41E613|If render attachment exists, set complete70=1 and dispatch complete58(0), the existing show/unhide path.| +|41E618/41E624|interfaceD0(1) and214(1); setters4710C0→471A40 and471A00 write authored/live movement/collision flags.| +|41E632|interface2C initialization/sync dispatch42AB50, which gates4623D0 on interface49E. Body re-registration internals remain in the physics investigation.| +|41E637..41E63B|complete17C(0)→41CC30: select submode0, copy globals4F8200/204/208 into complete6D4/6D8/6DC, set WORD complete9A0=0. These are table-sourced resets; do not invent numerical values from uninitialized file storage.| +|41E641/41E64A..651|interface914=1; interface110(130)→471240 writes authored34 and264→471B40 writes live15C.| +|41E657|interface928=0.| + +Hidden branch41E661 applies to LEV6,LEV7,LV1C,LV1D,LV4A,LV6A. It calls complete58(1), +interfaceD0(0),214(0), and sets928=1. It does **not** locally assign130 radius or +submode0; carrying an old radius is not equivalent to resetting it to0. The helper +includes exact comparison immediates and a bounded branch oracle, with neighbors +tested. These later-level predicates are recovered locally, not proof of those +levels' full behavior. + +## Existing companion174: rotation, not velocity + +Jimmy423CD4 addsC0 to the existing companion pointer and passes three zeroes to +its interface174 at423CE2. 49F480+174→4716D0 writes authored EulerFC/100/104, +dispatches330→472420 to logical Euler224/228/22C, then3E0→4624F0→473540 to convert +logical Euler and dispatch render angle sync3E4. It is a rotation reset. Calling +it a velocity reset would conflate distinct coordinate fields. + +Thus the source can zero Goddard's authored orientation before his own retained +PostLoad later copies authored→logical/cache. This report establishes both local +mutations; precise registry placement must determine their temporal order. Jimmy's +separate STRT/RETURN root placement still owns companion position, as already +documented. No broad body-velocity reset is inferred from174. + +## Shadow PostLoad and resource lifetime + +4B37B8+28→4587F0 generic Init;40C→43F810 first calls4354C0 at43F814. That base: + +-4354C3..4354CA resolves authored database name interface4BC using46ACC0. +-If found,4354D6..4354F5 calls completeC8→464430 with resolved database, + authored interface4B8 resource selector and float-converted4B4. If a resulting + attached object exists at complete8C (interface−3C),435503..435513 sets its60/64 + to1 and calls its embedded interface24 slot10. +-If the first database lookup fails,435518 tries literal4F02C0 + `permanenticons.omt`; if found43553F..435542 attaches selector3 with the same + float-converted4B4. If both fail, no attachment dispatch occurs locally. + +43F819..43F844 then converts signed authored WORDs interface520/522 into complete +AC/B0 runtime size;43F84A/43F854 resets completeB4=2 andB8=0. If global509A13 is +set,43F867..43F86B calls complete58(1) to hide. This refreshes visual-resource +references and size/flags, so retained identity does not mean retaining the old +scene's texture/database handle. No local owner-pointer reset is proven; full +database teardown/reattachment internals are separate. + +## Implementation and remaining gates + +Current port reconstructs companion/animation/patrol objects on scene continuation +and explicitly restores RETURN roots. It does not model this complete retained +Goddard/shadow lifecycle. Existing patrol remains a subset: state4 follow, source +angle/render sync, shadow resource identity and per-object ordering are incomplete. + +Direct fixture contracts now supported: no route property reload for companion; +Init restores AIstate/clears waypoint; target caches refresh conditionally; +authored rotation controls PostLoad and174; normal route reapplies130/flags/ +submode0; shadow resources/sizes refresh. Unknown fields must remain unknown, +not be silently copied or zeroed. Full body registration4623D0 and exact newly +appended/retained registry callback timing gate live retained-container integration. + +Validation: `python3 -m unittest discover -s tests -p test_retained_companion.py -v` +checks EXE identity, exact instruction/vtable targets, route record absence, +rotation-setter provenance and level-branch boundaries. Helper JSON: +`python3 tools/binary/retained_companion.py ../Original`. This is immutable static +evidence plus an interpretation oracle, not original runtime execution or port +gameplay validation. diff --git a/docs/checkpoint/retained-player-body.md b/docs/checkpoint/retained-player-body.md new file mode 100644 index 0000000..006ecd1 --- /dev/null +++ b/docs/checkpoint/retained-player-body.md @@ -0,0 +1,90 @@ +# 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. + +## 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. diff --git a/docs/checkpoint/retained-return-cleanup.md b/docs/checkpoint/retained-return-cleanup.md new file mode 100644 index 0000000..1bea58b --- /dev/null +++ b/docs/checkpoint/retained-return-cleanup.md @@ -0,0 +1,122 @@ +# RETURN cleanup and complete PostLoad route tail + +Static C3/C7 continuation,2026-10-26. Read-only source is Neutron.exe SHA256 +`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`. +All preferred-base EXE VAs below map to raw file offset VA−400000 for these sites. +The helper maps PE sections independently and emits actual offsets/bytes and +virtual targets. No original code was executed; no runtime implementation changed +in this investigation. This report supersedes the earlier **prefix-only** gadget +availability interpretation in retained-character-reset.md. + +## Result: cleanup is selected-gadget policy, not a universal motion reset + +RETURN457FED adjusts Jimmy's game interface−C0 to complete, then457FF7/9 invokes +complete178. Table4A3BDC+178 resolves427FF0. After cleanup,458014 setscomplete954, +458028 sets9A5, and45815C dispatches complete168→43B5A0. Cleanup therefore runs +before RETURN flags and ordinary transition staging. + +427FF0 first updates the C2DInGameMenu at completeA18, if present. Provenance: +Jimmy42238D calls401430,4223A6 stores its result inA18,401464 installs48D414; +literal4EF05C identifies `C2DInGameMenu`. Cleanup calls its4B0(3) at42800C, then +4C4 at42801A; those resolve405FB0 (menu selection/resource visibility) and406590 +(close/free menu resources). The receiver is not the owned C3DJetpackFire. + +428020 loads signed WORD selected gadget4F0588. Unsigned bound428027..2A rejects +values outside0..7, including−1, to the common epilogue. Table428844 has: + +| Selected gadget | Case target | Relevant distinction | +|---|---|---| +|0|428037|If completeA14 exists, explicitly writes movement mode7C4=0 at42804F and restores radius/support.| +|1|4284FB|Writes mode7C4=1 at4286EA after companion/gadget cleanup.| +|2|42810C|Other gadget/companion policy.| +|3 (jetpack)|42882F|Directly the common epilogue: selected gadget4F0588=−1.| +|4|4281B3|Other gadget/companion policy.| +|5|4280CC|Conditional companion/gadget policy.| +|6|42871D|Other gadget/companion policy.| +|7|4287AC|Other gadget/companion policy.| + +The jetpack/no-selection branch does not zero movement mode7C4, jump7E8, hold874 +or owned fire6C0. This is a local caller projection, not proof that every later +load callback preserves those fields. Generic cleanup must not be modeled as +“clear all movement”; gadgets0/1 demonstrate different behavior. + +Ordinary43B5A0 does not use this selected-gadget dispatch. It stages strings, +clears7FC, conditionally copies departure root9A8 unless9A5, queues the scene +request at43B7F1, then calls complete148 at43B7FB. That target429A00 only stops +saved sound handleA44 via458A00 and writes−1. Practice Yes40470D uses this ordinary +stage. Ordinary LOAD uses it at458276. RETURN adds its preceding cleanup/flags. + +## Critical correction: read the entire Jimmy PostLoad + +The generic prefix423DEF..423E3F enables the eight group0 gadgets, then +VR01..08 prefix423E71..423EC1 disables them. **That is not the final state.** +Jimmy PostLoad continues through424557 and has level-specific overrides: + +| Destination | Tail behavior and source call VAs | +|---|---| +|LV1B|423FBB..423FCB recognizes LV1A..LV1C.424108 disables group0 item1;424113 disables item7.| +|VR01|4242BB cleanup;4242C7 enables item0.| +|VR02|424319 cleanup;424325 enables item1.| +|VR03|4242F0 cleanup;4242FC enables item2;424408 selects item2.| +|VR04|424340 cleanup;42434C enables item3;42435A selects item3.| +|VR05|424380 enables item4;424394 cleanup.| +|VR06|4243A8 cleanup;4243B4 enables item5.| +|VR07|4243CA cleanup;4243D6 enables item6.| +|VR08|4243EE cleanup;4243FA enables item7;424408 selects item7.| +|LEV1|Falls through to common42440E without those per-level overrides.| + +VR05..08 branch424365 subtracts56523035, bounds0..3, then dispatches table424558 +to42437A/42439C/4243BE/4243E0. Every enable call pushes `(disabled=false,item,group0)` +in reverse argument order and targets403870; conversion remains only4→1. Thus +every tutorial enables its corresponding practice gadget0..7 after disabling the +others. Unknown/unowned wire values remain unchanged. LV1B owned items1/7 finish4. +Source VR04 owned jetpack3 finishes1, not4; lab return leaves it1. The earlier +port tests asserting VR04 jetpack4 validated an incomplete source prefix. + +Other ordinary-level branches also exist in423EE1..42440E; their availability, +selection and automatic save policies are outside this bounded route correction. +Do not present a route-specific implementation as a full PostLoad reconstruction. + +## Remaining callback closure for retained fields + +Common PostLoad42373E cleans selected gadget5 specifically, not every gadget. +Jump state is separately cleared at42378B (interface728=complete7E8). The route +tails above run after that reset. VR04's complete174(3) resolves428D50; its table +4298E8 is indexed item+1 and maps both−1 and3 to428DE0. That branch tests global +inventory item9==2, conditionally schedules another practice level, and otherwise +returns. It does not initialize movement/hold/fire time. Its UI prelude uses the +same menu-selection405FB0 and does not own the effect timer. + +The common tail424472 grants control through game118, then42447D invokes Jimmy410 +→42AFC0. That calls43A750 (speed0/body velocity2C4(0,0,0), separately recovered by +primary), stops sound148, then complete150(`STOP`) at42AFDE..E5. Complete150 is +43AFF0: a conditional animation/action request; it dispatches completeE0→40DD90, +which updates morph selection/alias strings and animation flags through base +targets. It contains no movement-mode/hold/owned-fire write. `STOP` is literal +4ED040, distinct from `RUN`4ECA64. This final control preparation does not mean +movement mode is walking0. + +Owned fire has its own subsequent tick421FB0. It queries owner support218 at421FDF, +zeros interface600=complete6C0 only if grounded421FE9, then subtracts dt421FF3. +This is an effect tick, not a loader reset. Takeoff separately zeros the timer at +438391. Initialization can preserve a timer that the first destination tick then +changes; comparisons must observe the same phase. + +**Confidence:** high for exact cleanup/table arguments and final route availability; +high for absence of direct scalar reset in these resolved local paths. Mode/hold/ +fire preservation through a complete transition additionally requires the sibling +property-stream/Init proof and enclosing control/loader order. Retaining only +these bounded scalars after that closure is justified for no-selection/jetpack +route states; retaining arbitrary gadget modes, physics vectors or effect handles +is not justified by object identity. Body reset, selected gadget and jump state +must remain independent state dimensions. Original runtime comparison remains open. + +## Verification + +`python3 -m unittest discover -s tests -p test_retained_return_cleanup.py -v` +passes5 tests covering immutable source identity, exact instructions/vtables, +cleanup table, all eight tutorial tail argument/dispatch sites, and a deliberately +nondefault sentinel projection for selected jetpack/no-selection cleanup. The +projection checks interpretation only; it does not execute the original routine. +`python3 tools/binary/retained_return_cleanup.py ../Original` emits the evidence; +local generated copy: artifacts/retained-return-cleanup.json. No originals modified. diff --git a/docs/checkpoint/retained-streamer.md b/docs/checkpoint/retained-streamer.md new file mode 100644 index 0000000..959050b --- /dev/null +++ b/docs/checkpoint/retained-streamer.md @@ -0,0 +1,99 @@ +# Retained Jimmy: GAM property-stream boundary + +Static C3/C7 follow-up,2026-10-26. Read-only analysis of supplied Neutron.exe +SHA256`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8` +and OMT2.dll SHA256`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`. +EXE preferred base400000; DLL preferred base10000000. All listed raw offsets +map to VA−module base, checked through the PE sections by retained_streamer.py. +No original code was executed. This report closes the property-streamer's hidden +callback question; it does not by itself prove preservation through all loading. + +## Recovered call chain + +| Source VA / raw | Edge / state | +|---|---| +|46E38B/6E38B,46E3AC/6E3AC|Ordinary loader tests/looks up reusable class; otherwise46E3B9 calls factory459CB0. Both paths converge at46E3C1.| +|46E3CB/6E3CB|Load EBX from IAT48D190, whose imported decorated symbol is OMediaStreamOperators pointer extraction of OMediaClassStreamer.| +|46E3FC/6E3FC|Push current game interface and call EBX, stream receiver in ECX.| +|OMT2 10073E00/73E00|Exported extraction saves stream receiver, loads supplied object into ECX, passes stream and dispatches **receiver slot4** at10073E0A. Returns stream; no constructor, default or Init call.| +|EXE4A373C+4,4A3160+4,49F480+4|Jimmy, fire and Goddard receiver read slots all resolve473B30.| +|473B30/73B30|Generic registered-property reader. Reads count, then property name at473B94; dispatches receiver slot400 at473BA3 to lookup descriptor.| +|4A373C+400 →473EB0/73EB0|Lookup scans interface+26C list; descriptor name is at+8, returns matching descriptor pointer at473F8F, or null. No field setter/initialization callback.| +|473BBC..473BC0|Reads serialized wire type and stores it into descriptor+4, selects typed case at473BD0.| +|473BEE..473BF4|String destination is descriptor+48; imported primitive extraction writes there directly.| +|473C43..473C4A|Integer case reads temporary and copies it to descriptor+48.| +|473C5F..473C65|Float case passes descriptor+48 directly to primitive extraction.| +|473CA7..473CAD|32-bit long case passes descriptor+48 to primitive extraction.| +|473E4D..473E75|Read checksum, compare/log, return. There is no end-of-read Init28, PostLoad40C, class-default or control callback.| + +The complete840-byte473B30..473E77 reader and239-byte473EB0..473F9E lookup are +hashed by the helper, in addition to individual decisive instruction checks. +The caller of their stream primitives is the stream, not the character; the +reader's only character virtual dispatch is slot400. Missing-property branches +consume data into local temporaries and log; they do not add properties or invoke +character callbacks. Serialized type mutates descriptor metadata, so this is a +trusted-original-data reader contract, not a claim of hardened arbitrary input. + +## Registered destinations for the route's20 JIM1 fields + +Offsets below are relative to Jimmy's game interface complete+C0. These are the +pointers passed to registration3FC, not live setters inferred from key names. + +| GAM name | Interface field | Registration pointer VA / raw | +|---|---|---| +|ObjectTag|3A0 string|470403/70403| +|RotateToDest|A,4 raw bytes via type2|470427/70427| +|ObjectID|404|47043E/7043E| +|PositionX/Y/Z|EC/F0/F4 floats|470458/70458,470472/70472,47048C/7048C| +|RotationX/Y/Z|FC/100/104 floats|4704A6/704A6,4704C0/704C0,4704DA/704DA| +|TaskName|430 string|45883F/5883F| +|Debug|4A4|458859/58859| +|RequiredLevel/ExactLevel/RemoveLevel|578/57C/580|40D3CC/D3CC,40D3E6/D3E6,40D400/D400| +|HasCollision/InitiallyVisible/CanMove|584/588/58C|40D41A/D41A,40D434/D434,40D44E/D44E| +|SecondPass|590|40D468/D468| +|PickupLink|595 string|40D482/D482| +|StartPoint|664 string|43784F/3784F| + +Each row's exact LEA, pushed wire type/name literal and original name bytes are +checked. These destinations explain why property loading changes authored +position/rotation/configuration before Init re-applies them to live state. No +route descriptor points at mode interface704/complete7C4, jump728/7E8, live body +velocity1A4, acceleration274 or impulse288. No authored velocity, acceleration, +impulse, hold or fire-time property occurs in the route JIM1 records. + +The lab LV1B, VR04 and outside LEV1 JIM1 records all have this exact20-name set. +Their record offsets and original GAM hashes are emitted by the helper. Their +placement values differ and are intentionally applied on each load. Jimmy's +constructor422245 calls422AC0, whose parent registration chain is +422AD7→437830,437846→40D3C0,40D3C3→462340,462356→458820, +458836→4703B0. Reusable-object property extraction does not repeat that constructor +chain.473FA0 registration stores the passed destination pointer in descriptor+48 +at473FFE; descriptor layout and reader ownership therefore agree independently. + +## What this resolves and what it does not + +**Recovered:** Route GAM property extraction is a named, direct-write pass into +authored/configuration fields. It has no hidden character reset/init/default/end +callback. It does not zero or serialize mode, jump or body vectors on these GAMs. +The fire read slot shares the same primitive reader; the inspected JIM1 record +never reaches the fire object's timer through that reader. + +**Inference limited by enclosing callbacks:** Runtime scalars not in these records +reach Init unchanged by this extraction pass. They may still be reset by generic +Init, Jimmy PostLoad, RETURN gadget cleanup, control handoff or an intervening tick. +Absence from GAM is not proof that they survive the complete transition. Generic +Init's authored→live vector copies are covered by the primary body investigation; +constructors can initialize authored fields even when GAM has no corresponding key. +Do not carry live velocity merely because the GAM lacks a velocity property. + +**Current implementation:** The port parses GAM values and reconstructs scene +objects from snapshots. This report changes no runtime behavior. It supports a +field-specific state container, not blanket copying or rerunning constructors. + +**Verification:** Three deterministic Python groups verify both module hashes, +20 decisive instruction anchors,6 vtable targets,20 descriptors, the two full +function bodies and the three exact route property sets. Run +`python3 -m unittest discover -s tests -p test_retained_streamer.py -v` and +`python3 tools/binary/retained_streamer.py ../Original`. Static source-byte/data +checks are separate from original-component execution, port runtime and full +original route comparison; none of the latter are added here. diff --git a/docs/checkpoint/review.md b/docs/checkpoint/review.md index 94a50ce..5c7bdbd 100644 --- a/docs/checkpoint/review.md +++ b/docs/checkpoint/review.md @@ -2,7 +2,11 @@ Implementation has since continued: the old-game Init/deletion gate is resolved, controlled player phases are split, the route static camera query is integrated, -and PostLoad gadget availability is applied. See `player-phase-implementation.md`, +and PostLoad gadget availability is applied. The later retained-field chunk adds +bounded route mode/hold/fire carry, closes property-reader and companion reset +paths, and corrects full VR practice re-enable tails/LV1B restrictions. See +`retained-player-body.md` and the three linked follow-ups; older prefix-only +availability conclusions are superseded. See `player-phase-implementation.md`, `level-game-lifetime.md` and the current ledger. The exit review below preserves the evidence/verification boundary at the original checkpoint milestone. diff --git a/docs/compatibility.md b/docs/compatibility.md index 95bc2d3..2161852 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -3,6 +3,23 @@ Compilation, native runtime, original behavior and full feature completion are separate evidence categories. **The game is not fully reconstructed/playable yet.** +Retained-state continuation (2026-10-26):14 new source-evidence tests and22 +movement groups cover named property loading, cleanup/Init/PostLoad/control +boundaries and bounded route scalar carry. Corrected full tutorial/lab gadget +availability and TSK/unknown-state tests pass. An isolated Wine32 component probe +executes copied original vector accessors and43A750 with synthetic fixture vtables +and invalid sound handle; source targets are byte-guarded. It confirms body-field +writes and unrelated sentinel preservation, not full loader/gameplay or native +Windows behavior. Evidence: artifacts/retained-lifecycle/original-probe/wine.log. + +Integration:84 Python checks, all managed groups and26 GPU render checks pass +with zero enabled-validation errors. Final nondefault mode1/hold.625/fire6.125 +ordinary-load replay independently checks jump/body resets on tutorial and RETURN; +all539 original hashes unchanged. A fixed200ms effects-smoke baseline failed under +load; paused stream construction plus a bounded consumption poll corrects the test +race. All four SDL dummy audio checks pass in audio-final.log; final route is in +route-final.log. No new native Windows runtime verification. + Debug expansion (2026-10-25): full scripts/test.sh passes, with70 Python checks, 21 movement groups, debug page/overlay groups, real SDL dummy pause/mute timing, remaining managed/GPU routes and539 unchanged original hashes. Native Linux diff --git a/docs/debug-menu.md b/docs/debug-menu.md index 5dfc765..60f3b11 100644 --- a/docs/debug-menu.md +++ b/docs/debug-menu.md @@ -30,7 +30,9 @@ The General page retains the existing actions. Player adds noclip, staged flight speeds300/600/1200/2400 (Enter applies), clear motion/queued jump, reopen objective, return to noclip entry, apply source level gadget availability, toggle input after player, staged jetpack states0/1/4 with a separate Apply row, and energy refill. -State0 means unowned,1 enabled and4 disabled by the level. These controls expose +State0 means unowned,1 enabled and4 disabled by the level. The full availability +action re-enables the matching VR practice gadget and applies LV1B restrictions +on gadgets1/7 after the common prefix. Other level-specific tails remain incomplete. These controls expose the current implementation; they are not proof of complete original behavior. Systems adds the route static camera query toggle, independent music/speech/effects diff --git a/docs/decisions.md b/docs/decisions.md index 6157c2f..6e6e368 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -138,3 +138,16 @@ 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. diff --git a/docs/progress.md b/docs/progress.md index 31542bc..a2d5aff 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -1,4 +1,46 @@ -# Progress — 2026-10-25 +# Progress — 2026-10-26 + +## Retained-state implementation continuation + +Read prompt.MD in full and resumed C3/C7. Three independent investigators owned +new property-reader, RETURN-cleanup and companion files; all ownership returned. +Reports: checkpoint/retained-streamer.md, retained-return-cleanup.md, +retained-companion.md and retained-player-body.md. Exact source offsets/targets, +structures, callers, scope and unresolved fields are recorded with14 new Python +regressions. Generic Init re-applies authored body vectors; final preparation +clears speed/velocity XYZ; jump state resets independently of retained scalars. + +Implemented bounded PlayerLevelState (mode, jump-hold, owned-fire timer) for +ordinary LV1B/VR04/LEV1 transitions in the supported no-gadget/jetpack cases. +Other body/debug state reconstructs separately; TSK/debug checkpoint loads do not +carry transient fields. Modern R reset clears them. Companion AI/target/waypoint/ +rotation and shadow resource resets are documented, not blanket-persisted. + +Corrected prior prefix-only gadget availability: full VR01..08 PostLoad tails +re-enable the matching practice gadget; owned VR04 jetpack finishes1, not4. LV1B +disables gadgets1/7. Unknown wire states and other inventory regions stay intact. +Other level-specific gadget tails remain explicitly incomplete. Older VR04 state4 +claims below describe the superseded partial implementation. + +Targeted22 movement groups and inventory tests pass. Isolated original routines +pass under Wine32 in a copied, filesystem/network-isolated installation: authored +vector leaf accessors and43A750 preparation preserve unrelated sentinel bytes. +Synthetic fixture vtables resolve to guarded source targets; no whole-loader, +original-game end-to-end or native Windows verification is implied. Fresh Wine +prefix setup failed; a copied existing generated prefix works. Probe logs and +build/integration artifacts: artifacts/retained-lifecycle/. + +Validation:84 Python checks (14 new), all managed groups including22 movement, +26 GPU render checks with zero enabled Vulkan validation errors, and the final +nondefault lab→VR04→lab boundary replay pass. Final boundary logs show mode1, +hold.625/fire6.125 retained independently of jump0/velocity0/speed0 at both loads; +RETURN position/control/companion and jetpack availability1 also pass. The full +suite's original-effects smoke initially failed its fixed200ms sampling window. +It now creates both streams paused before sampling and polls consumption with a +3s bound; all four final SDL dummy audio checks pass separately. No gameplay audio +lifecycle was changed by that harness correction. Logs: integration-final.log, +route-final.log, audio-final.log, evidence-final.log and hashes-final.log. All539 +original files verified unchanged. Build succeeds with zero warnings/errors. ## Requested debug expansion diff --git a/docs/reverse-engineering.md b/docs/reverse-engineering.md index 982eb9d..4a05153 100644 --- a/docs/reverse-engineering.md +++ b/docs/reverse-engineering.md @@ -5,6 +5,11 @@ offsets, virtual addresses, API symbols or observed behavior. Decompiled output evidence, not original source. Original gameplay has not yet been observed successfully; isolated original DLL probes and modern runtime checks are recorded separately. +- `checkpoint/retained-player-body.md`, `retained-streamer.md`, + `retained-return-cleanup.md`, `retained-companion.md`: complete named property + read chain, bounded ordinary-load scalar/body resets, full tutorial availability + tails and companion/shadow lifecycle. Source-byte checks and an isolated original + body-routine probe are separate from whole-game/runtime comparison. - `save-format.md`: full supplied TSK layout, task query/assignment and activation gates. - `analysis/lab-progression.md`: CAM/MCA/AI dispatch, original lab chain and skip/camera formulas. - `analysis/scene-entities.md`: exact entity-resource preparation and contact/sprite evidence. diff --git a/docs/tasks.md b/docs/tasks.md index 929041f..bae98bf 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -69,9 +69,14 @@ plan in verified chunks. Earlier priorities below are a backlog. - [x] Static first-hit camera adapter integrated for LV1B/VR04/LEV1 with shared segment kernel and source hit weighting/gain. Full camera handoff/state open. - [x] Source PostLoad gadget availability through tutorial/normal level entry. -- [ ] Next: retained mode/fire/body reset fixture through the full property/control - callback chain, remaining scene callback/morph phases, shared viewport/DEFAULT - handoff and C4 collision. C6 source channel allocation/clock/banks remains separate. +- [x] Bounded retained mode/hold/fire route fixture through property/Init/PostLoad/ + cleanup/control; authored/live body provenance and isolated original routines. +- [x] Full tutorial gadget re-enable tails and LV1B item1/7 restrictions; replaces + previous prefix-only availability. Other level tails/selection remain open. +- [x] Companion/shadow reset trace and equal-state AI guard; no blanket AI carry. +- [ ] Next: uncontrolled body/controller/fire scheduling, body registration and + appended-helper callback timing; then C4 support/response and shared viewport/ + DEFAULT handoff. C6 source channel allocation/clock/banks remains separate. 1. Lab regressions are corrected and republished, with user verification of their own Windows build. Keep comprehensive native Windows driver/audio/input diff --git a/src/GamePort/Game/LabSimulation.cs b/src/GamePort/Game/LabSimulation.cs index a832c0f..c0458f1 100644 --- a/src/GamePort/Game/LabSimulation.cs +++ b/src/GamePort/Game/LabSimulation.cs @@ -117,6 +117,24 @@ public sealed class LabSimulation CameraEye = DesiredEye().Eye; } + public PlayerLevelState? CaptureLevelState(int selectedGadget) => Noclip ? null + : new(LevelCode, selectedGadget, movementMode, jumpState.HoldSeconds, jumpState.EffectRemaining); + + /// Apply after destination construction. Init re-applies authored + /// body vectors and clears speed/turn; PostLoad resets jump, not these scalars. + /// Grounding and the next controller/fire tick may change them independently. + public bool ApplyRetainedLevelState(PlayerLevelState state) + { + ArgumentNullException.ThrowIfNull(state); + if (!state.SupportsDestination(LevelCode)) return false; + if (state.MovementMode is < 0 or > 1 || !float.IsFinite(state.HoldSeconds) + || state.HoldSeconds < 0 || !float.IsFinite(state.EffectRemaining)) + throw new ArgumentOutOfRangeException(nameof(state)); + movementMode = state.MovementMode; + jumpState = new(0, state.HoldSeconds, state.EffectRemaining); + return true; + } + // EXE 0x47F940 truncates, then degree lookup masks to the 16384-entry table. // Table generated with modern trig; x87 bit-identical table recovery is pending. public static (float Sin, float Cos) Trig(float degrees) diff --git a/src/GamePort/Game/PlayerLevelState.cs b/src/GamePort/Game/PlayerLevelState.cs new file mode 100644 index 0000000..8a8532e --- /dev/null +++ b/src/GamePort/Game/PlayerLevelState.cs @@ -0,0 +1,15 @@ +namespace GamePort.Game; + +/// +/// Retained scalars proven through route GAM read, Init and PostLoad callbacks. +/// This is in-memory ordinary-load state, never part of the original TSK format. +/// Other gadget cleanup branches/levels need their own lifecycle proof. +/// +public sealed record PlayerLevelState(string SourceLevel, int SelectedGadget, + int MovementMode, float HoldSeconds, float EffectRemaining) +{ + public bool SupportsDestination(string level) => IsRoute(SourceLevel) && IsRoute(level) + && SelectedGadget is -1 or 3; + + private static bool IsRoute(string level) => level is "LV1B" or "VR04" or "LEV1"; +} diff --git a/src/GamePort/Game/SceneInventory.cs b/src/GamePort/Game/SceneInventory.cs index ec64316..ca07669 100644 --- a/src/GamePort/Game/SceneInventory.cs +++ b/src/GamePort/Game/SceneInventory.cs @@ -25,9 +25,10 @@ public sealed class SceneInventory public void SetState(int group, int item, int state) => states[Offset(group, item)] = state; /// - /// Jimmy PostLoad423DEF..423EC1: enable these eight owned gadgets, then - /// disable them in numeric VR01..VR08. State4 is unavailable ownership, - /// distinct from unowned0. Other wire values and item8 remain unchanged. + /// Jimmy PostLoad: enable eight owned gadgets, disable them in VR01..08, + /// then re-enable that tutorial's gadget in the later level-specific tail. + /// LV1B disables gadgets1/7. Other level-specific tails remain unported. + /// State4 is unavailable ownership, distinct from unowned0. /// public void ApplyLevelAvailability(string levelCode) { @@ -38,8 +39,19 @@ public sealed class SceneInventory // Exactly the eight original FourCC values in the source numeric range. if (levelCode.Length == 4 && levelCode.StartsWith("VR0", StringComparison.Ordinal) && levelCode[3] is >= '1' and <= '8') + { foreach (var item in items) if (states[item] == 1) states[item] = 4; + //4242AF..424400: each practice scene enables its matching gadget. + var practiceItem = levelCode[3] - '1'; + if (states[practiceItem] == 4) states[practiceItem] = 1; + } + else if (levelCode == "LV1B") + { + //424102: lab restrictions follow the common enable pass. + foreach (var item in new[] { 1, 7 }) + if (states[item] == 1) states[item] = 4; + } } public void SelectGadget(int item) diff --git a/src/GamePort/Program.cs b/src/GamePort/Program.cs index b751574..5780dff 100644 --- a/src/GamePort/Program.cs +++ b/src/GamePort/Program.cs @@ -17,13 +17,15 @@ internal static class Program { using var presentation = new RenderSession(); OriginalSave? carriedSave = null; + PlayerLevelState? carriedPlayer = null; var returning = false; var diagnostics = new DebugDiagnostics { Enabled = args.Contains("--debug-overlay") }; while (true) { - var result = Run(args, carriedSave, returning, diagnostics, presentation, out var continuation); + var result = Run(args, carriedSave, carriedPlayer, returning, diagnostics, presentation, out var continuation); if (result != 0 || continuation == null) return result; args = continuation.Args; carriedSave = continuation.Save; returning = continuation.Returning; + carriedPlayer = continuation.Player; } } catch (Exception error) { Console.Error.WriteLine(error); return 1; } @@ -38,9 +40,9 @@ internal static class Program return args[i + 1]; } - private sealed record SceneContinuation(string[] Args, OriginalSave Save, bool Returning); + private sealed record SceneContinuation(string[] Args, OriginalSave Save, bool Returning, PlayerLevelState? Player); - private static int Run(string[] args, OriginalSave? carriedSave, bool returning, DebugDiagnostics diagnostics, + private static int Run(string[] args, OriginalSave? carriedSave, PlayerLevelState? carriedPlayer, bool returning, DebugDiagnostics diagnostics, RenderSession presentation, out SceneContinuation? continuation) { continuation = null; @@ -160,17 +162,23 @@ internal static class Program if (Option(args, "--effects-audio-smoke") is { } effectsManifest) { using var mixer = new SceneAudio(new PreparedEntityResources(effectsManifest)); + // Start transport only after both streams exist, so slow stream + // creation cannot consume the entire baseline before it is sampled. + mixer.SetPaused(true); mixer.Effect(59, "bars"); mixer.Effect(58); var before = mixer.QueuedEffectBytes; - Thread.Sleep(200); - var consumed = mixer.QueuedEffectBytes < before; + mixer.SetPaused(false); + var consumptionClock = Stopwatch.StartNew(); + while (mixer.QueuedEffectBytes >= before && consumptionClock.ElapsedMilliseconds < 3000) Thread.Sleep(20); + var after = mixer.QueuedEffectBytes; + var consumed = before > 0 && after < before; mixer.Pump(); mixer.StopLoop("bars"); var stopped = mixer.LoopCount == 0 && mixer.EffectCount == 1; mixer.Effect(230); var mixed = mixer.EffectCount == 2; mixer.StopEffects(); - Console.WriteLine($"Original effects: consumed={consumed}, loop stopped={stopped}, independent one-shots={mixed}, cleared={mixer.QueuedEffectBytes == 0}."); + Console.WriteLine($"Original effects: consumed={consumed}, loop stopped={stopped}, independent one-shots={mixed}, cleared={mixer.QueuedEffectBytes == 0}; baseline={before}, after={after}."); return consumed && stopped && mixed && mixer.QueuedEffectBytes == 0 ? 0 : 2; } if (Option(args, "--scene-audio-smoke") is { } sceneAudioManifest) @@ -316,6 +324,16 @@ internal static class Program simulation = new LabSimulation(new SceneCollision(world), standingPose, originalStart.Position, originalStart.Rotation.Y, cameraRay == null ? null : (look, eye) => cameraRay.Trace(look, eye)) { LevelCode = level.Code, InputAfterPlayerUpdate = carriedSave != null }; + if (carriedPlayer != null) + { + var applied = simulation.ApplyRetainedLevelState(carriedPlayer); + if (applied) + Console.WriteLine($"Retained player scalars: mode={simulation.MovementMode}, hold={simulation.JumpHoldSeconds}, fire={simulation.JetpackRemaining}; jump={simulation.JumpState}, velocity={simulation.Velocity}, speed={simulation.Speed}."); + if (practiceReturnSmoke && (!applied || simulation.MovementMode != carriedPlayer.MovementMode + || simulation.JumpHoldSeconds != carriedPlayer.HoldSeconds || simulation.JetpackRemaining != carriedPlayer.EffectRemaining + || simulation.JumpState != 0 || simulation.Speed != 0 || simulation.Velocity != Vector3.Zero || simulation.PendingImpulse != Vector3.Zero)) + throw new InvalidOperationException("Retained route scalar/body reset boundary changed"); + } } if (walking && returning) simulation!.RestoreReturnRoot(returnRoot); var placement = PreviewCharacterPlacement.Create(mesh, standingPose, originalStart.Position, originalStart.Rotation.Y); @@ -475,8 +493,8 @@ internal static class Program if (args.Contains("--skip-intro") || jetpackSmoke || debugSmoke || diagnosticsSmoke || toolsSmoke) { sceneAudio?.StopSpeech(); director.Skip(); } if (practiceReturnSmoke && level.Code == "VR04") { - if (interactions!.Inventory.State(0, 3) != 4) - throw new InvalidOperationException("Tutorial PostLoad did not disable the owned gadget before VR04's bypass"); + if (interactions!.Inventory.State(0, 3) != 1) + throw new InvalidOperationException("VR04 PostLoad tail did not re-enable its owned practice jetpack"); director.Skip(); interactions!.Update(level.Entities.First(e => e.Kind == "LOAD").Position); if (transitionRequest is not { Returning: true }) throw new InvalidOperationException("VR04 exit did not preserve RETURN identity"); @@ -1237,8 +1255,14 @@ internal static class Program nextArgs.AddRange(["--scene", nextScene, "--level", "gam/" + transitionRequest.LevelFile, "--start", transitionRequest.StartPoint]); if (toolsSmoke) nextArgs.AddRange(["--frames", "2"]); + // Deliberate test sentinels after the last departure tick: the + // destination assertion observes loader state, before grounding + // or controller/fire callbacks can legitimately change it. + if (practiceReturnSmoke && simulation != null) + simulation.ApplyRetainedLevelState(new(level!.Code, 3, 1, .625f, 6.125f)); continuation = new(nextArgs.ToArray(), (debugCheckpointToLoad ?? interactions!.Snapshot()) with { - StartPoint = transitionRequest.StartPoint, StoredVector = debugCheckpointToLoad?.StoredVector ?? returnRoot }, transitionRequest.Returning); + StartPoint = transitionRequest.StartPoint, StoredVector = debugCheckpointToLoad?.StoredVector ?? returnRoot }, transitionRequest.Returning, + debugCheckpointToLoad == null ? simulation?.CaptureLevelState(interactions!.Inventory.SelectedGadget) : null); Console.WriteLine($"Loading original destination: {transitionRequest.LevelFile}, start={transitionRequest.StartPoint}; fade behavior remains unreconstructed."); } if (walkSmoke && !simulation!.SmokePassed) return 2; diff --git a/tests/GamePort.InteractionTests/GamePort.InteractionTests.csproj b/tests/GamePort.InteractionTests/GamePort.InteractionTests.csproj index d6b7fc4..bf53ae0 100644 --- a/tests/GamePort.InteractionTests/GamePort.InteractionTests.csproj +++ b/tests/GamePort.InteractionTests/GamePort.InteractionTests.csproj @@ -9,6 +9,7 @@ + diff --git a/tests/GamePort.InteractionTests/Program.cs b/tests/GamePort.InteractionTests/Program.cs index 6d3f43e..7f928c0 100644 --- a/tests/GamePort.InteractionTests/Program.cs +++ b/tests/GamePort.InteractionTests/Program.cs @@ -162,15 +162,17 @@ foreach (var state in new[] { int.MinValue, -1, 0, 1, 2, 3, 4, 5, int.MaxValue } var availability = new SceneInventory(Enumerable.Repeat(state, 19)); availability.ApplyLevelAvailability(tutorial); var disabled = state is 1 or 4 ? 4 : state; - Check(Enumerable.Range(0, 8).All(i => availability.State(0, i) == disabled), - "Tutorial PostLoad only disables owned states1/4"); + var practiceItem = tutorial[3] - '1'; + Check(Enumerable.Range(0, 8).All(i => availability.State(0, i) + == (i == practiceItem && state is 1 or 4 ? 1 : disabled)), + "Complete tutorial PostLoad re-enables its practice gadget after the common disable pass"); Check(availability.State(0, 8) == state && Enumerable.Range(0, 10).All(i => availability.State(1, i) == state), "PostLoad availability preserves gadget8 and the independent inventory group"); var carried = OriginalSave.Parse((original with { InventoryStates = availability.Snapshot() }).Encode()); var returned = new SceneInventory(carried.InventoryStates); returned.ApplyLevelAvailability("LV1B"); - Check(Enumerable.Range(0, 8).All(i => returned.State(0, i) == (state is 1 or 4 ? 1 : state)), - "Serialized tutorial state returns to enabled owned gadgets in lab"); + Check(Enumerable.Range(0, 8).All(i => returned.State(0, i) == (state is 1 or 4 ? i is 1 or 7 ? 4 : 1 : state)), + "Serialized tutorial state returns to lab-specific owned gadget availability"); } } foreach (var normal in new[] { "LV1B", "LEV1", "VR00", "VR09", "vr04" }) @@ -181,7 +183,7 @@ foreach (var normal in new[] { "LV1B", "LEV1", "VR00", "VR09", "vr04" }) "Normal/fourcc-boundary PostLoad enables selected owned gadgets only"); } Check(JetpackBurst.CanStart("VR04", -1, 4, 20), "Tutorial jetpack bypass still works with disabled inventory state4"); -Console.WriteLine("PASS source PostLoad gadget availability, tutorial boundaries and lab RETURN round-trip"); +Console.WriteLine("PASS complete route/tutorial PostLoad availability tails, unknown states and lab RETURN round-trip"); // Independently recover the original SCENE setter's two dispatch tables rather // than testing the port's switch against another manually copied switch. diff --git a/tests/GamePort.MovementTests/Program.cs b/tests/GamePort.MovementTests/Program.cs index 3013362..3162d70 100644 --- a/tests/GamePort.MovementTests/Program.cs +++ b/tests/GamePort.MovementTests/Program.cs @@ -9,6 +9,7 @@ var tests = new (string Name, Action Check)[] ("60 simulation calls across 60/120/144 Hz presentation", ClockRates), ("clock remainder, stall bound, reset and invalid intervals", ClockBoundaries), ("physics consumes prior motion; fresh versus retained input order", FrameOrdering), + ("ordinary route load retains scalars independently of body/jump reset", RetainedLevelState), ("source camera query origin, hit adjustment, gain and one query per input", CameraQueryConsumer), ("debug noclip bypasses walls/gravity/camera and exits without queued motion", Noclip), ("turn-only speed, forward acceleration/cap and release", SpeedLimits), @@ -102,6 +103,38 @@ static void FrameOrdering() Check(jump.MovementMode == 0, "reset restores stored walking input mode"); } +static void RetainedLevelState() +{ + var state = new PlayerLevelState("LV1B", 3, 1, .625f, 6.125f); + foreach (var destination in new[] { "VR04", "LV1B", "LEV1" }) + { + var next = FlatSimulation(); next.LevelCode = destination; next.InputAfterPlayerUpdate = true; + Check(next.ApplyRetainedLevelState(state), "Proven route accepts supported retained scalars"); + Check(next.MovementMode == 1 && next.JumpState == 0 && next.JumpHoldSeconds == .625f + && next.JetpackRemaining == 6.125f, "Jump reset does not imply mode/hold/fire reset"); + Check(next.Speed == 0 && next.TurnRate == 0 && next.Velocity == Vector3.Zero + && next.PendingImpulse == Vector3.Zero && !next.JetpackEffectVisible, "Body and effect presentation remain independently initialized"); + next.RestoreReturnRoot(next.ActorRoot + Vector3.UnitY * 500); + next.Step(default); + Check(!next.Grounded && next.MovementMode == 1 && next.JumpState == 0, + "Airborne first destination tick keeps retained input mode after jump state reset"); + Near(next.JetpackRemaining, 6.125f - FixedStepClock.Step, .00001f, "Fire timer advances in its own next-tick phase"); + var carried = next.CaptureLevelState(-1)!; + Check(carried.SourceLevel == destination && carried.HoldSeconds == .625f, "Ordinary boundary captures current scalars"); + next.Reset(); + Check(next.MovementMode == 0 && next.JumpHoldSeconds == 0 && next.JetpackRemaining == 0, "Explicit modern reset clears transient carry state"); + } + var grounded = FlatSimulation(); grounded.ApplyRetainedLevelState(state); grounded.Step(default); + Check(grounded.MovementMode == 0 && grounded.JetpackRemaining < 0, + "First grounded released controller/fire ticks clear mode and timer independently of loader"); + var unsupported = FlatSimulation(); + Check(!unsupported.ApplyRetainedLevelState(state with { SourceLevel = "LEV6" }) + && !unsupported.ApplyRetainedLevelState(state with { SelectedGadget = 0 }), "Unproven class cleanup/level states do not acquire carry policy"); + unsupported.SetNoclip(true); Check(unsupported.CaptureLevelState(-1) == null, "Modern noclip does not leak flight into retained gameplay state"); + Throws(() => grounded.ApplyRetainedLevelState(state with { HoldSeconds = float.NaN })); + Throws(() => grounded.ApplyRetainedLevelState(state with { EffectRemaining = float.PositiveInfinity })); +} + static void CameraQueryConsumer() { var enabled = false; diff --git a/tests/GamePort.PatrolTests/GamePort.PatrolTests.csproj b/tests/GamePort.PatrolTests/GamePort.PatrolTests.csproj index 9873b53..2271cbf 100644 --- a/tests/GamePort.PatrolTests/GamePort.PatrolTests.csproj +++ b/tests/GamePort.PatrolTests/GamePort.PatrolTests.csproj @@ -13,6 +13,7 @@ + diff --git a/tests/test_checkpoint_character_reset.py b/tests/test_checkpoint_character_reset.py index 6f02600..3f96345 100644 --- a/tests/test_checkpoint_character_reset.py +++ b/tests/test_checkpoint_character_reset.py @@ -27,7 +27,7 @@ class CharacterResetEvidenceTests(unittest.TestCase): tables = {s['name']: s['target'] for s in self.report['vtables']} self.assertEqual(tables['Jimmy Euler getter'], '0x4723f0') - def test_gadget_postload_disables_owned_only_and_restores_on_return(self): + def test_common_availability_prefix_without_level_specific_tails(self): original = [0, 1, 4, 2, 3, -1, 99, 1, 123] disabled = gadget_postload(original, True) self.assertEqual(disabled, [0, 4, 4, 2, 3, -1, 99, 4, 123]) diff --git a/tests/test_retained_companion.py b/tests/test_retained_companion.py new file mode 100644 index 0000000..fb5322a --- /dev/null +++ b/tests/test_retained_companion.py @@ -0,0 +1,54 @@ +"""Retained companion local reset provenance; static evidence, not runtime fidelity.""" +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools/binary')) +from retained_companion import collect, level_policy, HIDDEN_CODES + + +class RetainedCompanionTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.report = collect(ROOT.parent / 'Original') + + def test_hash_instruction_and_virtual_callback_provenance(self): + self.assertTrue(self.report['known_binary']) + for key in ('sites', 'vtables'): + for site in self.report[key]: + with self.subTest(key=key, site=site): + self.assertTrue(site['matches']) + if key == 'sites': + self.assertEqual(int(site['file_offset'], 16), int(site['va'], 16) - 0x400000) + + def test_route_has_no_companion_property_reload(self): + self.assertEqual([r['code'] for r in self.report['route']], ['LV1B', 'VR04', 'LEV1']) + for route in self.report['route']: + self.assertEqual(route['dog_records'], []) + self.assertEqual(route['shadow_records'], []) + self.assertEqual(route['policy'], dict(hidden=False, range=1500, collision_enabled=True, + radius=130, submode=0, flag928=0)) + + def test_reused_companion_callback_resets_rotation_not_velocity(self): + targets = {s['name']: s['target'] for s in self.report['vtables']} + self.assertEqual(targets['Goddard authored Euler setter'], '0x4716d0') + self.assertEqual(targets['Goddard logical Euler xyz setter'], '0x472420') + self.assertEqual(targets['Goddard rotation sync'], '0x4624f0') + sites = {s['name']: s['actual'] for s in self.report['sites']} + self.assertEqual(sites['rotation_set_authored_x'], '8986fc000000') + self.assertEqual(sites['rotation_set_logical'], 'ff9030030000') + + def test_level_policy_hidden_branches_leave_radius_submode_unassigned(self): + for code in HIDDEN_CODES: + self.assertEqual(level_policy(code), dict(hidden=True, range=1500, collision_enabled=False, + radius=None, submode=None, flag928=1)) + for code in ('LEV5', 'LEV8', 'LV1B', 'LV1E', 'LV4B', 'LV6B', 'VR04'): + self.assertFalse(level_policy(code)['hidden']) + self.assertEqual(level_policy('VR06')['range'], 3500) + with self.assertRaises(ValueError): + level_policy('VR004') + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_retained_player_body.py b/tests/test_retained_player_body.py new file mode 100644 index 0000000..2096b5c --- /dev/null +++ b/tests/test_retained_player_body.py @@ -0,0 +1,31 @@ +"""Guard body-vector owners and their initialization/physics consumers.""" +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools/binary')) +from retained_player_body import collect + + +class RetainedBodyTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.report = collect(ROOT.parent / 'Original') + + def test_authored_body_vectors_reapplied_in_init(self): + targets = {x['name']: x['target'] for x in self.report['tables']} + self.assertEqual(targets['live velocity'], '0x471f70') + self.assertEqual(targets['physics velocity'], '0x471f10') + self.assertEqual(targets['live impulse'], '0x471cc0') + self.assertEqual(targets['physics impulse'], '0x471c60') + + def test_preparation_has_its_own_velocity_reset_boundary(self): + sites = {x['name']: x['bytes'] for x in self.report['sites']} + self.assertEqual(sites['prepare_velocity_xyz'], '6a006a006a008bceff90c4020000') + self.assertEqual(sites['prepare_speed_clear'], 'c7860806000000000000') + self.assertEqual(sites['postload_prepare'], 'ff9010040000') + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_retained_return_cleanup.py b/tests/test_retained_return_cleanup.py new file mode 100644 index 0000000..be7555a --- /dev/null +++ b/tests/test_retained_return_cleanup.py @@ -0,0 +1,69 @@ +"""Guard RETURN/ordinary departure distinctions against the original EXE.""" +from dataclasses import replace +from pathlib import Path +import sys +import unittest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / 'tools/binary')) +from retained_return_cleanup import collect, JetpackCleanupProjection, project_jetpack_cleanup + + +class RetainedReturnCleanupTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.report = collect(ROOT.parent / 'Original') + + def test_original_identity_instruction_targets_and_dispatch(self): + self.assertTrue(self.report['known_binary']) + for key in ('sites', 'vtables', 'cleanup_table', 'select_table', 'tutorial_tail', 'tutorial_table'): + for site in self.report[key]: + with self.subTest(key=key, site=site): + self.assertTrue(site['matches']) + + def test_jetpack_dispatch_is_common_epilogue_not_other_gadget_mode_reset(self): + targets = [s['target'] for s in self.report['cleanup_table']] + self.assertEqual(targets[3], '0x42882f') + self.assertNotEqual(targets[3], targets[0]) + self.assertNotEqual(targets[3], targets[1]) + sites = {s['name']: s for s in self.report['sites']} + self.assertEqual(sites['cleanup_case0_mode_zero']['actual'], '66899ec4070000') + self.assertEqual(sites['cleanup_case1_mode_one']['actual'], '6689aec4070000') + + def test_cleanup_prelude_is_menu_and_return_flags_precede_stage(self): + self.assertEqual(self.report['menu_identity'], 'C2DInGameMenu') + tables = {t['name']: t['target'] for t in self.report['vtables']} + self.assertEqual(tables['Menu select'], '0x405fb0') + self.assertEqual(tables['Menu close'], '0x406590') + sites = {s['name']: int(s['va'], 16) for s in self.report['sites']} + self.assertLess(sites['return_cleanup'], sites['return_flag']) + self.assertLess(sites['return_flag'], sites['return_preserve_departure']) + self.assertLess(sites['return_preserve_departure'], sites['return_stage']) + self.assertLess(sites['stage_request'], sites['stage_sound_callback']) + + def test_postload_tail_is_part_of_the_route_contract(self): + sites = {s['name']: s for s in self.report['sites']} + # The earlier generic-enable/VR-disable prefix is not the final state. + self.assertEqual(sites['route_lab_disable1']['actual'][:12], '6a016a016a00') + self.assertEqual(sites['route_lab_disable7']['actual'][:12], '6a016a076a00') + self.assertEqual(sites['route_vr04_enable3']['actual'][:12], '6a006a036a00') + self.assertEqual([t['target'] for t in self.report['select_table']], ['0x428de0']*2) + self.assertEqual(self.report['final_action'], 'STOP') + self.assertEqual([x['item'] for x in self.report['tutorial_tail']], list(range(8))) + self.assertTrue(all(not x['disabled'] and x['target'] == '0x403870' for x in self.report['tutorial_tail'])) + + def test_bounded_jetpack_projection_does_not_invent_blanket_reset(self): + # Deliberately nondefault sentinels expose accidental conflation of + # selected gadget, movement mode, jump state, hold and owned effect timer. + state = JetpackCleanupProjection(3, 1, 3, .625, 6.5) + self.assertEqual(project_jetpack_cleanup(state), replace(state, selected=-1)) + self.assertEqual(state.selected, 3) + no_selection = replace(state, selected=-1) + self.assertEqual(project_jetpack_cleanup(no_selection), no_selection) + for other in (0, 1, 2, 4, 5, 6, 7, 99): + with self.assertRaises(ValueError): + project_jetpack_cleanup(replace(state, selected=other)) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_retained_streamer.py b/tests/test_retained_streamer.py new file mode 100644 index 0000000..e34ff0b --- /dev/null +++ b/tests/test_retained_streamer.py @@ -0,0 +1,52 @@ +"""Immutable original streamer/descriptor evidence; no original code execution.""" +import importlib.util +from pathlib import Path +import unittest + +ROOT = Path(__file__).resolve().parents[1] +spec = importlib.util.spec_from_file_location('retained_streamer', ROOT / 'tools/binary/retained_streamer.py') +streamer = importlib.util.module_from_spec(spec) +spec.loader.exec_module(streamer) + + +class RetainedStreamerTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.evidence = streamer.collect(ROOT.parent / 'Original') + + def test_import_export_and_receiver_dispatch(self): + r = self.evidence + self.assertTrue(r['known_binary']) + self.assertTrue(r['import_export_matches']) + self.assertEqual(r['extraction_export']['va'], '0x10073e00') + self.assertTrue(all(s['matches'] for s in r['sites']), r['sites']) + self.assertEqual(len(r['sites']), 20) + self.assertEqual(len(r['vtables']), 6) + self.assertTrue(all(t['matches'] for t in r['vtables'])) + self.assertEqual({t['target'] for t in r['vtables'] if t['slot'] == '0x4'}, {'0x473b30'}) + + def test_entire_reader_lookup_bodies_and_direct_field_destinations(self): + r = self.evidence + self.assertEqual(len(r['functions']), 2) + self.assertTrue(all(f['matches'] for f in r['functions'])) + self.assertEqual(len(r['descriptors']), 20) + self.assertTrue(all(d['matches'] for d in r['descriptors']), r['descriptors']) + fields = {d['name']: int(d['interface_offset'], 16) for d in r['descriptors']} + self.assertEqual([fields[n] for n in ('PositionX', 'PositionY', 'PositionZ')], [0xEC, 0xF0, 0xF4]) + self.assertEqual([fields[n] for n in ('RotationX', 'RotationY', 'RotationZ')], [0xFC, 0x100, 0x104]) + self.assertEqual(fields['StartPoint'], 0x664) + self.assertTrue(set(fields.values()).isdisjoint({0x704, 0x728, 0x1A4, 0x274, 0x288}), + 'Mode/jump/live body vectors are not these GAM descriptor destinations') + + def test_route_properties_are_exact_registered_subset_without_runtime_fields(self): + r = self.evidence + self.assertEqual([s['code'] for s in r['route']], ['LV1B', 'VR04', 'LEV1']) + self.assertTrue(all(s['exact_descriptor_set'] for s in r['route'])) + names = sorted(d['name'] for d in r['descriptors']) + for scene in r['route']: + self.assertEqual(scene['player_properties'], names) + self.assertEqual(len(scene['player_properties']), 20) + + +if __name__ == '__main__': + unittest.main() diff --git a/tools/binary/checkpoint_character_reset.py b/tools/binary/checkpoint_character_reset.py index f9c5f2b..b855279 100644 --- a/tools/binary/checkpoint_character_reset.py +++ b/tools/binary/checkpoint_character_reset.py @@ -71,7 +71,11 @@ DISABLE_CALLS = (0x423E71, 0x423E7C, 0x423E87, 0x423E92, def gadget_postload(states, tutorial): - """Bounded state oracle: source403870 preserves values other than1/4.""" + """Common PostLoad prefix only:403870 preserves values other than1/4. + + Later level tails override this result; see retained_return_cleanup.py. + This function does not model final scene availability. + """ values = list(states) if len(values) < 8: raise ValueError('Need all eight group0 gadget entries') diff --git a/tools/binary/retained_body_probe.c b/tools/binary/retained_body_probe.c new file mode 100644 index 0000000..0223ba3 --- /dev/null +++ b/tools/binary/retained_body_probe.c @@ -0,0 +1,81 @@ +/* Isolated original-component probe. Compile at a non-game image base and run + * with reference_capture.py --asset-probe against a COPIED Neutron.exe only. + * Maps PE sections without running entry points/imports. Executes only proven + * leaf vector accessors and 43A750 with an already-invalid sound handle. + * Synthetic vtables use the guarded source targets rebased to the mapped copy; + * these selected paths use relative calls/fields, never absolute source globals. + * Does not execute the full loader, controller, physics or original game. */ +#include +#include +#include +#include +#include +#define TC __attribute__((thiscall)) +typedef struct { float x,y,z,w; } Vec4; +typedef void *(TC *GetVector)(void *, void *); +typedef void (TC *SetVector)(void *, Vec4); +typedef void (TC *Prepare)(void *); +static unsigned char *mapped; +static void *at(unsigned va) { return mapped+va-0x400000; } +static void require(int ok, const char *message) { + if (!ok) { fprintf(stderr,"FAIL %s\n",message); exit(2); } +} +static void map_copy(void) { + FILE *f=fopen("Neutron.exe","rb"); require(f!=NULL,"copied EXE available"); + fseek(f,0,SEEK_END); long size=ftell(f); rewind(f); + require(size>0 && size<16000000,"bounded EXE size"); + unsigned char *data=malloc(size); require(data!=NULL,"file allocation"); + require(fread(data,1,size,f)==(size_t)size,"read copied EXE"); fclose(f); + require(size>64 && *(uint16_t*)data==IMAGE_DOS_SIGNATURE,"DOS header"); + uint32_t nt_offset=*(uint32_t*)(data+0x3c); + require(nt_offset<(uint32_t)size-sizeof(IMAGE_NT_HEADERS32),"NT header bounds"); + IMAGE_NT_HEADERS32 *nt=(void*)(data+nt_offset); + require(nt->Signature==IMAGE_NT_SIGNATURE && nt->FileHeader.Machine==IMAGE_FILE_MACHINE_I386 + && nt->OptionalHeader.ImageBase==0x400000 && nt->OptionalHeader.SizeOfImage<16000000,"expected PE32 layout"); + unsigned char *image=VirtualAlloc(NULL,nt->OptionalHeader.SizeOfImage, + MEM_COMMIT|MEM_RESERVE,PAGE_EXECUTE_READWRITE); + require(image!=NULL,"component code map"); mapped=image; + IMAGE_SECTION_HEADER *sections=IMAGE_FIRST_SECTION(nt); + require((unsigned char*)(sections+nt->FileHeader.NumberOfSections)<=data+size,"section table bounds"); + for (unsigned i=0;iFileHeader.NumberOfSections;i++) { + IMAGE_SECTION_HEADER *s=§ions[i]; + require((uint64_t)s->PointerToRawData+s->SizeOfRawData<=(uint64_t)size + && (uint64_t)s->VirtualAddress+s->SizeOfRawData<=nt->OptionalHeader.SizeOfImage,"section bounds"); + memcpy(image+s->VirtualAddress,data+s->PointerToRawData,s->SizeOfRawData); + } + free(data); +} +int main(void) { + setbuf(stdout,NULL); map_copy(); + unsigned char complete[0x2100]={0}; unsigned char *object=complete+0xc0; + uintptr_t complete_table[0x500/4]={0}, interface_table[0x500/4]={0}; + complete_table[0x148/4]=(uintptr_t)at(0x429a00); + interface_table[0x2c4/4]=(uintptr_t)at(0x471f40); + *(uintptr_t*)complete=(uintptr_t)complete_table; *(uintptr_t*)object=(uintptr_t)interface_table; + const unsigned getters[]={0x471290,0x4712e0,0x4713d0}; + const unsigned setters[]={0x471bd0,0x471cc0,0x471f70}; + const unsigned authored[]={0x3c,0x4c,0x7c}, live[]={0x164,0x174,0x1a4}; + for (unsigned i=0;i<3;i++) { + Vec4 expected={11+i,22+i,33+i,44+i}, result; + memcpy(object+authored[i],&expected,sizeof(expected)); + memset(object+live[i],0xa5,sizeof(expected)); + ((GetVector)at(getters[i]))(object,&result); + ((SetVector)at(setters[i]))(object,result); + require(memcmp(object+live[i],&expected,sizeof(expected))==0,"authored vector reapplied"); + } + puts("PASS original leaf accessors reapply authored acceleration/impulse/velocity including fourth component"); + *(int32_t*)(complete+0xa44)=-1; // Avoid external sound-stop branch. + *(float*)(object+0x608)=345; + *(int16_t*)(object+0x704)=1; *(int16_t*)(object+0x728)=3; + *(float*)(object+0x7b4)=.625f; + unsigned char before[sizeof(complete)]; memcpy(before,complete,sizeof(complete)); + ((Prepare)at(0x43a750))(object); + require(*(float*)(object+0x608)==0,"preparation speed cleared"); + Vec4 *velocity=(void*)(object+0x1a4); + require(velocity->x==0 && velocity->y==0 && velocity->z==0 && velocity->w==46,"only velocity XYZ cleared"); + memset(before+0xc0+0x608,0,4); memset(before+0xc0+0x1a4,0,12); + require(memcmp(before,complete,sizeof(complete))==0,"all other sentinel fields preserved"); + puts("PASS original 43A750 clears speed/velocity XYZ; preserves impulse, acceleration, mode, jump and hold sentinels"); + puts("LIMIT isolated original routines with invalid sound handle; no whole-loader/game runtime verification"); + return 0; +} diff --git a/tools/binary/retained_companion.py b/tools/binary/retained_companion.py new file mode 100644 index 0000000..06f1282 --- /dev/null +++ b/tools/binary/retained_companion.py @@ -0,0 +1,157 @@ +#!/usr/bin/env python3 +"""Read-only Goddard/shadow retained-load callback evidence; no source execution.""" +from __future__ import annotations + +import argparse +import hashlib +import json +from pathlib import Path +import struct +import sys + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +from checkpoint_script_state import EXE_SHA256, find_case, read_va +from pe_inspect import PE +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'levels')) +import gam + +SITES = ( + ('goddard_complete_table', 0x41c866, 'c70620f94900'), + ('goddard_interface_table', 0x41c883, 'c70780f44900'), + ('goddard_retention', 0x41c99b, '538bcfe89d450500'), + ('goddard_reuse', 0x41c9c0, 'c686c900000001'), + ('goddard_init_bridge', 0x41e6a0, 'e90b98feff'), + ('actor_init_base', 0x407eb3, 'e838090500'), + ('actor_init_active', 0x407eb8, 'c6460a01'), + ('actor_init_state', 0x407ebc, '8b867c080000898608060000'), + ('actor_init_waypoint', 0x407ec8, 'c7860008000000000000'), + ('goddard_postload_base', 0x41e593, 'e8e8aefeff'), + ('actor_postload_base', 0x409486, 'e825530000'), + ('target_tag_lookup', 0x40948b, '8d86ac06000050e8d9ab0600'), + ('target_pointer_store', 0x40949a, '898600060000'), + ('target_id_store', 0x4094ae, '898e10060000'), + ('target_root_x', 0x4094c9, '898e28080000'), + ('target_root_y', 0x4094e5, '898e2c080000'), + ('target_root_z', 0x4094fd, '898e30080000'), + ('state_snapshot', 0x409503, '8b96080600008d8e40ffffff89967c080000'), + ('state_virtual_dispatch', 0x409515, '8b96080600008b0152ff9024010000'), + ('state_previous_store', 0x4089f8, '898ecc0600008986c8060000'), + ('state_same_gate', 0x408a18, '3bc10f846e010000'), + ('authored_rotation_get', 0x40952d, 'ff9070010000'), + ('logical_rotation_set', 0x409552, 'ff922c030000'), + ('rotation_cache_start', 0x409569, '81c6740200008916'), + ('rotation_cache_end', 0x409580, '89460c5e83c410c3'), + ('normal_range', 0x41e598, 'c786180900000080bb44'), + ('hide_lv4a', 0x41e5ad, '3d4134564c'), + ('hide_lv1d', 0x41e5ba, '3d4431564c'), + ('hide_lv1c', 0x41e5c1, '3d4331564c'), + ('hide_lev6', 0x41e5cc, '3d3656454c'), + ('hide_lev7', 0x41e5d3, '3d3756454c'), + ('hide_lv6a', 0x41e5e0, '3d4136564c'), + ('special_vr06', 0x41e5e7, '3d36305256'), + ('tutorial6_range', 0x41e5ee, 'c7861809000000c05a45'), + ('normal_enable', 0x41e618, '6a018bceff90d0000000'), + ('normal_collision_enable', 0x41e624, '6a018bceff9214020000'), + ('normal_submode_zero', 0x41e637, '6a008bcfff927c010000'), + ('normal_radius130', 0x41e64a, '68000002438bceff9010010000'), + ('normal_flag928', 0x41e657, 'c6862809000000'), + ('hidden_disable', 0x41e674, '6a008bceff90d0000000'), + ('hidden_collision_disable', 0x41e680, '6a008bceff9214020000'), + ('hidden_flag928', 0x41e68a, 'c6862809000001'), + ('companion_pointer_branch', 0x423c6a, '8b855c09000085c07560'), + ('companion_ctor', 0x423c98, 'e8738bffff'), + ('companion_reused_zero_rotation', 0x423cd4, '8d88c00000006a006a006a008b01ff9074010000'), + ('rotation_set_authored_y', 0x4716df, '898e00010000'), + ('rotation_set_authored_z', 0x4716e7, '899604010000'), + ('rotation_set_authored_x', 0x4716f6, '8986fc000000'), + ('rotation_set_logical', 0x471702, 'ff9030030000'), + ('rotation_render_sync', 0x47170c, 'ff92e0030000'), + ('logical_euler_set_x', 0x472428, '898124020000'), + ('render_sync_bridge', 0x4624f0, 'e94b100100'), + ('submode_zero_vector_x', 0x41cc73, 'a100824f008981d4060000'), + ('submode_zero_vector_y', 0x41cc7e, 'a104824f008981d8060000'), + ('submode_zero_vector_z', 0x41cc89, 'a108824f008981dc060000'), + ('submode_zero_state', 0x41cc94, '668991a0090000'), + ('shadow_complete_table', 0x43f6a0, 'c7031c3c4b00'), + ('shadow_interface_table', 0x43f6ad, 'c74500b8374b00'), + ('shadow_postload_base', 0x43f814, 'e8a75cffff'), + ('shadow_authored_size', 0x43f819, '0fbf86220500000fbf9620050000'), + ('shadow_runtime_size', 0x43f83e, 'd999ac000000d999b0000000'), + ('shadow_render_flags', 0x43f84a, 'c781b400000002000000c781b800000000000000'), + ('shadow_authored_db', 0x4354c3, '8d86bc04000050e8f1570300'), + ('shadow_resource_attach', 0x4354f5, 'ff92c8000000'), + ('shadow_resource_flags', 0x435503, 'b8010000008d4e24894660894664'), + ('shadow_fallback_db', 0x435518, '68c0024f00e89e570300'), + ('shadow_fallback_attach', 0x43553f, '6a0350ff92c8000000'), +) + +VTABLES = ( + ('Goddard Init', 0x49f480, 0x28, 0x41e6a0), + ('Goddard PostLoad', 0x49f480, 0x40c, 0x41e590), + ('Goddard authored Euler getter', 0x49f480, 0x170, 0x4716a0), + ('Goddard authored Euler setter', 0x49f480, 0x174, 0x4716d0), + ('Goddard logical Euler vector setter', 0x49f480, 0x32c, 0x472450), + ('Goddard logical Euler xyz setter', 0x49f480, 0x330, 0x472420), + ('Goddard rotation sync', 0x49f480, 0x3e0, 0x4624f0), + ('Goddard state dispatch', 0x49f920, 0x124, 0x4089b0), + ('Goddard submode dispatch', 0x49f920, 0x17c, 0x41cc30), + ('Goddard radius setter', 0x49f480, 0x110, 0x471240), + ('Goddard live radius setter', 0x49f480, 0x264, 0x471b40), + ('Goddard collision flag', 0x49f480, 0x214, 0x471a00), + ('Shadow Init', 0x4b37b8, 0x28, 0x4587f0), + ('Shadow PostLoad', 0x4b37b8, 0x40c, 0x43f810), + ('Shadow resource attach', 0x4b3c1c, 0xc8, 0x464430), +) + +HIDDEN_CODES = frozenset(('LEV6', 'LEV7', 'LV1C', 'LV1D', 'LV4A', 'LV6A')) + + +def level_policy(code: str): + """Bounded interpretation of41E5A2..41E692, not execution of original code. + + Hidden path does not assign a new radius/submode; None explicitly means + untouched by this local branch, not zero or a preservation proof elsewhere. + """ + if len(code) != 4 or not code.isascii(): + raise ValueError('Original level codes have four ASCII characters') + hidden = code in HIDDEN_CODES + return dict(hidden=hidden, range=3500 if code == 'VR06' else 1500, + collision_enabled=not hidden, radius=None if hidden else 130, + submode=None if hidden else 0, flag928=int(hidden)) + + +def collect(root: Path): + pe = PE(find_case(root, 'Neutron.exe')) + digest = hashlib.sha256(pe.data).hexdigest() + sites = [] + for name, va, expected in SITES: + actual = read_va(pe, va, len(bytes.fromhex(expected))).hex() + sites.append(dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)), + expected=expected, actual=actual, matches=actual == expected)) + tables = [] + for name, table, slot, expected in VTABLES: + actual = struct.unpack('