Recover retained route state and complete PostLoad availability tails

This commit is contained in:
UnixNight committed 2026-10-26 03:58:52 -04:00
1 parent 1dddfefc68
commit 9ad5a8ef6b
36 files changed
+1559 -32

No files matched your search

+12
View File
@@ -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.
+5
View File
@@ -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:
+4 -3
View File
@@ -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
+19
View File
@@ -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.
+12 -1
View File
@@ -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
+127
View File
@@ -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.
+90
View File
@@ -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.
+122
View File
@@ -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.
+99
View File
@@ -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.
+5 -1
View File
@@ -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.
+17
View File
@@ -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
+3 -1
View File
@@ -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
+13
View File
@@ -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.
+43 -1
View File
@@ -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
+5
View File
@@ -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.
+8 -3
View File
@@ -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
+18
View File
@@ -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);
/// <summary>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.</summary>
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)
+15
View File
@@ -0,0 +1,15 @@
namespace GamePort.Game;
/// <summary>
/// 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.
/// </summary>
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";
}
+15 -3
View File
@@ -25,9 +25,10 @@ public sealed class SceneInventory
public void SetState(int group, int item, int state) => states[Offset(group, item)] = state;
/// <summary>
/// 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.
/// </summary>
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)
+33 -9
View File
@@ -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;
@@ -9,6 +9,7 @@
<Compile Include="../../src/GamePort/Game/TaskActivation.cs"/>
<Compile Include="../../src/GamePort/Game/TaskStates.cs"/>
<Compile Include="../../src/GamePort/Game/LabSimulation.cs"/>
<Compile Include="../../src/GamePort/Game/PlayerLevelState.cs"/>
<Compile Include="../../src/GamePort/Game/AirSteering.cs"/>
<Compile Include="../../src/GamePort/Game/JetpackBurst.cs"/>
<Compile Include="../../src/GamePort/Game/SceneCollision.cs"/>
+7 -5
View File
@@ -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.
+33
View File
@@ -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<ArgumentOutOfRangeException>(() => grounded.ApplyRetainedLevelState(state with { HoldSeconds = float.NaN }));
Throws<ArgumentOutOfRangeException>(() => grounded.ApplyRetainedLevelState(state with { EffectRemaining = float.PositiveInfinity }));
}
static void CameraQueryConsumer()
{
var enabled = false;
@@ -13,6 +13,7 @@
<Compile Include="../../src/GamePort/Game/TaskStates.cs"/>
<Compile Include="../../src/GamePort/Game/TaskActivation.cs"/>
<Compile Include="../../src/GamePort/Game/LabSimulation.cs"/>
<Compile Include="../../src/GamePort/Game/PlayerLevelState.cs"/>
<Compile Include="../../src/GamePort/Game/AirSteering.cs"/>
<Compile Include="../../src/GamePort/Game/JetpackBurst.cs"/>
<Compile Include="../../src/GamePort/Game/SceneCollision.cs"/>
+1 -1
View File
@@ -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])
+54
View File
@@ -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()
+31
View File
@@ -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()
+69
View File
@@ -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()
+52
View File
@@ -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()
+5 -1
View File
@@ -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')
+81
View File
@@ -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 <windows.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#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;i<nt->FileHeader.NumberOfSections;i++) {
IMAGE_SECTION_HEADER *s=&sections[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;
}
+157
View File
@@ -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('<I', read_va(pe, table + slot, 4))[0]
tables.append(dict(name=name, table=hex(table), slot=hex(slot),
file_offset=hex(pe.offset(table+slot-pe.base)),
target=hex(actual), matches=actual == expected))
route = []
for name in ('level1b.gam', 'VR04.gam', 'level1.gam'):
path = find_case(root, 'gam/' + name)
raw = path.read_bytes()
level = gam.parse(raw)
route.append(dict(file=name, code=level.code, sha256=hashlib.sha256(raw).hexdigest(),
dog_records=[hex(e.offset) for e in level.entities if e.kind == '3DOG'],
shadow_records=[hex(e.offset) for e in level.entities if e.kind == '3SHA'],
policy=level_policy(level.code)))
return dict(known_binary=digest == EXE_SHA256, sha256=digest,
sites=sites, vtables=tables, route=route,
scope='Static source bytes/data and bounded interpretation only; no original execution.')
if __name__ == '__main__':
cli = argparse.ArgumentParser(description=__doc__)
cli.add_argument('original', type=Path)
result = collect(cli.parse_args().original)
print(json.dumps(result, indent=2))
if not result['known_binary'] or not all(x['matches'] for k in ('sites', 'vtables') for x in result[k]):
raise SystemExit(1)
+84
View File
@@ -0,0 +1,84 @@
#!/usr/bin/env python3
"""Read-only authored/live body reset and cutscene-preparation provenance."""
import argparse
import hashlib
import json
from pathlib import Path
import struct
from checkpoint_script_state import EXE_SHA256, find_case, read_va
from pe_inspect import PE
SITES = (
('init_acceleration_get', 0x4706EA, 'ff921c010000'),
('init_acceleration_set', 0x47070F, 'ff9274020000'),
('init_impulse_get', 0x47071E, 'ff9024010000'),
('init_impulse_set', 0x470743, 'ff9288020000'),
('init_velocity_get', 0x4707BA, 'ff903c010000'),
('init_velocity_set', 0x4707DF, 'ff92c0020000'),
('authored_acceleration', 0x471294, '8b513c'),
('authored_impulse', 0x4712E4, '8b514c'),
('authored_velocity', 0x4713D4, '8b517c'),
('live_acceleration', 0x471BD8, '81c164010000'),
('live_impulse', 0x471CC8, '81c174010000'),
('live_velocity', 0x471F78, '81c1a4010000'),
('physics_impulse_get', 0x479EBB, 'ff9284020000'),
('physics_impulse_apply', 0x479EE5, 'ff97cc020000'),
('physics_impulse_clear', 0x479EF2, 'ff928c020000'),
('physics_acceleration_get', 0x479F01, 'ff9070020000'),
('physics_acceleration_apply', 0x479F4A, 'ff92cc020000'),
('physics_velocity_get', 0x479F8D, 'ff92bc020000'),
('postload_prepare', 0x42447D, 'ff9010040000'),
('jimmy_prepare_base', 0x42AFC3, 'e888f70000'),
('prepare_speed_clear', 0x43A758, 'c7860806000000000000'),
('prepare_velocity_xyz', 0x43A764, '6a006a006a008bceff90c4020000'),
('prepare_stop_sound', 0x43A77E, 'ff9248010000'),
('invalid_sound_handle_guard', 0x429A09, '83f8ff7415'),
('body_velocity_xyz_write', 0x471F48, '8981a4010000'),
('game_control_store', 0x475A44, 'a3e4995000'),
)
TABLES = (
('authored acceleration', 0x4A373C, 0x11C, 0x471290),
('live acceleration', 0x4A373C, 0x274, 0x471BD0),
('authored impulse', 0x4A373C, 0x124, 0x4712E0),
('live impulse', 0x4A373C, 0x288, 0x471CC0),
('authored velocity', 0x4A373C, 0x13C, 0x4713D0),
('live velocity', 0x4A373C, 0x2C0, 0x471F70),
('physics impulse', 0x4A373C, 0x284, 0x471C60),
('physics impulse clear', 0x4A373C, 0x28C, 0x471C90),
('physics velocity', 0x4A373C, 0x2BC, 0x471F10),
('velocity XYZ setter', 0x4A373C, 0x2C4, 0x471F40),
('velocity adder', 0x4A373C, 0x2CC, 0x471FA0),
('Jimmy preparation', 0x4A373C, 0x410, 0x42AFC0),
('Jimmy stop sound', 0x4A3BDC, 0x148, 0x429A00),
('lab control assignment', 0x4C3CD0, 0x118, 0x475A40),
('tutorial control assignment', 0x4CE910, 0x118, 0x475A40),
('outside control assignment', 0x4C5A80, 0x118, 0x475A40),
)
def collect(root):
pe = PE(find_case(Path(root), 'Neutron.exe'))
if hashlib.sha256(pe.data).hexdigest() != EXE_SHA256:
raise ValueError('Unsupported original EXE')
sites = []
for name, va, expected in SITES:
actual = read_va(pe, va, len(bytes.fromhex(expected))).hex()
if actual != expected:
raise ValueError(f'{name} changed at {va:#x}: {actual}')
sites.append(dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)), bytes=actual))
tables = []
for name, table, slot, target in TABLES:
actual = struct.unpack('<I', read_va(pe, table+slot, 4))[0]
if actual != target:
raise ValueError(f'{name} callback changed')
tables.append(dict(name=name, table=hex(table), slot=hex(slot), target=hex(target),
file_offset=hex(pe.offset(table+slot-pe.base))))
return dict(sha256=EXE_SHA256, sites=sites, tables=tables,
scope='Static body-vector provenance; original component execution is a separate C probe.')
if __name__ == '__main__':
cli = argparse.ArgumentParser(description=__doc__)
cli.add_argument('original', type=Path)
print(json.dumps(collect(cli.parse_args().original), indent=2))
+173
View File
@@ -0,0 +1,173 @@
#!/usr/bin/env python3
"""Read-only evidence for RETURN's selected-gadget cleanup, not a load oracle."""
from __future__ import annotations
import argparse
from dataclasses import dataclass, replace
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, rel_call_target
from pe_inspect import PE
SITES = (
('return_complete_receiver', 0x457FED, '8d8b40ffffff'),
('return_cleanup', 0x457FF7, '8b11ff9278010000'),
('return_flag', 0x458014, '889054090000'),
('return_preserve_departure', 0x458028, '8890a5090000'),
('return_stage', 0x45815C, 'ff9268010000'),
('practice_yes_stage', 0x40470D, 'ff9268010000'),
('stage_clear_7fc', 0x43B5EE, 'c683fc07000000'),
('stage_departure_guard', 0x43B78E, '8a83a509000084c07537'),
('stage_request', 0x43B7F1, 'ff9200010000'),
('stage_sound_callback', 0x43B7FB, 'ff9248010000'),
('stage_sound_stop', 0x429A11, 'e8eaef0200'),
('stage_sound_handle_reset', 0x429A19, 'c786440a0000ffffffff'),
('menu_constructor_call', 0x42238D, 'e89ef0fdff'),
('menu_pointer_store', 0x4223A6, '8985180a0000'),
('menu_vtable_install', 0x401464, 'c70614d44800'),
('cleanup_zero_register', 0x427FFB, '33db'),
('cleanup_menu_pointer', 0x427FFE, '8b8e180a00003bcb7418'),
('cleanup_menu_select', 0x42800A, '6a03ff90b0040000'),
('cleanup_menu_close', 0x42801A, 'ff92c4040000'),
('cleanup_selected_signed', 0x428020, '0fbf0588054f00'),
('cleanup_range_guard', 0x428027, '83f8070f87ff070000'),
('cleanup_dispatch', 0x428030, 'ff248544884200'),
('cleanup_case0_mode_zero', 0x42804F, '66899ec4070000'),
('cleanup_case1_mode_one', 0x4286EA, '6689aec4070000'),
('cleanup_common_selection_reset', 0x42882F, '5f5e5d66c70588054f00ffff5b81c494000000c3'),
('postload_cleanup_only_selected5', 0x42373E, '66833d88054f0005750a8b068bceff9078010000'),
('postload_jump_zero', 0x42378B, '6689bd28070000'),
('control_cleanup', 0x42AE08, '8b8640ffffff8d8e40ffffffff9078010000'),
('fire_owner_support_query', 0x421FDD, '8b11ff9218020000'),
('fire_grounded_clear', 0x421FE7, '740ac7860006000000000000'),
('fire_tick', 0x421FF3, 'd98600060000d8642418'),
('takeoff_timer_clear', 0x438387, '8b86f80700003bc5740689a8c0060000'),
('route_lab_range_low', 0x423FBB, '3d4031564c0f8e48040000'),
('route_lab_range_high', 0x423FC6, '3d4331564c0f8e31010000'),
('route_lab_disable1', 0x424102, '6a016a016a00e863f7fdff'),
('route_lab_disable7', 0x42410D, '6a016a076a00e858f7fdff'),
('route_vr04_select', 0x42418E, '3d343052560f8fcc0100000f8493010000'),
('route_vr01_select', 0x42419F, '3d313052560f8f2a0100000f84ff000000'),
('route_vr02_vr03_select', 0x4242D4, '2d323052567432480f852c010000'),
('route_vr05_vr08_index', 0x424365, '05cbcfada983f8030f879b000000ff248558454200'),
('route_vr04_cleanup', 0x424340, 'ff9278010000'),
('route_vr04_enable3', 0x424346, '6a006a036a00e81ff5fdff'),
('route_vr04_select3', 0x424358, '6a03ff9074010000'),
('route_final_control', 0x424472, 'ff9218010000'),
('route_final_player410', 0x42447D, 'ff9010040000'),
('select_gadget_index', 0x428DCD, '8d460183f8090f87f40a0000ff2485e8984200'),
('select_jetpack_auxitem9', 0x428DE0, '6a0953e868abfdff83c408663d02000f85d80a0000'),
('select_jetpack_auxload', 0x428E46, 'ff9068010000e97c0a0000'),
('final_stop_player_prepare', 0x42AFC3, 'e888f70000'),
('final_stop_action', 0x42AFDE, '6840d04e008bceff9250010000'),
('stop_animation_dispatch', 0x43B58A, '8b166a01578bceff92e0000000'),
)
VTABLES = (
('Jimmy cleanup', 0x4A3BDC, 0x178, 0x427FF0),
('Jimmy stage', 0x4A3BDC, 0x168, 0x43B5A0),
('Jimmy stage sound', 0x4A3BDC, 0x148, 0x429A00),
('Jimmy control cleanup', 0x4A373C, 0x438, 0x42AE00),
('Menu select', 0x48D414, 0x4B0, 0x405FB0),
('Menu close', 0x48D414, 0x4C4, 0x406590),
('Jimmy gadget select', 0x4A3BDC, 0x174, 0x428D50),
('Jimmy final410', 0x4A373C, 0x410, 0x42AFC0),
('Jimmy action150', 0x4A3BDC, 0x150, 0x43AFF0),
('Jimmy animation E0', 0x4A3BDC, 0xE0, 0x40DD90),
('Jimmy current animation', 0x4A3BDC, 0x100, 0x40DF80),
)
CLEANUP_TARGETS = (0x428037, 0x4284FB, 0x42810C, 0x42882F,
0x4281B3, 0x4280CC, 0x42871D, 0x4287AC)
TUTORIAL_ENABLE_CALLS = (0x4242C7, 0x424325, 0x4242FC, 0x42434C,
0x424380, 0x4243B4, 0x4243D6, 0x4243FA)
TUTORIAL_CLEANUP_CALLS = (0x4242BB, 0x424319, 0x4242F0, 0x424340,
0x424394, 0x4243A8, 0x4243CA, 0x4243EE)
@dataclass(frozen=True)
class JetpackCleanupProjection:
"""Only the caller-visible selected-jetpack branch, before other load phases.
This excludes the UI resource callbacks, property stream, Init/PostLoad,
ownership handoff and any intervening physics/effect tick. It is an
interpretation fixture, not execution of original instructions.
"""
selected: int
movement_mode: int
jump_state: int
hold_seconds: float
fire_seconds: float
def project_jetpack_cleanup(state: JetpackCleanupProjection):
if state.selected not in (-1, 3):
raise ValueError('Only no-selection and selected-jetpack cleanup are modeled')
return replace(state, selected=-1)
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()
item = dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)),
expected=expected, actual=actual, matches=actual == expected)
if actual.startswith('e8'):
item['direct_call_target'] = hex(rel_call_target(pe, va))
sites.append(item)
tables = []
for name, table, slot, expected in VTABLES:
actual = struct.unpack('<I', read_va(pe, table+slot, 4))[0]
tables.append(dict(name=name, table=hex(table), slot=hex(slot), target=hex(actual),
file_offset=hex(pe.offset(table+slot-pe.base)), matches=actual == expected))
cleanup = []
for selected, expected in enumerate(CLEANUP_TARGETS):
va = 0x428844 + 4*selected
actual = struct.unpack('<I', read_va(pe, va, 4))[0]
cleanup.append(dict(selected=selected, va=hex(va), file_offset=hex(pe.offset(va-pe.base)),
target=hex(actual), matches=actual == expected))
select = []
for selected in (-1, 3):
va = 0x4298E8 + 4*(selected+1)
actual = struct.unpack('<I', read_va(pe, va, 4))[0]
select.append(dict(selected=selected, va=hex(va), file_offset=hex(pe.offset(va-pe.base)),
target=hex(actual), matches=actual == 0x428DE0))
tutorial = []
for item, (va, cleanup_va) in enumerate(zip(TUTORIAL_ENABLE_CALLS, TUTORIAL_CLEANUP_CALLS, strict=True)):
arguments = read_va(pe, va-6, 6)
target = rel_call_target(pe, va)
cleanup_instruction = read_va(pe, cleanup_va, 6)
tutorial.append(dict(level=f'VR0{item+1}', item=item, disabled=False,
va=hex(va), file_offset=hex(pe.offset(va-pe.base)),
arguments=arguments.hex(), target=hex(target), cleanup_va=hex(cleanup_va),
matches=arguments == bytes((0x6a, 0, 0x6a, item, 0x6a, 0))
and target == 0x403870 and cleanup_instruction in (bytes.fromhex('ff9278010000'), bytes.fromhex('ff9078010000'))))
tutorial_table = []
for item, expected in enumerate((0x42437A, 0x42439C, 0x4243BE, 0x4243E0)):
va = 0x424558 + 4*item
actual = struct.unpack('<I', read_va(pe, va, 4))[0]
tutorial_table.append(dict(level=f'VR0{item+5}', va=hex(va), file_offset=hex(pe.offset(va-pe.base)),
target=hex(actual), matches=actual == expected))
return dict(known_binary=digest == EXE_SHA256, sha256=digest, sites=sites,
vtables=tables, cleanup_table=cleanup,
select_table=select, tutorial_tail=tutorial, tutorial_table=tutorial_table,
menu_identity=read_va(pe, 0x4EF05C, 32).split(b'\0')[0].decode('ascii'),
final_action=read_va(pe, 0x4ED040, 8).split(b'\0')[0].decode('ascii'),
scope='Static immutable-source checks and bounded interpretation; no original runtime execution.')
if __name__ == '__main__':
cli = argparse.ArgumentParser(description=__doc__)
cli.add_argument('original', type=Path)
report = collect(cli.parse_args().original)
print(json.dumps(report, indent=2))
if not report['known_binary'] or not all(x['matches'] for key in ('sites', 'vtables', 'cleanup_table', 'select_table', 'tutorial_tail', 'tutorial_table') for x in report[key]):
raise SystemExit(1)
+141
View File
@@ -0,0 +1,141 @@
#!/usr/bin/env python3
"""Read-only GAM retained-object property-stream callback and descriptor evidence."""
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
DLL_SHA256 = '3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943'
EXTRACTION_NAME = '??5OMediaStreamOperators@@QAEAAV0@PAVOMediaClassStreamer@@@Z'
# (name, pointer argument LEA VA, exact LEA, interface offset, wire type,
# property-name literal VA, push-name VA). These are Jimmy's actual registered
# destinations, not inferred destinations from GAM key spelling.
DESCRIPTORS = (
('ObjectTag', 0x470403, '8d8ea0030000', 0x3A0, 1, 0x4F6044, 0x47040C),
('RotateToDest', 0x470427, '8d460a', 0xA, 2, 0x4F6034, 0x47042D),
('ObjectID', 0x47043E, '8d8604040000', 0x404, 6, 0x4F6028, 0x470447),
('PositionX', 0x470458, '8d86ec000000', 0xEC, 3, 0x4F601C, 0x470461),
('PositionY', 0x470472, '8d86f0000000', 0xF0, 3, 0x4F6010, 0x47047B),
('PositionZ', 0x47048C, '8d86f4000000', 0xF4, 3, 0x4F6004, 0x470495),
('RotationX', 0x4704A6, '8d86fc000000', 0xFC, 3, 0x4F5FF8, 0x4704AF),
('RotationY', 0x4704C0, '8d8600010000', 0x100, 3, 0x4F5FEC, 0x4704C9),
('RotationZ', 0x4704DA, '8d8604010000', 0x104, 3, 0x4F5FE0, 0x4704E3),
('TaskName', 0x45883F, '8d8630040000', 0x430, 1, 0x4F2870, 0x458848),
('Debug', 0x458859, '8d86a4040000', 0x4A4, 6, 0x4F2868, 0x458862),
('RequiredLevel', 0x40D3CC, '8d8e78050000', 0x578, 6, 0x4ED294, 0x40D3D5),
('ExactLevel', 0x40D3E6, '8d867c050000', 0x57C, 6, 0x4ED288, 0x40D3EF),
('RemoveLevel', 0x40D400, '8d8680050000', 0x580, 6, 0x4ED27C, 0x40D409),
('HasCollision', 0x40D41A, '8d8684050000', 0x584, 6, 0x4ED26C, 0x40D423),
('InitiallyVisible', 0x40D434, '8d8688050000', 0x588, 6, 0x4ED258, 0x40D43D),
('CanMove', 0x40D44E, '8d868c050000', 0x58C, 6, 0x4ED250, 0x40D457),
('SecondPass', 0x40D468, '8d8690050000', 0x590, 6, 0x4ED244, 0x40D471),
('PickupLink', 0x40D482, '8d8695050000', 0x595, 1, 0x4ED238, 0x40D48B),
('StartPoint', 0x43784F, '8d8664060000', 0x664, 1, 0x4EFB3C, 0x437858),
)
SITES = (
('loader_extraction_import', 0x46E3CB, '8b1d90d14800'),
('loader_property_call', 0x46E3FC, '56ffd3'),
('jimmy_ctor_property_registration', 0x422245, 'e876080000'),
('jimmy_properties_parent', 0x422AD7, 'e8544d0100'),
('player_properties_parent', 0x437846, 'e8755bfdff'),
('actor_properties_parent', 0x40D3C3, 'e8784f0500'),
('shape_properties_parent', 0x462356, 'e8c564ffff'),
('task_properties_parent', 0x458836, 'e8757b0100'),
('reader_name_read', 0x473B94, 'ff1508d24800'),
('reader_lookup', 0x473BA3, 'ff9000040000'),
('reader_wire_type_metadata', 0x473BC0, '894704'),
('reader_type_jump', 0x473BD0, 'ff2485783e4700'),
('reader_string_destination', 0x473BEE, '8b47488bce50ff1508d24800'),
('reader_int_destination', 0x473C43, '8b57488b4424348902'),
('reader_float_destination', 0x473C5F, '8b47488bce50ff15e4d34800'),
('reader_long_destination', 0x473CA7, '8b4f48518bceffd3'),
('reader_finish_returns', 0x473E6F, '81c4e8000000c20400'),
('lookup_returns_descriptor', 0x473F8F, '8b43085f5e5d5b81c408010000c20400'),
('register_destination_pointer', 0x473FFA, '8b4c241c894b48'),
)
FUNCTIONS = (
('registered-property reader', 0x473B30, 0x473E78,
'31d5e0051c36501b2251d136338650d0f1786238c844aea30916c4f9fc976ffb'),
('registered-property lookup', 0x473EB0, 0x473F9F,
'ee1435c3eb5d2728f10c70c900560afd459585b392e78c9248017ff49908c211'),
)
def site(pe, name, va, expected):
actual = read_va(pe, va, len(bytes.fromhex(expected))).hex()
return dict(name=name, va=hex(va), file_offset=hex(pe.offset(va-pe.base)),
expected=expected, actual=actual, matches=actual == expected)
def collect(root: Path):
pe = PE(find_case(root, 'Neutron.exe'))
dll = PE(find_case(root, 'OMT2.dll'))
exe_hash = hashlib.sha256(pe.data).hexdigest()
dll_hash = hashlib.sha256(dll.data).hexdigest()
sites = [site(pe, *s) for s in SITES]
sites.append(site(dll, 'DLL extraction receiver slot4', 0x10073E00,
'568bf18b4c2408568b01ff50048bc65ec20400'))
tables = []
for name, table in (('Jimmy', 0x4A373C), ('fire', 0x4A3160), ('Goddard', 0x49F480)):
for slot, expected in ((4, 0x473B30), (0x400, 0x473EB0)):
actual = struct.unpack('<I', read_va(pe, table+slot, 4))[0]
tables.append(dict(name=name, table=hex(table), slot=hex(slot), target=hex(actual),
file_offset=hex(pe.offset(table+slot-pe.base)), matches=actual == expected))
descriptors = []
for name, va, instruction, field, wire_type, literal, push in DESCRIPTORS:
matches = (read_va(pe, va, len(bytes.fromhex(instruction))).hex() == instruction
and read_va(pe, push-3, 2) == bytes((0x6A, wire_type))
and read_va(pe, push, 5) == b'\x68'+struct.pack('<I', literal)
and read_va(pe, literal, len(name)+1) == name.encode()+b'\0')
descriptors.append(dict(name=name, argument_va=hex(va), file_offset=hex(pe.offset(va-pe.base)),
interface_offset=hex(field), complete_offset=hex(field+0xC0),
wire_type=wire_type, literal_va=hex(literal), matches=matches))
functions = []
for name, begin, end, expected in FUNCTIONS:
actual = hashlib.sha256(read_va(pe, begin, end-begin)).hexdigest()
functions.append(dict(name=name, begin=hex(begin), end_exclusive=hex(end),
file_offset=hex(pe.offset(begin-pe.base)), sha256=actual,
matches=actual == expected))
route = []
for filename in ('gam/level1b.gam', 'gam/VR04.gam', 'gam/level1.gam'):
path = find_case(root, filename)
level = gam.parse(path.read_bytes())
jimmy = next(e for e in level.entities if e.kind == '3JIM')
route.append(dict(file=filename, code=level.code, offset=hex(jimmy.offset),
sha256=hashlib.sha256(path.read_bytes()).hexdigest(),
player_properties=sorted(jimmy.values()),
exact_descriptor_set=set(jimmy.values()) == {d[0] for d in DESCRIPTORS}))
imported = next(i for i in pe.imports() if int(i['iat'], 16) == 0x48D190)
exported = next(e for e in dll.exports() if e['name'] == EXTRACTION_NAME)
return dict(known_binary=exe_hash == EXE_SHA256 and dll_hash == DLL_SHA256,
exe_sha256=exe_hash, dll_sha256=dll_hash, sites=sites, vtables=tables,
descriptors=descriptors, functions=functions, route=route,
extraction_import=imported, extraction_export=exported,
import_export_matches=(imported['dll'].lower() == 'omt2.dll'
and imported['name'] == EXTRACTION_NAME
and int(exported['va'], 16) == 0x10073E00),
scope='Static bytes/data only; no original execution or runtime claim.')
if __name__ == '__main__':
cli = argparse.ArgumentParser(description=__doc__)
cli.add_argument('original', type=Path)
result = collect(cli.parse_args().original)
print(json.dumps(result, indent=2))
if (not result['known_binary'] or not result['import_export_matches']
or not all(x['matches'] for key in ('sites', 'vtables', 'descriptors', 'functions') for x in result[key])
or not all(x['exact_descriptor_set'] for x in result['route'])):
raise SystemExit(1)
+4 -3
View File
@@ -97,7 +97,7 @@ def inside(args):
try: processes.append(path.parent.name + ': ' + path.read_bytes().replace(b'\x00', b' ').decode('utf8', 'replace'))
except OSError: pass
(work/'processes.txt').write_text('\n'.join(processes)+'\n')
application_name = 'GamePort.exe' if args.port_smoke else 'omt_shape_probe.exe' if args.asset_probe else args.game
application_name = 'GamePort.exe' if args.port_smoke else 'isolated-probe.exe' if args.asset_probe else args.game
(work/'capture.json').write_text(json.dumps({'game': application_name, 'captures': captures}, indent=2)+'\n')
finally:
subprocess.run(['/opt/wine-stable/bin/wineserver', '-k'], timeout=10, check=False)
@@ -125,6 +125,7 @@ def main():
p.add_argument('--asset-probe', action='store_true', help='Run compiled read-only OMT shape probe inside isolated copy')
p.add_argument('--probe-model', default=r'ASE\jimstop.ase')
p.add_argument('--probe-executable', type=Path, help='Local probe executable to mount read-only for --asset-probe')
p.add_argument('--probe-success', default='VERTICES ', help='Required output marker for an isolated component probe')
p.add_argument('--output', type=Path)
args = p.parse_args()
args.port_smoke = args.port_smoke or args.port_window or args.port_walk or args.port_story or args.port_practice or args.port_cutscene_audio or args.port_jetpack or bool(args.port_regression)
@@ -201,8 +202,8 @@ def main():
else 'Windows port rendered under Wine; native Windows validation is still required')
if args.asset_probe:
result = json.loads((work/'capture.json').read_text())
if result['captures'][-1]['wineExit'] != 0 or 'VERTICES ' not in (work/'wine.log').read_text():
raise SystemExit('OMT asset probe did not complete; inspect wine.log')
if result['captures'][-1]['wineExit'] != 0 or args.probe_success not in (work/'wine.log').read_text():
raise SystemExit('Original component probe did not complete; inspect wine.log')
if __name__ == '__main__': main()