Files
Neutron/docs/checkpoint/body-modes.md
T

132 lines
9.1 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.
# Body modes and post-callback ownership
2026-11-05. This closes a bounded prerequisite for Jimmy's special contacts; it
does not enable new terrain/climb policies or replace the lab/outside capsule.
The authoritative EXE SHA256 is
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
JN-Engine gameplay is not the oracle. Retained REA instruction Evidence
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`
is artifacts/jimmy-movement-audit/rea-original-disassembly.json; the original
479D20 procedure Evidence is
`ev_5439072b32ae9f9208795ad2b07bc524e2407b46da487072fb3dfd8c10e7c4b0`.
No unchanged failed Ghidra selector was repeated. This investigation reuses those
instructions and independently guards the complete body/support/friction spans.
## Source branch and state map
Addresses are EXE VAs; raw offsets equal VA−400000 in these PE-mapped spans.
Slot numbers refer to the body/game interface, Jimmy complete object+C0.
The generic data fields and initialization are separately recorded in
[body composition](collision-body-composition-source.md).
| Source VA / raw offset | Recovered phase |
|---|---|
|479D2E/479D34 /79D2E/79D34|Read supported218; cache prior support695D49 even if integration will reject.|
|479D3D..479D4E /79D3D..79D4E|If support handling1C8, clear supported21C(false). Otherwise preserve the previous supported flag.|
|479D58..479D60 /79D58..79D60|Integration210=false returns after those effects: root/previous/anchor, impulse, velocity, acceleration, angular velocity and static context remain unchanged.|
|479DDA..479E54 /79DDA..79E54|Global geometry4F69E5=true publishes anchor(0,−25000,0). False publishes supported=true, anchor(0,currentY,0), acceleration(0,+800,0), velocity(oldX,0,oldZ). Pending impulse still applies later.|
|479E63..479FD2 /79E63..79FD2|Rotate by angular×dt; consume impulse once; add acceleration then gravity separately; compute displacement from final velocity.|
|479FD6 /79FD6|Collision220 gates the post-integration branch.|
|479FE8 /79FE8|When collision=true, world-response1D0 selects clipping versus direct translation. This is not the integration/global-geometry gate.|
|47A038..47A096 /7A038..7A096|World branch alone resets last polygon/nearest face130000/nearest edge radius/auxiliary; captures full live root into previous2FC, then dispatches world traversal.|
|47A123..47A1C4 /7A123..7A1C4|World path compares fresh previous/live Vec4; equality permits candidate clampY≥−25000/publication314. See the independent root-publication investigation.|
|47A1CC..47A220 /7A1CC..7A220|Collision=true/world-response=false copies live Vec4 to previous, then translates31C(displacement). No static-context reset, world dispatch or−25000 clamp.|
|47A22A /7A22A|Fresh support1C8 read after world callback/publication/direct translation; true calls47B890.|
|47B890 /7B890|Support independently rereads global geometry. False skips its query/result publication; it does not retroactively cancel the gravity already consumed earlier in479D20.|
|47A241..47A25A /7A241..7A25A|Fresh published-speed268==0 enters friction47A330. That helper reads current supported218 and only damps when supported and magnitude>0.|
|47A264..47A28E /7A264..7A28E|Collision=false reads alternate228: false translates31C; true holds root. Both skip previous-root copy, support and friction.|
|47A294..47A31D /7A294..7A31D|All integrated branches reach suppression. Angular and linear quick magnitude×scale≤.1 clear the respective velocity; linear additionally requires a fresh published268==0. Rotation already happened, even if angular velocity is then cleared.|
A support-disabled body may retain supported=true, including while moving upward.
If collision is enabled, that stale-but-owned supported state still allows
friction. Disabling support is not permission to clear it unconditionally.
Collision-disabled bodies skip friction even when global geometry-off forced
supported=true. World-response-off retains integration, gravity, impulse,
optional support and friction, plus the prior static context. F3 noclip remains a
separate modern policy.
## Flag mutation timing
The source does not reselect a branch already entered. Synthetic world callbacks
that change integration210, collision220 or world1D0 still finish the selected
world publication/support/friction path in the current call. The changed flags
persist for a later call. Support1C8 is read fresh after world dispatch, so changing
it there suppresses the current support query. Global geometry is also read fresh
inside support; changing it during world work suppresses support while retaining
the already integrated gravity/acceleration and earlier anchor.
For example, the final native fixture's world mutation5 changes global geometry
to false after integrating fallingVy−213.333328. The output still has that Vy,
acceleration0 and anchorY−25000, with no support query; it is not the early
geometry-off result with acceleration+800/support=true/vertical cancellation.
A mutable scene-global getter can represent that read boundary; embedding a new
per-body geometry flag would misstate its ownership. No live original writer or
new gameplay use of that global is inferred from the synthetic callback.
## Landing37C: writes before and after callback
47BB10..47BB4B publishes anchor, supported root through318 and acceleration
(oldAx,0,oldAz). It checks prior supported695D49 and invokes37C at47BB5E only on
an unsupported→supported transition. The callback observes the new root/anchor/
zeroed vertical acceleration but old live velocity and supported=false.
47BB64..47BB80 then overwrites velocity with **cached pre-callback VX/Z and Y0**,
and writes supported=true. Support pointers34C/33C follow at47BB91/47BBA1.
Consequently:
- Callback velocityXYZ and supported edits are overwritten, even though the
callback legitimately owned them during its invocation.
- Callback root (including W), acceleration, anchor and pending impulse survive.
Pending impulse is not consumed a second time; its next owner is a later body pass.
- Modes and published speed survive. Published speed is read fresh by friction;
changing it to100 skips damping in the same call.
- Callback angular velocity survives into friction/suppression; with(7,123,9),
friction.8/dt1/60 yields approximately(6.906667,121.360001,8.88).
- Changing support/collision/integration modes during37C does not rerun preceding
branches or stop the support function's final supported=true publication.
The native payload cases verify each item. They do not execute Jimmy's real37C
(which is an inherited no-op), an animation event or a special Player callback.
They establish generic phase ownership for safe composition.
## Copied-original fixture and verification
`tools/binary/body_modes.py` reuses the existing read-only body/support range and
relocation collector. Generated sources are separated from the Wine work/prefix
under artifacts/body-modes/generated. The probe executes full copied479D20,
47A330 friction and47B890/support queries against the existing synthetic floor.
Its47B4B0 world dispatcher is deliberately substituted: it adds the supplied
movement to the candidate and performs selected synthetic flag mutations.
Angular334 is a simple additive synthetic virtual, not proof of generic angle
normalization. The copied original OMT quick-magnitude export is retained.
No real world traversal, actor, loader/game entrypoint, animation or audio runs.
The final isolated Wine32 run exits0 with BODY_MODES_COMPLETE.87 observations:
64 combinations of integration/support/world/collision/alternate/global geometry;
6 world-mutation cases;11 genuine landing-mutation cases;6 no-clamp/suppression
extras. Source, generator/shared harness/generated EXE/log hashes and all numeric
vectors/counters/event traces are committed in tests/body-modes-reference.json.
The initial landing setup had prior support=true and therefore correctly emitted
no37C; it was corrected to unsupported before using those cases as callback
evidence. A regeneration attempt into the parent directory containing a Wine
prefix was rejected by the symlink guard; separate generated output resolved it.
Only the final87-case run is retained as the committed conformance fixture.
Four Python groups pass: identity/ranges/provenance, all64 branch/counter/context
combinations, callback/suppression observations and generated-output separation.
Run from GamePort:
```
python3 -m unittest discover -s tests -p test_body_modes.py -v
python3 tools/binary/body_modes.py ../Original --generate-probe artifacts/body-modes/new-generated
```
Parent owns managed integration and its conformance claim. Source-world mutation
outputs depend on the synthetic unclipped dispatcher candidate; a real-wall
adapter may compare branch/state invariants without claiming candidateXYZ parity.
All64 flag cases,11 landing payload cases and6 no-clamp/suppression cases permit
full numeric body comparison under the corresponding floor/empty-world fixture.
Contact metadata, root-changing Vec4 publication, special animation/control and
dynamic body eligibility remain independent gates. Whole-original gameplay and
native Windows movement are not established by these component calls.