Files
Neutron/docs/gameplay/jimmy-air-motion.md
T

134 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 ordinary airborne movement audit
2026-11-04. User prioritizes stable Jimmy movement and explicitly preserves the
current GamePort feel over JN-Engine's replacement movement. JN-Engine's saved
original decompiler output was used only to locate/interpret original routines;
its C/Godot movement was not used as a behavioral reference. Authoritative source
is the immutable project EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
## Recovered contracts and concrete mismatches
Addresses below are original EXE VAs; independently mapped file offsets equal
VA−400000. `tools/binary/jimmy_air_motion.py` guards source identity, five complete
bounded ranges and decoded absolute relocation operands. Source instruction
extracts are retained in artifacts/jimmy-air-audit/{input,apply}.asm.
| Original VA / offset | Original behavior | Prior port mismatch / bounded correction |
|---|---|---|
|439900..439A69 /39900..39A69|Mode1 keyboard Left precedes Right, changes stored turn by100dt; no-key return toward0 occurs only when complete6E6 keyboard-turn latch is set. Key turning sets latch; mouse turning clears it.|AirSteering always applied return, without storing the latch. JimmyAirMotion.Input owns explicit latch state; caller must retain it and share it with other input modes.|
|439AE6..439B69 /39AE6..39B69|Up adds30 only when scalar<maximum, then clamps. Existing overspeed is preserved.|RecoveredMotion.AddSpeed clamped overspeed down to maximum. New helper preserves it. Ground correction is investigated separately.|
|439B69..439BA2 /39B69..39BA2|Without throttle, coast only above maximum*float.909090936; compare uses the unrounded x87 product. Coast subtracts17.5 per callback.|Float-rounded C# comparison misses a representable threshold case. At max600, speed545.45459 must coast to527.95459. New helper uses double intermediate for the comparison.|
|439BA2..439BED /39BA2..39BED|Independently test body218 support, even with stored air mode1. Supported positive scalar subtracts17.5 with no crossing clamp; nonpositive scalar resets0.|Old AirSteering had no support argument. Supported speed300+Up ends312.5; speed5 with no keys ends−12.5. These affect landing/rejump and retained input phases.|
|439C1D..439CB2 /39C1D..39CB2|Down after throttle/coast/support subtracts35 supported or17.5 airborne, clamps positive scalar to0; negative scalar adds35 toward0.|Old helper used17.5 for positive scalar regardless support. No reverse-flight initiation is added.|
|439D81..439DB7 /39D81..39DB7|Ordinary mode1 turn caps±30, distinct from Bubble's±50.|Existing cap is correct and retained.|
|437FD0..438011 /37FD0..38011|Read incoming live velocity. Exact zero magnitude skips independent yaw AND lateral computation. It still publishes forward scalar afterward.|LabSimulation gated yaw but computed side unconditionally. Zero incoming velocity/scalar300/turn30 produces(0,0,300), not a lateral launch.|
|438011..438062 /38011..38062|For nonzero velocity, call334 AddEuler(0,turn*dt,0), then side=turn*float(1/55)*(1−friction)*scalar, without dt on side.|Existing side formula is generally right but ungated. Plain yaw modulo omitted full-axis AddEuler normalization. New helper reuses original-leaf-compatible RocketOrientation.Add.|
|438062..4380E6 /38062..380E6|Rotate the lateral contribution around current yaw using original OMT table values.|Retain yaw-only lateral contribution. No invented normalization or clamp.|
|4380E6..438124 /380E6..38124|game38C rotates local(0,0,scalar) by full Euler. Sum its X/Z with lateral contribution and preserve incoming Vy, discarding rotated forwardY.|Old port used flat yaw only. Nonzero pitch must scale horizontal forward; roll does not alter this local-forward vector. Use original-compatible rotate/lookup helper.|
The probe complete-object fields are6C8 scalar,6D4 turn,6D8 applied turn,
6BC acceleration step30,6C0 decay35,6C4 maximum600,6E4/6E5 throttle/backward,
6E6 keyboard-turn latch,7C4 movement mode1. Its game interface is complete+C0.
Game Euler is224/228/22C; getVelocity2BC/setVelocity2C4, friction248, support218,
getEuler328, AddEuler334, local-vector transform38C are separate calls. Synthetic
probe binds the last three to original4723F0/472480/472B10. Real class wrapper
334 may add gameplay gates; source publication/controller ownership remain caller
responsibilities and are not reconstructed by this isolated component.
Keyboard steering and scalar increments retain current signs, precedence, source
per-callback30/17.5/35 values and mode1 turn cap. Existing ordinary flat-air
movement with nonzero incoming velocity is preserved. None of these corrections
adopts JN-Engine's tuned jump650/gravity1600 or instant tank movement.
## Native observations and REA
`tests/GamePort.JimmyAirTests/original-air-reference.json` commits35 copied-original
observations and source/generator/shared-map-helper/probe-EXE/output-log hashes:
22 mode1 keyboard input cases and13 velocity-prefix cases. Coverage includes
Up/Down combinations, overspeed, exact coast boundary, supported positive/negative
crossings, turn cap/precedence/latch/return crossing,60Hz, zero/rising/falling live
velocity, slope pitch, roll, Euler seam/negative angle normalization, friction0,
reverse scalar, zero scalar and ordinary60Hz output.
Probe executes copied439900 through439DB7 (before orientation/camera work) and
complete-entry437F90 through438124 (before jump suffix). It supplies synthetic
actor/body/friction/mouse callbacks and uses the copied project's original OMT
trig global plus original Euler helpers. Zero mouse/controller input is explicit.
439900's continuation is replaced by a stack-correct return, and437F90's suffix
is replaced by its original4387A1 epilogue. No original game entrypoint, physics,
collision, camera, animation or audio is executed. Source jump suffix438148 and
effect421FB0 are independent parent investigations.
The isolated Wine32 run exits0 and prints JIMMY_AIR_MOTION_COMPLETE; capture.json
and wine.log are retained in artifacts/jimmy-air-audit/probe. Thirty-five saved
outputs match two managed conformance groups. Two Python groups guard source,
relocations, PE offsets, complete fixture counts and generator provenance. This
is original component execution, not whole-original or native Windows gameplay.
REA/Ghidra12.1.4 was invoked through the configured local scripts/rea.sh on the
generated target copy. The default profile did not recognize439900 as a procedure;
the complete explicit mapped-selector failure, export and closed snapshot are
retained under artifacts/jimmy-air-audit/rea-input. No pseudocode success or
Evidence ID is attributed to that failure, and the unchanged selector was not
repeated. Earlier Bubble movement attempts had provider startup failures and do
not establish successful decompilation either. Supporting source instructions,
whole-source identity and new native observations establish the bounded arithmetic.
JN's docs/decomp/evidence/c3dplayer_movement_target3.md supplied an original-code
reading lead, independently checked against these project originals.
## Integration API and remaining limits
New `JimmyAirMotion` is an isolated source-backed implementation. Parent owns live
integration and existing AirSteering/LabSimulation files:
1. Pass Input(new(Speed,TurnRate,keyboardTurnLatch),input,Grounded,dt,MaximumSpeed).
Retain returned scalar, rate and latch. Complete6E6 is shared with ground and
Bubble input: update it when those source paths set it; do not reset each frame.
2. Call Apply(Speed,TurnRate,new(Pitch,Yaw,Roll),Velocity,dt,friction) in the ordinary
air branch, after existing facing/mode selection and before438148 jump suffix.
Publish returned full Euler and velocity. The incoming velocity gate must use
prior live velocity, not a newly fabricated forward vector.
3. Keep body-first/fresh-vs-retained order, ordinary landing/reset, jump/jetpack
state/effect, raw/effective control and special modes in their existing owners.
This does not implement mouse/controller axes, general camera/pose targets,
reverse-run helper states, complete full-Euler/render root behavior, original
cadence, dynamic/special contacts or the jump state suffix. Fixed60Hz and source
body vs capsule admission remain existing port policies. Ordinary input requires
0<dt<1 because the original divides mouse deltas by dt. Native Windows and
whole-original movement/trajectory comparison remain unverified.
## Destination-Euler follow-up (2026-11-05)
REA's complete retained objdump Evidence
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`
adds the next target write. 439DB7..439E33 (offset39DB7;
range end39E33) reads accepted forward6E4 before backward6E5, writes pitch7EC
or7F0, yaw=currentEulerY and roll=−turn. Neutral pitch is0. Constructor437445/
43744F (offset37445/3744F) initializes7EC=−40,7F0=10; ordinary437FBC/437FC6
reasserts those values. Bubble43880A/438814 substitutes−10/10. These are
retained controller fields, separate from current Euler and destination Euler.
`tools/binary/jimmy_air_targets.py` extends the previous input probe through
439E33, supplying a synthetic36C destination writer. Twelve native observations
are retained in `tests/GamePort.JimmyAirTests/original-air-targets-reference.json`,
including both arrows (Up wins), turn signs, supported zero/overspeed, zero and
custom pitch seeds. Isolated capture exits0 with JIMMY_AIR_TARGETS_COMPLETE;
source range, generator, executable and output hashes are recorded. No camera,
facing interpolation, body or original whole-game entrypoint ran. A Python guard
checks source/provenance and saved writes; this is recovery evidence, not a
managed/runtime implementation claim.
Live ordinary-air pitch targets are deliberately still the baseline simplification.
The source-backed input/velocity helper is integrated, but enabling this target
requires the full Euler/actor-root visual bridge and retained mode-field ownership
to move together. Otherwise horizontal velocity would gain pitch attenuation
while the ordinary rendered Jimmy remains upright. Follow-up must retain source
7EC/7F0 across Bubble→ordinary and fresh/retained callback order, then verify
model pivot, takeoff, turning, landing and route returns. This is an identified
original mismatch, not a recovered behavior that is already live.
Live integration/route/native/package status (2026-11-05): [movement stabilization](jimmy-movement-stabilization.md). The audit API notes above describe the isolated component boundary; parent integration is now recorded in that continuation.