Files
Neutron/docs/checkpoint/retained-streamer.md

100 lines
6.4 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.
# 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.