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

207 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.