Files
Neutron/docs/gameplay/jimmy-air-target-state.md
T

156 lines
9.8 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 air targets: owners, initialization and mode transitions
2026-11-05. Original EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
This closes the state boundary needed to integrate the
[twelve original air destination writes](jimmy-air-motion.md). It adds static
source/data verification, not another original runtime capture. JN-Engine's
saved original index was a navigation aid; its tuned movement is not used.
REA's retained complete instruction Evidence is
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`,
artifacts/jimmy-movement-audit/rea-original-disassembly.json. No unchanged failed
Ghidra selector was repeated. Focused extracts and the source report are under
artifacts/jimmy-air-target-state/. Preferred EXE VA maps to file offset VA−400000;
the helper independently uses PE sections and guards every listed anchor.
## Distinct state owners
Jimmy's game interface is complete object+C0. These are **data offsets**, not
same-numbered virtual slots:
| State | Game-interface data / complete data | Owner |
|---|---|---|
|Current Euler|224/228/22C /2E4/2E8/2EC|330→472420 sets XYZ;334→458F90→472480 adds Euler.|
|Destination Euler|274/278/27C /334/338/33C|36C→472660 writes all three axes and sets dirty byte+A.|
|Facing enabled/dirty|5/A /C5/CA|Init enables5, clearsA; source facing reads both; input destination writes setA.|
|Air forward/back pitch seeds|72C/730 /7EC/7F0|Constructor and movement apply callbacks, not input or current support.|
|Other yaw scalar|61C /6DC|Constructor0; Jimmy Init captures current yaw. No other direct access appears in the bounded437290..43B820 controller search.|
The last scalar is **not** the destination yaw captured by the ground probe.
`jimmy_ground_motion_probe.c` explicitly captures game+278 after its synthetic36C
writer. `JimmyGroundState.TargetYaw` therefore models retained destinationEuler.Y;
ordinary air input replacing that destination Y is expected. There is no evidence
for adding an independently consumed ground-yaw accumulator merely because Init
writes61C. The bounded direct-access search is not a whole-program proof that
61C is globally unused.
### Input publication
- Ground43915D..4395CF calls36C only when an accepted active heading path reaches
43957C,439599 or4395C9 (offset3957C/39599/395C9). It writes `(0,heading,0)`;
accepted Up/Down without a turn uses current yaw. Neutral leaves destination
Euler and dirty state alone. Backward acceptance is resolved before this suffix.
- Ground apply437C40..437F7F has no36C call or direct61C/6DC read. It does not
copy a saved ground yaw into the destination each pass. Its independent334
yaw addition does not become a destination write.
- Air input439A7A/439A80 clears accepted throttle6E4 and brake6E5, then sets them
in the accepted branches439AF2/439C29. In the bounded zero-mouse/analog case,
Up accepts throttle; Down accepts brake; mode2 additionally accepts primary fire
as throttle. Target publication reads these accepted flags, not speed>0.
- Ordinary target branch439DB7..439E33 (offset39DB7..39E33) chooses forward pitch
seed first, backward seed second, otherwise0; yaw=currentEuler.Y;
roll=−storedTurn. Both arrows select forward pitch even though both affect the
speed arithmetic. Mode2's preceding439CFx..439D7C branch uses roll=−.25*turn
(constant4AFD2C, fileAFD2C), with the same seed selection.
- Shared36C dispatch439E2D→472660 writes targets even when neutral or equal to
current Euler. Its setter stores274/278/27C at472668/472672/472678 and sets
dirty+A=1 at47267E. The existing12 native observations cover ordinary targets;
mode2 roll/first-tick sequencing here is statically recovered.
## Lifecycle and phase order
| Event / original VA (file offset) | Result |
|---|---|
|Constructor437445/43744F (37445/3744F)|Complete7EC=−40,7F0=+10.|
|Ordinary apply437FBC/437FC6 (37FBC/37FC6)|Reassert complete7EC=−40,7F0=+10 before composing ordinary air velocity.|
|Bubble apply43880A/438814 (3880A/38814)|Reassert complete7EC=−10,7F0=+10 before Bubble velocity/bounce.|
|Bubble cleanup428037..4280CC (28037..280CC)|If owned effect exists, mode7C4=0, maximum650, radius60/factor1.265 and effect/sound cleanup. No pitch-seed or destination-Euler reset appears in this resolved branch.|
|Generic Init4709CA/9D0/9D6 (709CA/709D0/709D6)|Clear destination XYZ.4709E2 enables facing5;4709E6 clears dirtyA. This is not a current-Euler zeroing policy.|
|Jimmy Init437890..4378CC (37890..378CC)|Calls4587F0→470540, clears speed/turn/published scalar, copies current yaw to61C. It does not re-seed7EC/7F0.|
|PostLoad4239E6 (239E6)|Copy the selected STRT's full authored rotation through174→4716D0. That setter copies authoredFC/100/104 and calls330→472420 to publish currentXYZ. Target Euler/dirty are not modified by this leaf chain.|
|Control preparation42AFC0→43A750|Clears speed/body XYZ velocity and stops sound, then requests STOP. It is not a destination/facing reset or evidence that all current Euler axes become0.|
Route property extraction does not reconstruct the object or re-run its
constructor: see [retained property stream](../checkpoint/retained-streamer.md).
Its verified20 descriptors do not point at game72C/730. The closed generic Init,
PostLoad and no-selected-gadget/jetpack cleanup route therefore retain these
pitch seeds while resetting destination Euler/dirty independently. This is the
bounded LV1B→VR04→LV1B→LEV1 contract, not arbitrary selected gadget/level cleanup.
Original save files do not gain these process fields; current R reset remains
an explicit modern debug policy and can restore constructor seeds.
The existing original registry/partial-order findings imply these concrete
transition cases; the joint sequence has not been newly executed here:
1. First Bubble activation on a fresh input-before-player tick may read the prior
−40 seed. Its later Bubble apply publishes−10, so subsequent Bubble input reads
−10. Retained player-before-input order seeds−10 before that first input.
2. Bubble cleanup leaves−10. Ground mode itself does not re-seed it. A subsequent
input already dispatched in ordinary air mode may read−10 until ordinary air
apply reasserts−40. Do not choose pitch solely from the current mode at input.
3. During a retained ordinary scene load, preserve the seed fields but initialize
targetEuler=(0,0,0), enabled=true, dirty=false. Reapply authored/current Euler
and subsequent destination writes through their own owners.
## Facing and control
43796A calls40E050→462520→473240 before the raw controlled-pointer check at
437A1B.47328D dispatches3D8→43A420. Facing itself checks global475CA0, game byte5
enabled and byteA dirty at43A426/43A433/43A43E; it does not query raw control.
475CA0's global pause/gameplay policy is not the controlled-player identity.
After accepting the gates,43A44F clearsA, then each unequal **before-step**
current/target component setsA again. Its comparisons are direct float equality,
before shortest-arc conversion/interpolation. It then calls334 even if all axes
were equal. A caller reproducing state needs to set `dirty = oldEuler != target`
when the facing callback actually runs; testing equality only after interpolation
can change that final pass. If a gate rejects the callback, dirty survives.
Canonical360 vs0 may remain unequal even when their angular delta is0. Direct
330 current-Euler writes do not synthesize dirty state or replace destinations.
## Initial current Euler is data, not target defaults
The source PostLoad copies full STRT XYZ. Default route GAM data nevertheless
supports keeping the present upright baseline:
| Original GAM / selected default STRT | Authored/current rotation after the resolved setter |
|---|---|
|level1b.gam /STARTEXP|(0,155,0)|
|VR04.gam /PHONEBOOTH|(0,290,0)|
|level1.gam /PHONEBOOTH|(0,220,0)|
The read-only helper records each GAM SHA256 and JIM1/STRT record offsets.
Arbitrary `--start` selections or authored script rotation with nonzero X/Z need
fullXYZ current publication; no source flattening is inferred from targetInit0.
RETURN restores a separate saved root, not a saved rotation; the selected STRT
rotation and its callback chain still apply. Other body/model animation offsets
belong to the render-transform investigation, not this Euler state report.
## Implementation contract and verification
Parent owns live implementation. Retain forward/back pitch seeds as fields,
seed them in apply callbacks, and read them at input time. Store current Euler,
destination Euler and facing enabled/dirty independently. Ground helpers' existing
destinationY state can remain a view of destinationEuler.Y; no extra6DC owner is
needed by proven ground math. Preserve source phase order, support/input gates,
and the explicit modern reset boundary. Full actor-root/model placement must be
handled by the sibling render bridge before enabling ordinary pitch visually.
`tools/binary/jimmy_air_target_state.py` guards32 source anchors,9 virtual targets,
11 bounded instruction ranges, the registered route descriptor boundary and
selected STRT data. Optional `--rea-disassembly` validates retained REA identity
and emits the bounded61C/6DC access and ground-apply call lists. Three Python
groups pass with exact source/offset/binding, separate target/current/default
route data and apply-owned seed checks. Run:
```
python3 -m unittest discover -s tests -p test_jimmy_air_target_state.py -v
python3 tools/binary/jimmy_air_target_state.py ../Original --rea-disassembly artifacts/jimmy-movement-audit/rea-original-disassembly.json
```
Confidence is high for the guarded local contracts and route data. Full original
frame execution, unsupported modes/gadgets, other selected starts/levels, original
cadence, complete animation-root rendering and native Windows comparison remain
separate. No shared runtime or existing evidence fixture was changed here.