Files
Neutron/docs/checkpoint/jimmy-special-contact.md
T

131 lines
10 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.
# Jimmy special contacts: movement-stability audit
2026-11-04. Static recovery plus27 isolated original-dispatch observations; no
runtime solver change. Current playable fccc0b9 remains the baseline. The user
returned priority to Jimmy movement and explicitly allowed JN-Engine as a guide.
JN-Engine's prototype movement is not imported or treated as an oracle.
## Result and immediate implementation boundary
The lab/outside capsule bypasses material callbacks entirely: SceneCollision's
private triangles retain geometric positions/normals but no linked material ID,
and LabSimulation.StepPhysics receives only grounded/wall/ceiling flags. This is
a concrete missing interaction layer, not evidence that changing walk constants
or adding universal wall reflection will fix collision fidelity.
**Do not globally admit lab/outside to OriginalBodyPhysics yet.** Besides dynamic
pairs, three directly evidenced contracts are missing: material-driven hazard/
climb actions, world-response1D0 state during special animation, and contact-owned
root publication. The existing ordinary sphere composition assumes no
root-changing callbacks. Its wallContact hook alone does not establish the
source's fresh previous/live Vec4 equality or special-animation lifecycle.
For example, it currently adds the old falling displacement.Y after the hook
returns a root, whereas the original can skip that entire candidate publication
when the contact changed live/previous root. A root-changing callback cannot be
made faithful simply by returning a different OrdinaryBodyState.Position.
The smallest safe movement implementation chunk is ordinary ground/air arithmetic
and phase stability while preserving the current route solver. For collision:
first preserve/report actual contacted shape/polygon/3DMa identity in a diagnostic
path; next implement the state-owning callbacks and source body modes with
regressions; only then enable a bounded real lab/outside source-body route. Do not
silently classify a special contact as ordinary to make scene admission succeed.
## Original identity and source map
Neutron.exe SHA256:
f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8.
Every code VA below maps to raw offset VA−400000, independently checked by PE.
`tools/binary/jimmy_special_contact.py` records five bounded spans with hashes,
raw offsets and four live virtual bindings. Existing material loader/source
coverage is in collision-contact-callbacks.md and its guarded helper.
| Code VA / raw offset | Observed contract |
|---|---|
|43AA40 /3AA40|Player contact handler takes **game interface** (Jimmy complete+C0), supplied Vec4 normal and polygon. First requires elapsed game774>3; missing polygon/material/chunk yields no special policy. Reads signed archive3DMa ID through polygon+4→material+C→chunk+8.|
|43AA7E..43AAD5 /3AA7E..3AAD5|IDs120..129 call **complete virtual160**, IDs110..119 call **complete164**. These dispatches precede the movement-mode check and therefore still occur in nonzero modes.160/164 are slot offsets, not material IDs.|
|43AAD5..43AAF9 /3AAD5..3AAF9|Fence IDs60..69 and ladder180 require mode game704==0. Other metadata returns without generic reflection/projection. The handler contains no raw controlled-pointer gate.|
|43AB17..43ABBF /3AB17..3ABBF|Ladder first requires game338→472570 retained support polygon pointer (live234), then a47C210 probe. This is not the same predicate as current grounded218. A missing retained polygon prevents even the ray attempt.|
|43ACD4..43AE19 /3ACD4..3AE19|Fence requires first probe to miss and subsequent side probes to hit. Miss-only synthetic probes make exactly two calls then reject. Different ray outcome sequences are not equivalent to a single wall hit.|
|43AC29..43ACC5 /3AC29..3ACC5;43AF54..43AFDB /3AF54..3AFDB|Successful branches derive yaw from negative supplied normal through original angles, set destination/live orientation, transform local offsets, publish root314 and request LADDER/FENCE through complete150. Full successful-ray traces remain unexecuted.|
|42A7E0 /2A7E0|Jimmy complete160 requires splat cooldown1E60<=0 and !1DED latch. Requests SPLAT via150, sets latch, clears impact clock1DE8 and controller scalar complete6C8/game608, stores supplied normal at1DF0..1DFC, requests−5 energy/score through42A920/42ADC0, and SFX37. Those helpers retain their own tutorial/global policies.|
|42A8D0 /2A8D0|Jimmy complete164 requires !1DEC latch and raw gadget4F0588!=0 (Bubble0 immunity). Sets latch, clears1DE8, requests−5 energy/score, calls complete1E0→425120 (mode1 jump/effect cancellation). It does not share160's cooldown gate.|
|437953..43796A /37953..3796A|Increment game774 elapsed **before** base40E050 and later raw ownership gate. Physics contact reads the preceding phase's elapsed. Omitting this timer would permanently suppress source policies; gating it only on Jimmy input is also wrong.|
|43B408..43B4B4 /3B408..3B4B4;43B4BE..43B58A /3B4BE..3B58A|FENCE/LADDER animation entry owns saved destination Vec4 complete838..844/game778..784. Respective local offsets(0,320,150)/(0,800,150), velocity0, gameA8(false), action helper148, global busy4F83E0=true, duration complete888=4/6, fallback timer868=5, elapsed834=0, nonloop animation and SFX146/143.|
|43A900 /3A900|AnimEnded handler returns FENCE/LADDER to STOP, clears busy/duration, calls Jimmy game410→42AFC0, clears action flag complete6E4/game624 and controller speed complete6C8/game608, restores saved full Vec4 root314, then gameA8(true). SPLAT/HIT branches differ.|
|437988..437A15 /37988..37A15|Fallback timer game7A8 is decremented before input ownership gate. Expiry while busy can restore the saved root/response state too. Source duration4/6 and fallback5 are distinct; do not invent one universal fixed climb timer.|
|47A123..47A1C4 /7A123..7A1C4|Body publication rereads previous2F8/live310 and compares all four components. A contact-owned root change skips candidate clamp/publication. Vector3-only stale equality is not this boundary.|
Bindings independently checked: Jimmy complete4A3BDC+160→42A7E0,+164→42A8D0;
Jimmy game4A373C+374→42A660→Player43AA40; Player game4AF6C4+374→43AA40.
Game338→472570 returns retained polygon234, not a boolean grounded query.
GameA8→470FD0 changes **world-response** getter1D0/live13C. It does not disable
integration210, support1C8, raw control118 or global geometry4F69E5. Consequently
`geometryEnabled=false` in the current managed body is not an implementation of
this transition: that parameter follows global geometry-off gravity cancellation.
The pose setter's exact callback acceptance, source morph/event cadence, impact
latch/impulse updater4255C0, successful ladder/fence ray offsets/filters and reset
interactions need component/runtime closure before actual mechanics are enabled.
The stored impact normal is consumed later; immediate arbitrary velocity reflection
would replace that state machine with a different behavior.
## REA and JN-Engine evidence
JN-Engine docs/decomp/C3DPlayer.md, C3DJimmy.md and original decompiler bodies
in docs/decomp/evidence/c3dplayer_movement_target3.md/c3djimmy_target6.md supplied
function/field leads. Shared EXE identity is verified; its prototype movement and
its different declared OMT2.dll build are not numeric/runtime authorities here.
Class reports mix game and complete bases in places; the offsets above follow
authoritative instructions and the independently established+C0 interface.
Configured REA/Ghidra12.1.4 batch at artifacts/jimmy-special-contact/rea used the
existing generated target copy and exported Evidence/closed snapshot:
- 42A7E0: ev_801bbf1e21eb341f126f5e57e3efbfca42bb1c799680b2429c7f05dfdda3d625.
- 42A8D0: ev_889e1c63d50f8e6da7e451ba0b821396f884fb7d7961dcdede3c4f3ca0e54af3.
- 43A900: ev_0c030c12f6beb0790a6be2c53d3c4ac6591c8c2bd6552e8ea888f8de13455c7f.
43AFF0 returned an explicit procedure-recognition error; retained reply03.json
is not successful decompilation and the unchanged selector was not repeated.
Its supporting instruction extract is saved as special-animation.asm; the JN
body is only a lead. Reused43AA40 Evidence:
ev_4f2a6aa666451db831efd46f5c587573e22d8072315626b8bc2f844f9c6f0cae
under artifacts/collision-integration/contacts/rea-callbacks. REA x87/return-address
aliases are imperfect; reviewed call signatures/bytes settle the normal payload.
## Isolated original execution and tests
The new generated probe executes copied43AA40 with synthetic game/complete
vtables, linked polygon/material/chunk records, no-op160/164 callbacks and a
miss-only ray stub. It **does not** execute real damage, successful climb,
animation, body integration, collision traversal or the original game entrypoint.
An initialized local Wine32 prefix runs the copied code in the project's separate
network/filesystem sandbox; Wine exit0 and JIMMY_SPECIAL_CONTACT_COMPLETE are
retained in artifacts/jimmy-special-contact/probe/{wine.log,capture.json}.
27 observations cover signed metadata and all dispatch boundaries, strict elapsed
3/above3, nonzero movement modes, null polygon/material/chunk, missing retained
support polygon, and both hazard dispatch/fence ray attempts with raw controlNULL.
Normal Vec4 reaches160 unchanged. Miss-only fence performs two probes; ladder one
when support pointer exists. These are branch/gate observations, not terrain
success or original end-to-end movement traces.
`tests/test_jimmy_special_contact.py` commits the observations, original source
span/binding identity and generator/harness/executable/log hashes. Four Python
groups pass: source/offset/bindings, all27 native dispatch cases, provenance, and
output/original/symlink isolation. Originals remain untouched. No runtime source
or existing tests/docs were modified by this investigator; no commit was made.
## Proposed continuation gates
1. Keep source-backed controller/air/jump fixes and current playable route solver
independent; preserve fccc0b9 and subsequent tested movement checkpoints.
2. Expose contact metadata/root-ownership diagnostics; recover4255C0 impact latch
and impulse completion, then implement material120..129's bounded hazard flow.
3. Recover/verify successful climb rays, full animation-end/fallback ownership and
independent world-response mode before adopting fence/ladder callbacks.
4. Complete dynamic pair eligibility/shared context and Vec4 publication, then
run input-only lab/tutorial/RETURN/outside cases with known special contacts.
General floor/step/wall fidelity is not established by these27 leaf probes.