Files
Neutron/docs/checkpoint/collision-contact-callbacks.md

254 lines
15 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.
# C4 contact callbacks, landing and friction
2026-10-26. Static recovery for original EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Addresses below are preferred VAs; these text offsets are VA−400000. The helper
maps PE sections independently and retains exact bytes, offsets, 20 virtual
targets and six complete callback hashes in
`artifacts/collision-integration/contacts/source-contract.json`.
## Recovered dispatch and state ownership
The game-interface pointer is complete object+C0. Slots below are relative to
that interface, not the complete-object movement slots130/134.
| Class/interface table |370|374|378|37C|
|---|---|---|---|---|
|C3DObject4D3154|472690|458890|472750|472970|
|C3DAnimated48FE1C|472690|458890|472750|472970|
|C3DPlayer4AF6C4|472690|43AA40|472750|472970|
|C3DJimmy4A373C|472690|42A660|472750|472970|
Static traversal47B4B0 publishes its candidate current root at47B7B1..BD,
then reads last-hit polygon695D4C. If present, it copies polygon+8..14 normal
and dispatches374 at47B80F if normal.Y is strictly greater than float32−0.7
(4A3148, bytes333333BF); otherwise370 at47B82E. Equality dispatches370.
The arguments are a by-value four-float normal and polygon pointer. This occurs
after grid/triangle response, before the body's later support/friction phase;
the supplied original stored normal is not derived from triangle winding.
370→472690 (raw72690, lengthBA) independently reads live velocity2BC and
acceleration270. A strictly positive Y is set to zero through2C0/274;
nonpositive Y and X/Z/W are preserved. It does not project against the supplied
normal or change movement mode, jump latch, fire timer or horizontal speed.
Generic374→458890 (raw58890, length3D) checks interface1D8, then forwards the
four-float normal to378→472750. Jimmy overrides374:42A660 (raw2A660,lengthB4)
forwards to Player43AA40 at42A70B on the ordinary path. It does **not** enter
generic374/378 on that path. Therefore generic reflection/projection must not be
attached to every Jimmy wall contact merely because base378 exists.
No-selection−1 and selected-jetpack3 both take this ordinary branch because
neither equals7 (selection identities recovered in retained-return-cleanup.md).
For a nonspecial metadata ID, neither state adds velocity, position, orientation,
mode, jump or gadget-side effects through374. This bounds the route's supported
states; it does not imply every material on the route is nonspecial.
Jimmy's gadget7 branch additionally checks global4F8210. When set, it invokes
Player contact, zeros global4F82BC/C0, tests their prior two-component magnitude
against60, and may invoke complete-object204 and set interface1D65. Those
gadget effects remain outside ordinary-contact integration.
## Player material handler
43AA40 (raw3AA40,length5A3) first requires interface774 elapsed>3.0. The signed
discriminator comes from polygon+4 → material+0C → database chunk+8; missing
records produce no ordinary effect. The follow-up below proves this is the
3DMa archive resource ID, not an additional custom payload flag. It remains
distinct from a merged render-array index or texture resource ID.
| Metadata ID | Effect after elapsed gate |
|---|---|
|120..129|Calls complete-object160 with supplied normal.|
|110..119|Calls complete-object164.|
|60..69, only mode704==0|Additional rays/orientation/root/action handling ending in FENCE.|
|180, only mode704==0|Additional rays/orientation/root/action handling ending in LADDER.|
|Others|Returns without generic velocity projection or mode/jump reset.|
These are dispatch facts, not complete recovery of the four special policies.
Complete160/164 effects and all ray success/failure transitions need separate
tracing before implementation. The ordinary callback has no raw-control5099E4
gate; controller ownership alone cannot justify suppressing contact effects.
## Material database identity and actual route coverage
OMT2.dll SHA256 is
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
The EXE chain above reaches OMediaDBObject's inherited database association:
| DLL VA / raw offset | Proven role |
|---|---|
|10030070 /30070, exported db_link|Arguments are database, OMediaFSChunk*, type.1003007F stores that chunk pointer in material/object+0C; chunk+0C is the reciprocal object pointer.|
|10030260 /30260, DBObjectStreamLink::read_class|Reads link fourcc through100302B3 and signed long ID through100302BF;100302EE calls database get_object(type,ID), stores resulting material pointer in temporary streamlink+4.|
|10003E20 /3E20, Polygon::read_class|10003F56 reads a temporary stream link;10003F5B obtains its pointer at temporary+4;10004277 calls set_material100043F0.10004408 publishes it in polygon+4, with material reference-count bookkeeping. The legacy-version path10004252..5E also uses set_material.|
|1002DEF0 /2DEF0, DataBase::get_object(type,long)|Looks up the requested chunk through formatted-stream slots6C/74, then passes that chunk to object's virtual18/db_link at1002E0B0.|
|10045B70 /45B70, FormattedStream::get_chunk(node,long)|Looks up signed ID in the chunk map, returns the corresponding chunk record (list-node+8).|
|100464C0 /464C0, FormattedStream::load_header|100465A7 reads ID into stack58;100465B4/C1 read offset/size into stack50/54;10046638..46 insert record starting stack50. Thus ID is chunk record+8.|
The on-disk source is the 0MF2 resource-table entry's big-endian32 identity,
not a field inside the 3DMa material payload. The payload parser's trailing BE16
is3 for every used material in all three archives, including special and
ordinary contacts. The helper records each material's exact table ID byte offset,
separate payload offset/size/hash, archive hash, and source shape/polygon identity.
Negative on-disk IDs require signed32 interpretation for policy comparisons;
all special route IDs below are positive.
| Archive | Special ID | Non-NC polygons using ID | Wall-grid polygons eligible for374 |
|---|---:|---:|---:|
|level1b.omt|61|23|20|
|level1b.omt|62|24|24|
|level1b.omt|63|4|4|
|level1b.omt|120|4|4|
|level1b.omt|121|32|20|
|level1b.omt|122|3|3|
|level1b.omt|180|6|6|
|VR04.omt|none|0|0|
|level1.omt|60|62|62|
|level1.omt|61|51|38|
|level1.omt|62|38|26|
|level1.omt|180|32|20|
Eligibility means registered shape and strictly−0.7<stored normal.Y<0.7:
the lower test dispatches374; the upper test is wall-grid registration. Route
checkpoint-name exclusions are zero (camera-ray-predicate.md). Counts do not
prove a particular player trajectory hits these polygons. LV1B examples are
crates/topcrate shapes76/77 with ID61, Box25/83 with62, Object07/91 with63,
Plane41/51 and Object03/73 with120, Cylinder13/22 andCylinder14/23 with121,
Object03/73 with122, Box31/93 with180. Level1 has fence/bush/blocks/ladder-class
polygons; names are explanatory labels, not policy evidence.
The route cannot be declared ordinary-only. Preserve linked3DMa identity in
CollisionPolygons, retain unsupported special callback boundaries, and test any
ordinary-only integration against the actual contacted polygon's ID. Resource
identity is now justified by the loader trace, rather than assumed from naming.
## Landing order
Support47B890's successful branch calls these virtuals in order:
1. 47BB32: publish root318.
2. 47BB4B: acceleration278, Y=0, retaining original X/Z.
3. 47BB5E: landing37C only if previous-support695D49 was false.
4. 47BB74: velocity2C4, Y=0, retaining original X/Z.
5. 47BB80: support21C=true.
6. 47BB91/47BBA1: contact shape34C and polygon33C.
Jimmy37C→472970 (raw72970) is exactly `C3`/return. Thus the landing callback
would observe the new root/zero vertical acceleration but old velocity/support;
Jimmy itself adds no mode/jump/fire reset here. Controlled movement and the
independent fire callback own their later grounded transitions. Do not merge
these source phases into a universal landing-mode reset.
## Friction and speed publication
479D20 calls support47B890 at47A235 when interface1C8 permits it. It then reads
268 at47A241 and calls47A330 at47A25A only if the returned scalar equals0.
268→471B50 reads interface160. The controlled movement tail437C22 reads its
current scalar speed608, pushes it at437C2A and publishes through26C at437C2D;
26C→471B60 writes160. Publication follows ground/air apply and is skipped by
the earlier ownership/modal gates. Treat published160 and controller608 as
separate state with that copy point, not a fresh input query during friction.
47A330 (raw7A330,lengthF1) requires a nonnull body, support218=true and strictly
positive imported quick_magnitude of the full linear XYZ vector. It reads
friction248→471AD0/live150. It adds these deltas through2CC and2B8:
```
linear delta = (-vx * friction * dt, 0, -vz * friction * dt)
angular delta = (-wx * friction * dt, -wy * friction * dt, -wz * friction * dt)
```
No multiplier clamp is present. Zero linear velocity skips angular friction too;
pure vertical linear motion permits angular friction but leaves vertical speed.
No controller pointer, movement mode, jump or animation state gates this helper.
The enclosing body's later suppression is distinct:230→471A70/live144 scales
quick_magnitude. Angular magnitude×144 <=float32(0.1) zeros angular velocity;
linear magnitude×144 <=0.1 zeros linear velocity only when268==0. The finite
equality boundary is included by the AH&41 tests at47A2C5/47A2FA. The semantic
name of144 is not established by this bounded contact investigation. Follow-up
REA471120 and constructor46FE01..08 recover the default0.5; this is called a
suppression scale in the implementation plan without assigning physical units.
Constructor byte confirmation: generic46FDC8→470FA0 sets1C8/live13B true;
46FDD1→470FD0 sets1D0/live13C true;208/live13A starts false at46FDBF but
Player43740D→470F70 overrides it true (EDI=1).220/live140 defaults true through
46FDF4→4710C0 (authored18);228/live141 defaults false through46FDFC→4710F0
(authored19). Generic46FFB1 writes interface42C=BL=0, with EBX zero at46FC08.
These are constructor defaults, not invariants after property/script changes.
## Evidence and verification
Own REA CLI sessions used only the generated
`artifacts/uncontrolled-phases/rea/Neutron.exe`, Ghidra provider. Complete open,
procedure replies, exported evidence, close and snapshot files are preserved in
`artifacts/collision-integration/contacts/rea-callbacks/` and
`rea-offset-followup/`. Both sessions closed. Session analysis errors are also
preserved;42A660 and472750 were unrecognized by both VA and corrected raw-offset
selectors. This is a REA procedure-recognition limitation, not evidence of an
absent function. Their bounded conclusions use reviewed source instructions and
fixed byte/vtable guards; no pseudocode is attributed to those failed queries.
| Procedure | REA Evidence ID |
|---|---|
|472690|ev_122849f87121b02fefe6a3a443f75c7f02fee30c59c816b617d30e1f98fc2cff|
|43AA40|ev_4f2a6aa666451db831efd46f5c587573e22d8072315626b8bc2f844f9c6f0cae|
|47A330|ev_8be4a538fe941bcf0ba77ce64f552d4f0e17969ea87713cec5d37d39bc560735|
|472970|ev_1af0165b36fee8d2c680091bdaa560a63092016b1010baa947b0fe672f790520|
|458890|ev_2e4ec83ea68f06777162a80ab45793cff068e973dc248556d4a408932d24c85a|
Caller/traversal evidence is reused from collision-response.md, especially
479D20 `ev_5439072b32ae9f9208795ad2b07bc524e2407b46da487072fb3dfd8c10e7c4b0`
and47B4B0 `ev_d45e078c585d3773494c0e0dfb1696178dd0b8ce8b696caf133892ff070e552e`.
Reviewed instruction cache: `artifacts/retained-lifecycle/exe-disassembly.txt`.
`python3 -m unittest discover -s tests -p test_collision_contact_callbacks.py -v`
passes eight tests: original identity/50 sites/20 virtuals/six complete bodies,
normal threshold equality, independent positive-Y clearing, material branch
boundaries, no-selection/jetpack gadget exclusion, friction gates/no clamp, and
landing callback observation order;11 DLL linkage/header/publication byte guards plus
decoded route special-ID coverage and payload/table distinction.
The helper fixtures are explicit source projections, not original execution or
x87 numeric identity. No original process ran during the independent callback
investigation; primary's later isolated dispatcher/body executions are documented
separately in collision-body-probe.md.
Confidence is high for guarded targets, finite-input gates and write order;
special callback policy and native runtime equivalence remain unverified.
Follow-up own closed REA sessions and complete exports are in
`artifacts/collision-integration/contacts/rea-material-identity/` and
`rea-material-chunks/` and `rea-polygon-material-link/`, using the generated
asset-probe/game/OMT2.dll copy. All three sessions closed and exported evidence.
| Procedure | REA Evidence ID |
|---|---|
|10030070 db_link|ev_68d90891887ea6865b9caa01929af4c321701bd7c4a2812727fdf42c75cc4007|
|1002DEF0 get_object|ev_81d436d02d94e725815b1f09da5e5a70d12a65a699580a4f4d766fd637e25c9a|
|10030260 stream link|ev_a36a19b371e3f9202b8e7b44f6756593081a18da9f24dcb3a23fcdd92836ad9a|
|10001490 material read|ev_f592b625a60ec683a17627d671c47d78d722eb39d5eb407744d53a283ee2586d|
|10045B70 get_chunk|ev_1eef58e78dd2025953bfc6d29d750992ad031eff3ade40848b565b70493a51af|
|100464C0 load_header|ev_25667da3ab34f3e3a238282bf667878fa957db0b59501f737178637dd8fe2d61|
|100451E0 create_chunk|ev_bb9a4656bc3b4cc1ebd2ce7da540b2f5d633632cc70b9548f30942e52c806868|
|10003E20 polygon read|ev_a611c0c32859d598bd4f02c071cc8f57dec8e85c821593187d3ea6d0b2db18cb|
|100043F0 set_material|ev_66c8163e76d1c4621dd75dbad433b6810d7dc6f69da84d4bdcd6644df935736b|
|10073E00 stream operator|ev_01e2fb540f6adee163371853f0823abcd4a67553b0dc7d067ef88a448ce87740|
## Minimal implementation contract and limits
OriginalSphereResponse currently implements only the bounded triangle kernel;
LabSimulation still calls its capsule adapter at inspection time. Integration
should retain the original traversal's final contact polygon and stored normal,
publish the root before contact dispatch, apply inherited370 positive-Y clearing,
and preserve ordinary374's material-policy boundary. Then run support in its
source order, friction using persisted published160, and separate small-motion
suppression. Contact callbacks are eligible when Jimmy is uncontrolled if the
body phase itself runs; they do not grant input ownership.
Do not add generic horizontal velocity projection, automatic jump/mode reset,
or unconditional friction to compensate for adapter symptoms. Static geometry
order/duplicate visits, dynamic reclipping, negative-Y split and support query
coverage belong to the separate body integration trace. Generic378's complete
reflection arithmetic, special materials, gadget7, runtime-mutated flags,
144 semantics, NaNs and x87 threshold identity remain explicit gaps. Native
Windows gameplay and the lab→tutorial→lab→outside route still require runtime
comparison after integration; these static fixtures do not claim that proof.