Files
Neutron/docs/checkpoint/physical-registration.md
T

139 lines
8.7 KiB
Markdown
Raw 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.
# VR04 physical registration and initialization boundaries
2026-11-06. Extends the existing [registration trace](body-root-registration.md)
and [pair contract](pair-lifecycle.md) with complete serialized-class coverage and
12 executed original-component cases. No runtime gameplay code or scene admission
changes in this checkpoint. The playable/package baseline remains924ad2f.
## Identity and evidence
Canonical Neutron.exe SHA256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
`physical_registration.py` verifies that identity,6 bounded source hashes,
13 RTTI interface identities,11 own-registration sites and78 method bindings.
It inventories every one of VR04's72 records with source GAM offsets/activation
fields. Original instruction Evidence is
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`;
bounded extracts, offsets, hashes and10 private-memory relocation operands are
retained in artifacts/physical-registration/native/source.json.
New local REA/Ghidra results:
- 464210 sprite bridge:
`ev_4d39cc1aaad564de60bb801c08dfeb740d52e507227e630de9b0570e3e1bc43d`.
- 436B80 derived AI/pickup gate:
`ev_95baf27f6c5f2949dcc5f03f77f3c45bcd14852595b0cc207b9ee27c1dbb02f9`.
Requests for46E570,40E1F0 and45F2B0 had no recognized procedure in this analysis;
complete errors are retained. Their instructions remain available in the earlier
full REA disassembly. No retry is counted as successful decompilation. Successful
results/export and closed snapshot are in artifacts/physical-registration/rea/.
The prior4623D0/458910/479A40 Evidence remains linked in body-root-registration.md.
## What registration actually owns
| VA / PE file offset | Recovered behavior |
|---|---|
|4623D0 /623D0|3D-object interface at complete+C0. Calls458910; copies current complete44/48/4C through16C; converts signed14-bit Euler fields through174; calls479A40.|
|464210 /64210|Sprite interface at complete+C8. Same registration shape with the corresponding−84/−80/−7C render-root offsets; converts Euler units by360/16384; calls479A40.|
|458910 /58910|Tests interface49E. When false invokes470A00 and sets49E=true. This gates the base hook, **not the later append in either bridge**.|
|470A00 /70A00|Logging hook ending at472970; it does not allocate a physical body node. This corrects an earlier allocation label.|
|479A40 /79A40|Calls own150(0,0,0), then own28 Init, then allocates/appends a12-byte physical node and increments695D40. The payload is the game-interface pointer. No identity deduplication or pair/integration gate occurs here.|
|42AB50 /2AB50|Jimmy/Rocketship outer49E guard: true returns; false jumps to4623D0. This is a distinct guard around the whole registration path.|
|46E570..46E69F /6E570..6E69F|Live registry traversal: own28 Init, attached-render handling, own40C PostLoad, attached-render handling, next node. Then app10C cleanup and47E470 timer reset.|
The physical list695D3C and ordinary registry50999C have separate ownership.
Common registration reads the current render transform, which is not a promise
that authored GAM properties have already been streamed. Constructor registration
can precede that streaming; later Init/PostLoad work owns later state publication.
The12-case copied-code probe establishes:
- Repeated direct4623D0 or464210 calls append the same interface again, repeating
transform/zero/Init callbacks even with49E already true. This is a function
contract, not evidence that every real actor naturally acquires duplicate nodes.
- Jimmy's guarded entry skips all that work when49E is set. Clearing49E admits
another append. Clearing a flag is not equivalent to clearing the list.
- A child registered from the supplied Init callback is appended before its
parent's append, because479A40 calls Init before allocating the parent's node.
The child callback is synthetic; no claim is made that all real Init methods do so.
- Pair flag140 and integration13E false do not prevent registration. Membership,
active integration and pair eligibility must stay independent.
- The previously recovered per-object Init/PostLoad order is confirmed by actual
46E570 execution. Nodes appended from either callback are visited later in that
same traversal. A snapshot/two-global-pass model would differ in these fixtures.
## All serialized VR04 classes
The following is a source inventory of **own registration sites**, not a complete
runtime body count. Constructor rows assume that constructor is actually invoked
and succeeds; reuse, nested helpers, later calls and scene state remain separate.
| GAM kind / records | Actual interface | Own registration site / phase |
|---|---|---|
|3JIM /1|C3DJimmy4A373C, complete+C0|4238B4 virtual2C during matching-start PostLoad; guarded42AB50|
|3ROC /1|C3DRocketShip4B25AC, complete+C0|43DB22 virtual2C in PostLoad; guarded42AB50|
|STRT /1|C3DStartPoint4B7654, complete+C8|Constructor44249D→464210|
|3PHO /2|C3DPhoneBooth4ADF6C, complete+C0|Constructor4356A0→4623D0|
|3PAT /34|C3DPatrolPoint4ACEE4, complete+C8|Constructor434D44→464210|
|3PIC /11|C3DPickupItem4AE548, complete+C8|Constructor435A37→464210|
|3SOL /3|C3DYokianSoldier4C19C4, complete+C0|Constructor44BFA4→4623D0|
|3TRO /1|C3DVRTrophy4BE404, complete+C0|Constructor448D33→4623D0|
|3AIT /2|C3DAITrigger48F8C0, complete+C8|Constructor40BE5B→464210|
|3CHK /1|C3DCheckPoint4959A8, complete+C8|Constructor414323→464210|
|LOAD /2|CLoadLevel4D025C, complete+C8|Constructor457CCA→464210|
|3CAM /12|C3DCutSceneCamera497BFC, complete+C8|No own registration call in the inspected constructor/base/PostLoad chain|
|3SM1 /1|C3DSmoke4B4F08, complete+C8|No own call in that chain; it creates a separately registered SmokePuff helper|
Thus57 serialized records map to own constructor sites,2 to PostLoad sites and13
to no own call in the inspected chain. These numbers partition records; they
are **not a claim of59 actual bodies**. All these interfaces expose InitPhysics,
including the two negative own-call classes. Having that method is insufficient
evidence that it is invoked.3CAM's class is the cutscene-camera subclass, not the
base C3DCamera. Source RTTI verifies the distinction.
Authored HasCollision/task/range values are retained per record. Generic activation
40E1F0, task callback40E340, pickup45F2B0 and derived436B80 have different ownership.
The recovered436B80 first calls40E340, then may hide an acquired optional pickup;
it does not establish an independent universal body-list removal policy. Current
live flags, deletion, exclusions and child activation still require tracing.
## Execution, reproduction and limits
`physical_registration_probe.c` executes copied4623D0/464210/458910/470A00/479A40,
42AB50 and46E570. Explicit adapters supply actor vtables/transforms, Init/PostLoad
callbacks, logging, allocation, app cleanup and timer. Render-presence byte8 is
false in loader fixtures, so attached-render branches are not exercised. No real
actor constructor, original game entry point, script/task world or renderer runs.
All12 cases verify full emitted callback/order/count/flag/Init/XYZ/Euler outputs
under isolated Wine32, with Original unmounted and network disabled. The helper
checks copied EXE hash, observed probe identity, exit0 and completion marker;
provenance and validated observations are retained locally. This is original
component execution, not native Windows or full original gameplay verification.
```sh
python3 tools/binary/physical_registration.py ../Original \
--output artifacts/physical-registration/native \
--rea artifacts/jimmy-movement-audit/rea-original-disassembly.json
i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wno-unused-function \
-o artifacts/physical-registration/native/probe.exe \
artifacts/physical-registration/native/physical_registration_probe.c
python3 tools/recon/reference_capture.py --asset-probe \
--probe-executable artifacts/physical-registration/native/probe.exe \
--probe-success PHYSICAL_REGISTRATION_COMPLETE --seconds 12 \
--output artifacts/physical-registration/probe
python3 tools/binary/physical_registration.py ../Original \
--output artifacts/physical-registration/native --capture artifacts/physical-registration/probe
```
The short capture uses a copied initialized generated Wine32 prefix; this scalar
probe needs no OMT DLL load. No runtime implementation or package identity changes
follow from these observations alone. [Generated helpers](vr04-generated-bodies.md)
records21 verified creation/registration calls and the remaining lifetime gaps.
Next: close helper reuse/removal and activation enough to reconstruct the actual
physical sequence for fresh and retained VR04; then integrate dynamic response
with original nearest/last-polygon reclip ownership. Keep the playable collision
baseline and separate OriginalPairCollision component until that boundary closes.