Files
Neutron/docs/checkpoint/pair-lifecycle.md
T

9.6 KiB
Raw Blame History

Physical pair ordering and contact lifecycle

2026-11-06. Continues step4 of the movement plan after the Carl story-entry fix. This closes a bounded pair-dispatch contract. It does not admit new live scene physics, implement special Jimmy terrain callbacks or establish whole-game fidelity.

Recovered source and structures

Canonical Neutron.exe SHA256: f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8. tools/binary/pair_lifecycle.py guards8 complete source ranges and20 virtual bindings, records PE file offsets and retains the matching original instruction Evidence ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904. The generated probe relocates11 explicit absolute operands in private memory. The supplied originals are read only; the executable entry point is not invoked.

New local REA/Ghidra pseudocode Evidence:

Original VA / file offset Role Evidence ID suffix (all prefixed ev_)
479BC0 /79BC0 Physics scheduler; nonzero seconds, body pass then pair pass 56b7e074ec8509d1c5b3576d02361ff051963b777d7ccb8259ed9c65dc2db52f
47A430 /7A430 Ordered pair eligibility and notifications 8756a4c51d0c9215d3a36b86b673a2529bf74ed86bb9dcf630f66cbc398259b3
47B3E0 /7B3E0 Strict root-sphere overlap and callbacks b98a1806c11507d5105d6fb22e259efafd141fe3c862eb4bb6602468a93a658d
47CA90 /7CA90 Earlier body's exclusion list 3f2613369c1259cba7aadfc00b7383dbf7bd37def7085f003daf81802dddbc4e
470B20 /70B20 Base leave, optional wake, contact removal ae39adff84ac253cd370a2fd3f04ee7e9c00a6a6210d4f0222e938103a114d72
470BC0 /70BC0 Base stay/game callback cache c3f377c29e0818cb43ed7bcc58d4db3871ab34d1b54c329421591438b79f0d00

Complete replies/export and closed snapshot: artifacts/pair-lifecycle/rea/. Ghidra did not recognize470A60/470BF0 as requested procedures; error replies are retained. Its47B3E0 pseudocode misidentifies the first argument as a return-address value. Calling convention, stack arguments and the omitted leaf bodies therefore use guarded instructions plus actual copied-code execution, not that pseudocode. No repeated query is presented as successful decompilation of those two leaves.

The physical list at695D3C is a circular sentinel list of12-byte nodes: next+0, previous+4, game-interface pointer+8. This differs from the ordinary update registry50999C. Re-registration and repeated Init are documented separately in body registration. Each actor owns contact-list sentinel pointer+260/count+264 and exclusion-list sentinel pointer+254. These are interface-relative fields, not radius slot260. Base contact game-callback result caches are+408 enter,+40C stay,+410 leave.

State transitions and ordering

  • Viewport47E554 calls479BC0 before ordinary registry updates. Nonzero delta and global4F69E7 admit body integration479D20 followed by47A430. Pair global4F69E4 gates the latter independently; raw control5099E4 is not queried here.
  • 47A430 traverses each earlier physical node against itself and subsequent nodes. Identical actor pointers are skipped, with no reverse pair traversal. A duplicate physical node can cause another test of the same actor pair; it is not deduplicated.
  • Own220 is sampled once at the outer boundary; each inner actor's220 is read again. Mutual3A0 permissions follow. Rejected flags/permissions skip the pair without removing stored contacts or emitting leave. An outer actor disabled by its first enter callback can still contact later actors in that traversal.
  • First actor mode178=2 selects47A5E0(first,second); otherwise second mode2 selects47A5E0(second,first). Both mode2 preserves first-first selection. Other modes use47B3E0(first,second). Box geometry is a distinct contract.
  • Sphere query reads second root, first root, both radii and quick_magnitude. Contact requires strict distance<radius sum. Tangency is separation.47CA90 checks only the earlier actor's exclusion list, after the distance test; the later actor's exclusions are not consulted by this sphere query.
  • Successful sphere query invokes first4C then second4C before notifications, retaining the computed distance/result. A response may change a live root; the current pair still notifies, while later pairs read the changed root.
  • Each side independently queries membership3C. Positive overlap gives enter40 when absent, stay48 when present; separation gives leave44 only when present. The first notification can alter the second side's membership before its query.
  • Actual470A90 adds a contact unless already present or own deletion byte+6 is set. Actual470B20 optionally restores live integration214 when own210 is false and authoredB4 true, then removes matching nodes.470BC0 does not change membership. These base routines can request current-game callbacks when their cache is−1.
  • 470BF0 uses the other actor's1E0 inhibition flag. If clear, own integration210 permits414 response; a separate own1F8 branch may call60. Sleeping bodies can still enter/stay contact. The probe leaves1F8 false; full response60 remains open.

Original component execution and C# comparison

The native probe executes the complete pair pass, sphere/exclusion queries and base membership/enter/stay/leave/overlap routines in a hash-verified generated copy. Quick magnitude uses the copied OMT DLL export. Actors, vtables, permission getters, response414 mutations, allocation/free and box query results are explicit fixture adapters. No real Jimmy constructor, actor AI/contact consumer, static world reclip, original renderer or scene loader executes.

All28 cases pass under isolated Wine32 with no network or Original-directory mount. Cases cover enter/stay/tangency/leave/reentry, wake-on-leave, earlier/later/reordered exclusions, gate retention, three-actor order, callback root/flag/membership changes, duplicate identity, response inhibition, sleeping bodies and mode2 dispatch. Initial12s capture expired during prefix creation; a reused scalar-only prefix could not load OMT (error126, missing Wine DLLs). Both failures are retained. The successful run uses a copied initialized OMT-capable prefix; it is component evidence, not native Windows or whole-original gameplay verification.

OriginalPairCollision now translates the ordered pass and sphere query with live actor callbacks and explicit mode2 injection. It is intentionally not wired into SceneInteractions or LabSimulation. A stable physical list is required; callback insertion/removal of list nodes is not yet reproduced by this component. Base actor callback implementation remains the consumer's responsibility.

GamePort.PairLifecycleTests compares all28 native callback traces, contact masks, integration/enabled flags and root-X snapshots. Fixed copies of those finite expectations also run without generated artifacts. All28 complete comparisons pass. The fixture's synthetic base-callback behavior is not a complete actor implementation. The optional test rejects mode2 without an explicit solver instead of substituting the provisional capsule. Existing lookup-table/x87 precision limitations remain; these sphere fixtures use axis distances, not a proof of all boundary arithmetic.

Reproduce locally:

python3 tools/binary/pair_lifecycle.py ../Original \
  --output artifacts/pair-lifecycle/native \
  --rea artifacts/jimmy-movement-audit/rea-original-disassembly.json
i686-w64-mingw32-gcc -O0 -Wall -Wextra -Wno-unused-function \
  -o artifacts/pair-lifecycle/native/probe.exe \
  artifacts/pair-lifecycle/native/pair_lifecycle_probe.c
python3 tools/recon/reference_capture.py --asset-probe \
  --probe-executable artifacts/pair-lifecycle/native/probe.exe \
  --probe-success PAIR_LIFECYCLE_COMPLETE --seconds 12 \
  --output artifacts/pair-lifecycle/probe
python3 tools/binary/pair_lifecycle.py ../Original \
  --output artifacts/pair-lifecycle/native --capture artifacts/pair-lifecycle/probe
source scripts/env.sh
dotnet run --project tests/GamePort.PairLifecycleTests -- \
  --native artifacts/pair-lifecycle/native/observations.json

Use an initialized OMT-capable generated Wine32 prefix for the12s capture. source.json records identities/ranges/bindings; observations.json hashes the capture, executable and generated source. The capture verifier checks EXE/DLL copy hashes and observed probe identity. All generated evidence remains local.

VR04 eligibility coverage and next gate

Actual VR04 GAM contains Jimmy, Rocketship,3 YokianSoldiers and trophy among its records. Their4 class game tables bind220→471A30, mode178→471720, permission3A0→472F80 (unconditional true), overlap4C→470BF0 and210→4719F0. The3 soldier records explicitly request HasCollision1. Guard output retains their GAM offsets, tags, task/activation fields and20 common bindings. This removes any basis for treating their class permission callback as a blanket exclusion.

It does not establish the complete physical list: other GAM classes, generated children/helpers, task activation, constructors, exclusions, registration and live flags still matter. Visibility and raw-control ownership cannot substitute for that inventory. SceneInteractions currently groups selected player contacts after player processing; its single contact set, active/control gates and immediate talk dispatch are still approximations of these independent owners/phases.

Next: trace actual VR04 physical registration/activation and generated children, then recover shared nearest/last-polygon dynamic reclip ownership. Recover real Jimmy material160/164/FENCE/LADDER callbacks and persistent body/animation state before enabling source physics in lab/outside. Keep the existing playable baseline and clean ea04210 packages for comparison; this checkpoint changes no live route.