Files
Neutron/docs/checkpoint/script-state-route.md

17 KiB
Raw Permalink Blame History

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. 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 at460E7B / 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 at460D2E / file60D2E. Thus duplicate per-task callback execution is present in the supplied binary. A final all-object slot420 traversal appears at460D87 / 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.