Files

173 lines
11 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.
# 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](body-root-registration.md).
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:
```sh
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.
## Integration and package verification
All338 Python tests pass, including2 new source/corpus checks. The28-case native
comparison and saved-reference replay pass; existing10 dynamic collision groups,
body-ownership and Director regressions pass. Debug build has zero warnings/errors.
Windows x64 cross-publish succeeds; its initial normal restore reports NU1900 for
unavailable vulnerability metadata. Clean packaging disables that metadata query.
Both packages identify clean source commit924ad2f67b5a2c3c90856366b0642c12da56d59e.
Each contains519 byte-identical original copies,4285 matching prepared scene files
and7 matching prepared audio files; DLLs match the corresponding publish outputs.
Standalone Linux from /tmp without SDK/development-library paths passes Carl first
neutral input/300 idle ticks/held-input return. All4 captures match the previous
ea04210 package exactly. This run disables optional Vulkan validation; prior
enabled-validation evidence remains separate. No new Windows runtime or whole-
original gameplay result is inferred. All539 originals remain unchanged.
Logs and hashes: artifacts/pair-lifecycle/validation.json, package-identity.json,
package-readbacks.json and package-control.log.
## 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 ea04210 readbacks as the
comparison baseline; current clean924ad2f packages preserve that live route.