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

15 KiB
Raw Blame History

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.