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

6.4 KiB
Raw Permalink Blame History

Retained Jimmy: GAM property-stream boundary

Static C3/C7 follow-up,2026-10-26. Read-only analysis of supplied Neutron.exe SHA256f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8 and OMT2.dll SHA2563ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943. 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.