Document architecture checkpoint and restore original task callback order

This commit is contained in:
UnixNight committed 2026-10-25 12:56:17 -04:00
1 parent 69d0187a21
commit 531883aaac
45 files changed
+2935 -43

No files matched your search

+206
View File
@@ -0,0 +1,206 @@
# Script, task and transition ownership checkpoint
Read-only original investigation, 2026-10-25. Baseline audited:
`69d0187a2178deab1edff961d5126dad1cce3a05`. Preserve that playable baseline.
This checkpoint uses **fact** for original bytes/GAM data, **inference** for their
interpretation, **implementation** for modern source, and **runtime** only for an
executed game. No original-game runtime capture was obtained for this report.
## Source identity and reproducible evidence
| Original file | SHA-256 |
|---|---|
|`Neutron.exe`|`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`|
|`gam/level1b.gam`|`316fff40db565c2add5b07cbccdef640ddb67c64d6625fea1429ce2a0542a234`|
|`gam/VR04.gam`|`e34f6b6aa11ba1137dc4410148565b3c29db9d02c5fcc1f145017dafd2f3ca04`|
All executable addresses below are preferred-base Neutron.exe VAs. The inspected
sites have raw file offset **VA−0x400000**, independently checked using PE section
mapping, not assumed by the helper. GAM offsets are raw offsets in the named file.
`tools/binary/checkpoint_script_state.py ../Original` emits hashes, individual
VA/offset/byte records, resolved direct calls/vtable targets, and exact route GAM
fields. It reads originals and writes only stdout. The corresponding Python test
guards the decisive evidence. Cached `artifacts/binary/neutron.asm` was used for
cross-reference discovery; decisive sites were re-disassembled from the original.
## New inconsistency audit: task ordering
**Fact.** `45F990` does more than set a task value. Its phases are:
1. For matching SCENE milestones, call objective helper `406F50` at
**45FB5B / file5FB5B**, before task record mutation.
2. Traverse task list `4FC5FC`; case-insensitive match; store supplied state at
record+64 at **45FB7F / file5FB7F**. It updates existing records, including
repeated values; it does not insert unknown names.
3. Traverse game-object registry `50999C`; compare interface+430 TaskName;
matching objects receive interface slot424 at **45FBD9 / file5FBD9**.
The objective callback can therefore observe the **old task state**. Per-object
task callbacks observe the **new task state**. The call is synchronous: each
derived callback finishes before moving to the next registry object. This is an
ownership/order contract, not merely an eventual-state assertion.
**Baseline implementation mismatch.** `TaskStates.SetExisting` mutated records,
then invoked one `Assigned` event. `SceneDirector` was the first subscriber and
updated a batch of generic actors; `SceneInteractions` subscribed afterward and
selected the objective and applied all Carl overrides. Both objective timing and
derived-callback boundaries differed from the original. This justifies C1/C2 in
[implementation-plan.md](implementation-plan.md). The primary has implemented a
separate pre-assignment objective boundary during this checkpoint; integration
results belong to the primary ledger, not this static evidence report.
**Carl callback detail (new audit).** Interface vtable495364+424 points to413F30.
At **413F3D / file13F3D** it queries current SCENE via45FEA0, saves it in EBX at
413F45, then at **413F4E / file13F4E** calls generic40E340 with the supplied
callback value. Only after that base callback returns does it inspect level code
and run the LV1B override414068..414118. Thus its contract is **capture SCENE →
base activation → derived action**, inside one object callback. The override
uses the captured SCENE value, not a later reread. No reentrant task mutation was
observed in this investigation; this does not prove such mutation impossible.
For LV1B, scene outside0..60 disables Carl; >30 resolves CARLESC3, sets AIstate6
at4140AA and copies marker root via slot314 at4140E0; <60 activates him, exactly60
leaves base activation unchanged. Repeated assignments can therefore reposition
him. Applying this as a post-batch correction masks class behavior and can expose
partially updated state to actor observers.
## State owners, structures and lifetimes
Jimmy has a complete C++ object and a game interface at complete+C0. Mixing those
bases produced earlier apparent contradictions. Constructor4221E8/42220B installs
complete vtable4A3BDC and game-interface vtable4A373C. Player base constructor
437280 initializes inherited transition state. Read/write sites below retain the
base used by the actual instruction.
| Owner / field | Writes, consumers and lifetime |
|---|---|
|Global5099E4, controlled game interface|Game setter475A40; script/control handoffs replace it. Input, UI and player logic consult it. Null is a control state, not evidence that all world updates stop. Not a TSK field.|
|Task list4FC5FC; record name+0/state+64|45F990 mutates/broadcasts synchronously; trigger, actor and LOAD queries consume. Serialized by TSK.|
|Global4F8194 objective selector|406F50 updates selector and transient objective flags before SCENE mutation. TSK serializes selector; flags/timer are separate runtime state.|
|Jimmy complete+724, +774|Transition/start strings, written by43B5A0; writer460057..6F persists both. +774's wider role remains unresolved.|
|Jimmy complete+88C/+8F0|RETURN level/start strings, written by43B5A0, consumed by LOAD RETURN and persisted in TSK.|
|Jimmy complete+955|Staged level-name string, copied43B772..78C; not one of the four TSK strings. Dependency on game loader pending further recovery.|
|Jimmy complete+9A8..9B7|16-byte departure root captured by43B5A0 unless+9A5. First three floats serialize as TSK StoredVector. No yaw/velocity/camera state in this copy.|
|Jimmy complete+954|RETURN sets it; matching STRT consumes it to suppress the initial trigger once. Separate from root restoration; not serialized.|
|Jimmy complete+9A5|RETURN sets it; staging preserves departure root; Jimmy PostLoad consumes it and restores root. Not serialized.|
|Jimmy complete+1E38..1E47/+1E48|Independent pickup capture root/level.42AF00 writes;42AF50 writes plus attached effect callback. Not the TSK departure root. Read consumer unresolved.|
|Globals4FC604 filename/4FC67C pending|460E70 queues TSK load;460EA0 update consumes and clears. One pending filename, not a proven request queue.|
|Acquired table4F8438;19 inventory entries;score4F83C0;energy4F83D4|Global/save-owned data. Pickup/inventory/score actions mutate; TSK persists. Complete state-reset policy for ordinary level load is still open.|
**Vtable provenance.**4A3BDC+168→43B5A0, +1E8→42AF00,
+1EC→42AF50. Carl495364+424→413F30. LOAD4D025C+424→458880 only stores taskstate;
it must not inherit animated activation merely because its base has TaskName.
## First end-to-end source case study
| Route event | Recovered fact and state boundary |
|---|---|
|New game/lab entry|NewGame.tsk has SCENE30. LV1B STRT STARTEXP **GAM5B0E**, yaw155, StartTrigger LABEXP. STRT4426A7 validates the deferred target and clears controlled entity before dispatch.|
|Intro completion|AI/CAM/MCA chain recovered in lab-progression.md; DEFAULT447CF0 restores Jimmy/inventory, clears skip and conditionally restarts music. It does not simply assign SCENE35/60. Speech-end handles drive CAM/MCA update; port sample-duration timing remains an approximation.|
|Explanation|Special AI40CB43..6B maps SCENE30/31→35. Task setter selects objective1 before task records35 and actor callbacks.|
|Jetpack pickup|LV1B3PIC **GAM1799**, internal tagshrinkray, index301,+50,radius125. Generic435CE0 marks acquired/hides; special4365D0 only at SCENE35 calls Jimmy+1E8→42AF00 first; then SCENE50, group0/item3=1,406F90(0) practice prompt, gadget3. Positive score occurs after special hook. Pickup outside35 still has generic acquisition/+50 without those special side effects.|
|Practice No|UI modal resumes current level. It does not stage a departure or overwrite the RETURN root. Modern practice modal behavior is covered separately in camera/audio/UI checkpoint.|
|Practice Yes|4046AF stages VR04/PHONEBOOTH with current level/current STRT as RETURN context via complete+168→43B5A0.43B78E sees no pending RETURN, captures the live root into+9A8, then schedules game slot100 at43B7F1. Capture happens on acceptance, not necessarily on pickup.|
|Tutorial entry|VR04 STRT PHONEBOOTH **GAM48C**, yaw290, trigger sr1. Persistent task/inventory/acquired/score save-like state is distinct from new scene actors and playback handles. Source exact loader teardown order remains unresolved.|
|Tutorial exit|Two VR04 LOAD RETURN gates **GAMB0D7/B4C5**, radii400/350. RETURN457FF7 cleans gadget, sets+954 at458014 and+9A5 at458028; resolves saved level/start and dispatches transition168 at45815C. Staging must preserve lab departure root instead of capturing tutorial exit.|
|Lab RETURN|Jimmy423A90..9E consumes pending+9A5; root setter423ABF receives savedXYZ. Companion423AE3..423B1E receives identical saved root, no offset/yaw. Requested STRT supplies yaw155. STRT4427F2 consumes+954 and suppresses LABEXP entirely; fast-forwarding LABEXP would wrongly execute its actor/task actions.|
|Carl approach|Contact target match40A44C; AIstate6 contact40A676..68D sets0. Friend update41B950 invokes generic AI then41B972..988 dispatches talk when resultingstate0. General sensing/facing remains incomplete in port.|
|Carl conversation|Talk41BB20 chooses first existing matching task/wildcard target, retains it, derived callback413E50 first awards+100 and SCENE50→60, then41B7D3 dispatches selected neutron1a. Score150/SCENE60 precede dialogue. neutron1a **GAME0B** has5 shots, PlayerControlledJIM1 as completion target and NextTriggercarlwalk. Activation43159E clears control; completion4311F0 restores target.|
|Outside exit|LABTONEIGH **GAMA43** requiresSCENE≥60, no exact gate, radius200; destination **level1.gam / level1**. Earlier lab-progression.md's `startlevel1` is a documentation error: the exact GAM value is `level1`. Runtime source-field lookup already uses this value. LOAD contact's required-task gate457F32..5F is separate from generic activation.|
The source route does not require interpreting pickup42AF00 as respawn. It also
does not justify replacing ordinary level load with TSK file load: those are
distinct entry points with different transient flags.
## Save/load boundary: new call and callback audit
**Fact.** Writer45FEE0 locatesJIM1 via474070 at460043; the lookup returns game
interface. Its+8E8/+8EC/+8F0 writes46008B..B0 are complete+9A8/+9AC/+9B0.
Reader460A79 explicitly subtractsC0 from controlled interface, then460BA3/BAD/BBA
stores the same complete-object vector. This proves TSK StoredVector is departure
state; it does not serialize the separate pickup capture or pending954/9A5.
**New queue provenance.**460E70 sets pending4FC67C at**460E7B / file60E7B** and
copies requested name to4FC604. Caller sites include404B54 (NewGame),406E80,
40D08E,4247F0,424BCF,42B1B9..42B21B (slot-name dispatch).460EA0 first executes
its inherited/update logic473240, then460EE1 tests pending,460EF0 calls4603F0
with filename,460EF8 clears pending. These are deferred TSK load calls; menu
request ownership and engine update scheduling require the loop investigation.
**New double-callback fact.** Each valid saved task is sent through45F990 at
**460CE2 / file60CE2**, including its objective and ordinary actor callbacks.
The reader then makes another registry traversal and calls matching non-none
TaskName slot424 again at**460D2E / file60D2E**. Thus duplicate per-task callback
execution is present in the supplied binary. A final all-object slot420 traversal
appears at**460D87 / file60D87**, after positive-count task loading; the no-task
branch460C65 jumps to cleanup460D98 and skips that traversal.
Do **not** call slot420 Jimmy placement PostLoad: vtable4A373C+420 is472970,
the log helper; Carl495364+420 is413EB0. The placement/root code423A90 belongs
to a different initialization path. Exact function names for slot420 remain
unproven; use “post-task slot420” until class-specific behavior is mapped.
**Actual placement PostLoad provenance (new audit).** Jimmy game vtable
4A373C+40C points to423610; its first log literal4EF3B4 explicitly says
`Calling PostLoad for C3DJimmy()`. Registry traversal46E570 invokes each object's
slot28 at46E5C3, conditionally handles an attached/render object, then invokes
slot40C at **46E61A / file6E61A**, before moving to the next registry entry.
Within Jimmy PostLoad, matching STRT lookup42385B..423885 precedes authored root
application42399D, authored rotation4239E6, available companion source-root
application423A36, RETURN test423A90/clear423A9E, saved-root application423ABF,
same-root companion application423B1E, and game control assignment423B3D. Camera
viewport setup follows423B43. This establishes local call order, not the full
caller chain from game slot100 to46E570; the latter remains C7 work.
Separate lifecycle callback4235B0 (Jimmy game slot3C8) conditionally clears4200
acquired integers at4235E9..5EE and calls group2 inventory helper for29 entries
when global50988A is set. Follow-up `scene-loader.md` proves this is R in the
virtual-key table509838, consumed only in editor3C8 mode. It is not an ordinary
loader-reset flag. Ordinary selective retention and per-field PostLoad behavior
must be traced separately before generalizing item reset/persistence.
**Baseline implementation.** `OriginalSave` parses/encodes all12 supplied TSKs;
`TaskStates` and fresh `SceneDirector` construction restore modern state.
CLI `--write-save` serializes existing StoredVector, not necessarily current
player root; this matches the recovered departure-field identity, but is not a
complete original save UI. `Program.SceneContinuation` carries root and explicit
Returning; `SceneInteractions.Snapshot` carries arrays/task/inventory/score/
energy/return strings. New scene actors/audio are reconstructed. The port does
not reproduce the queued TSK reader, duplicate broadcasts or all-object420 path.
These should be investigated before implementing full source resume behavior.
## Independent checkpoint consumer audit
42AF00 captures current game level from509948+490 into+1E48 and root getter310
into+1E38.42AF50 repeats this then attached+ A18 object's slot4B8 effect call.
Constructor4221E2 initializes checkpoint vector fourth component+1E44 to1.
An explicit operand search in the EXE disassembly for complete+1E38/+1E3C/
+1E40/+1E44/+1E48 and interface-relative+1D78/+1D7C/+1D80/+1D84/+1D88 found
capture/constructor writes, but no demonstrated read consumer.42B2A3's subtract
1E48 is a virtual-base adjustment thunk, not a checkpoint read. This bounded
search is negative evidence only: aliases, indexed/member pointers and other
modules can hide consumers. No death/respawn/reset policy is established.
## Coverage, unresolved questions and next gates
| ID | Remaining question / evidence gate | Bounded action |
|---|---|---|
|S1|Full registry order and reentrant mutations unknown; capture-before-base matters for Carl.|C2 preserve per-actor query/base/derived boundary and test notification sees final Carl state. Do not add invented class callbacks.|
|S2|What owns ordinary game slot100 load request and which globals/actors persist?|C7 trace43B7F1 receiver vtable, staged+955 string and loader update through scene construction/destruction. Contrast with460E70 TSK path.|
|S3|Why does TSK reader duplicate callbacks; what does420 do per class?|Build source callback trace for Carl/pickup/LOAD; compare same-value assignment/load before adopting duplicates. Preserve exact no-task branch distinction.|
|S4|Independent pickup root/level consumers unknown.|Trace virtual-base/member aliases and constructor RTTI before labeling respawn. No gameplay change justified now.|
|S5|RETURN flag survival and matching STRT consumption through all loader paths.|Trace actual ordinary scene loader and PostLoad order; test initial trigger suppression independently from placement and TSK resume.|
|S6|Exact script/physics/contact scheduling and sound-handle completion incomplete.|C3/C6 phase and voice trace; avoid treating null control as whole-world pause or file duration as source end event.|
|S7|Persistent energy/inventory/29 counters reset policy beyond route unclear.|Recover load/constructor globals writes; preserve unknown wire values; no normalization or minimum task assumptions.|
Recovered route contracts and these explicit boundaries are sufficient for C1/C2,
and for a concrete C7 investigation. Full source resume, generic scripts and
other levels remain incomplete. Current route managed/headless tests and user
Windows reachability provide port evidence only; they do not prove the original
end-to-end behavior or original runtime timing.
Validation for this report: `python3 -m unittest discover -s tests -p
test_checkpoint_script_state.py -v`; five tests assert binary identity,25 byte
sites,8 vtable dependencies, task/Carl ordering, deferred load call, distinct
source destinations and bounded helper rejection. Source files only were read;
no original executable was run.