17 KiB
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:
- For matching SCENE milestones, call objective helper
406F50at 45FB5B / file5FB5B, before task record mutation. - 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. - 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.