Files
Neutron/docs/analysis/movement-checkpoint.md
T

265 lines
14 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.
# Walking and jump checkpoint evidence
Static investigation, 2026-10-23. Sources: read-only `Original/Neutron.exe`,
`artifacts/binary/neutron.asm`, and the existing RTTI/PE analysis. No original
program was executed for these findings. Recovered instructions are not runtime
verification. Addresses below are executable VAs; for these `.text` ranges the
on-disk file offset is VA minus `0x400000`.
## Pointer and update conventions
`C3DJimmy` has its game interface at complete-object offset `0xC0`. The interface
vtable is `0x4A373C`, complete-object OMT vtable `0x4A3BDC`. Confusing these
pointers changes every field interpretation. Input dispatcher `0x438A60` and
update `0x437940` receive interface pointers; walking `0x438BC0`, ground apply
`0x437C40`, and air apply `0x437F90` receive complete-object pointers.
Relevant interface methods:
| Slot | Target | Meaning recovered here |
|---|---|---|
| `0x218` | `0x458960` | Grounded predicate |
| `0x248` | `0x471AD0` | Friction getter, interface `+0x150` |
| `0x24C` | `0x471AE0` | Friction setter |
| `0x310` | `0x472300` | Current position vector |
| `0x318` | `0x472330` | Set position vector |
| `0x328` | `0x4723F0` | Current Euler rotation |
| `0x334` | `0x458F90` | Add current Euler rotation |
| `0x36C` | `0x472660` | Set destination rotation |
World integration at `0x479EBB–0x479F8D` adds queued impulse to velocity and
clears the queue, adds object acceleration times `dt`, adds global gravity
times `dt`, then obtains the updated velocity for displacement times `dt`.
This is semiimplicit Euler. Game gravity is `(0,-800,0)`, set at `0x44D414`;
the engine initialization value `-5000` is superseded. Exact ordering of input,
rotation interpolation, physics and rendering across the entire frame remains
unverified. A fixed 60 Hz simulation is a port compatibility choice: original
speed increments are per invocation, while displacement and interpolation use
seconds. Original gameplay cadence has not been observed.
The physics support-hit branch `0x479DF7–0x479E54` sets grounded, zeroes
vertical velocity and sets object acceleration to cancel gravity. Because
queued impulses are applied afterward, a takeoff step which still finds
support can receive the full 550 impulse with no net gravity that step,
before airborne acceleration begins. A port's immediate grounded-to-airborne
transition can differ by one tick; do not claim an exact original jump apex.
**Correction from user testing:** mode1 (`0x438B60`) logs and falls through
`0x438B6D` to complete virtual128=`0x439900`, the separate airborne input handler.
The earlier claim that it returned without input was wrong. Normal jumps and
jet pack flight allow Up acceleration, Down braking and Left/Right turn-rate
control. The corrected source arithmetic, regressions and remaining integration
limits are in [air-steering.md](air-steering.md). Ground input remains separate.
## Normal keyboard walking
Constructor `0x437280` initializes complete-object fields `+0x6BC=30` speed
increment, `+0x6C0=35` speed decay, `+0x6C4=600` maximum speed,
`+0x6C8=0` current speed, `+0x6D4=0` extra turn rate. Constructor `0x4373B0`
sets friction to float `0.8` through `0x4711B0`, which forwards via slot
`0x24C`. The subsequent `0.7` at `0x4373C2` is a different property and must
not replace this friction value.
Arrow booleans are `0x50985D` left, `0x50985E` up, `0x50985F` right,
`0x509860` down. Key array starts at `0x509838`, indexed by Windows virtual
key; event setters `0x46A360`/`0x46A380` confirm these arrow indices.
Ignoring mouse/analog input and special gadgets, walking input proceeds in
this order:
1. Down enables the reverse flag at `0x438F9A–0x438FDD`.
2. Left has precedence over Right. Left at `0x43921C` sets yaw delta `+20`
degrees and side contribution `-1000`; Right at `0x4391A7` sets `-20`
and `+1000`. Either adds 30 to speed, capped at 600.
3. Up at `0x4392A9` separately adds 30, capped at 600. Thus Up+Left/Right
increments speed twice per invocation. Up halves any nonzero accumulated
yaw delta at `0x4392CC`; keyboard Up+Left/Right therefore produces
`+10`/`-10` rather than `+20`/`-20` degrees of target offset.
4. If reverse is enabled and the reverse-run flag is clear, subtract
`35*1.5=52.5` from speed, clamped below at `-600*0.5=-300`
(`0x439344–0x43937D`). Up+Down is processed in this order too.
5. If neither Up nor reverse marked the moving flag, decay speed by 35
toward zero (`0x439416–0x43948A`). Turning by itself adds 30 above but
still encounters this decay, because the turn branch sets `+0x6E6`,
not the forward moving flag `+0x6E4`.
6. If a yaw input was supplied, set destination yaw to **current yaw plus
this invocation's delta**, at `0x4395A1–0x4395C9`. It does not repeatedly
accumulate into the previous destination. A pending pushed setter argument
shifts the apparent local stack offset by four bytes here.
Rotation interpolation `0x43A420–0x43A5C2` wraps the yaw error to
`[-180,180]` and adds `error * dt * 3.7` to current yaw. The `3.7` is a
double at `0x4AFCF0`; pitch and roll use `4.5` at `0x4AFD38`. Consequently
held Left/Right alone requests about 74 degrees/s, and Up+Left/Right about
37 degrees/s, before any other turn source. The full interpolator also has
enable/dirty flags, so these formulas describe its active branch.
At zero pitch/roll, forward is `(-sin(yaw), 0, cos(yaw))` and right is
`(cos(yaw),0,sin(yaw))`. Ground apply `0x437CC9–0x437DF0` preserves vertical
velocity and computes:
```text
currentYaw += extraTurnRate * dt
sideSpeed = (extraTurnRate * (1-friction) * speed / 45 + sideContribution) * dt
velocityXZ = forward(currentYaw) * speed + right(currentYaw) * sideSpeed
```
The ordinary keyboard walking path does not assign `extraTurnRate`;
constructor zero is therefore the relevant baseline. Its lateral key term is
still present, e.g. Left at `dt=1/60` contributes about `-16.667` units/s to
local right. Original angle lookup converts float degrees by multiplying
float `45.5111122`, truncating through `0x47F940`, then masking with `0x3FFF`.
It uses 16384-entry float sine/cosine arrays. Continuous host trigonometry
is an approximation to that lookup.
### Reverse-run branch uncertainty
There is a branch when complete `+0x830 > 1.5` at `0x439383` which sets
speed 600, remembers current yaw plus 180 degrees, and sets reverse-run flag
`+0x828`. While that flag remains set, reverse keeps speed 600. Input release
clears the flag. However, the cached full executable disassembly only shows
initialization/reset and reads of this timer in the player code; no increment
was found. The timed transition's reachability is unresolved. Persistent
backpedal capped at -300 is the directly usable baseline. Do not silently add
a hold timer or claim the turnaround runs in the original.
## Basic jump and held-input behavior
Complete field `+0x7C4` is the movement mode (walking 0, air 1, flying 2,
seated 3), while `+0x7E8` is a separate jump state. The outer update
`0x437A7E–0x437C1C` calls air apply while jump is held or while an existing
air mode has not yet landed. A released, grounded player is returned to
walking, and **jump state is reset to 0** at `0x437B9E`
(`interface +0x728 = complete +0x7E8`).
Jump-held predicate `0x4378D0` accepts global right mouse, Insert, Shift,
numpad 0, or controller flag, subject to gadget-6/ground gating. The
previously cited Jimmy helper `0x42A730` is separate; the complete-object
vtable slot `0x158` used by base player here targets `0x4378D0`.
For jump states less than 3, `0x438148–0x43818D` sets additional object
acceleration Y to `gravityY*1.33 - gravityY`. Combined with global gravity,
net acceleration is approximately `-1064` units/s². The factor is float
`1.33000004` at `0x4AFCE4`. Input release from state 1 does not shorten the
impulse or alter this acceleration immediately.
Held dispatch table at `0x4387AC` is:
| State | Target | Effect |
|---|---|---|
| 0 | `0x438379` | If grounded, select `JUMP`, queue `(0,550,0)`, enter 1, clear hold timer `+0x874` |
| 1 | `0x4383FD` | Add `dt` to hold timer; after `>0.4`, run gadget/level checks and enter 3 |
| 2 | `0x438559` | On renewed hold, run gadget/level checks and enter 3 |
| 3 | `0x438693` | On ground contact, stop effect and enter 4 |
| 4 | `0x4387A1` | No action while held |
| 5 | `0x4386FB` | Reset to 0 if grounded |
Released table at `0x4387C4`, indexed by state minus 1, maps 1 to
`0x438732` (enter 2), 2 to no action, 3 to `0x438745` (stop effect, enter
4), 4 to `0x43879A` (grounded resets 0), and 5 to `0x43878C` (same).
The outer grounded-release reset usually handles landing before this table.
State 4 blocks automatic repetition while held. The zero-burn gadget-disabled
path below resets state 3 to 0 sooner and can repeat on landing while held.
### Long hold without an available gadget
Absence of a gadget does **not** leave the jump in state 1. At
`0x43848E–0x4384C8`, profile 0/item 3 state 0 or 4 branches to a path that
sets jump state 3 on every level except `VR04`. This skips the effect/animation
and velocity-Y=10 branch used when the gadget is allowed. `0x403950` retrieves
that profile item state. Initial current gadget is -1 at `0x42225F`.
Crucially, there is an earlier guard at `0x438192–0x43820D`. Complete
`+0x7F8` points to `C3DJetpackFire`, allocated in the player constructor
(`0x4374DF`, stored `0x4374EF`, debug name at `0x4F058C`). Its constructor
`0x421D80` initializes burn time `+0x6C0=0` at `0x421E68`; takeoff also
clears it at `0x438387–0x438391`. If this object exists and burn time is
<=0, states 3 or 4 reset to jump state 0, retain air mode 1, select `FALL`,
and return **before** changing object acceleration. Thus a normal disabled
gadget keeps the prior extra acceleration `-264` and remains ballistic at
net `-1064`, even after a long hold. No powered hover needs to be invented
for that case. If jump is still held when grounded after this state reset,
state 0 can queue another jump. This repeat-on-landing is a static call-path
consequence, awaiting original runtime comparison.
Only a null effect pointer or positive burn time reaches the following
distance-controlled acceleration branch for state >=3
(`0x438210–0x43830D`). For `g=-800`:
| Condition | Additional Y acceleration | Net including gravity |
|---|---:|---:|
| complete `+0x86C <500`, vertical velocity >=-1 | `-g -0.1*g = 880` | 80 |
| complete `+0x86C <500`, vertical velocity <-1 | `-g -0.3*g = 1040` | 240 |
| complete `+0x86C >=500` | `0.1*g-g = 720` | -80 |
`+0x86C` is **not a timer**: `0x425450–0x42547C` writes the distance between
Jimmy and his `C3DShadow` (`complete +0xA2C`). Jimmy constructor `0x42250C`
creates it via `0x43F640`, stores it at `0x42251C`, and names it with the
debug string `C3DShadow` at `0x4EE75C`. Shadow constructor `0x43F775` sets
its height field `+0x5EA` to 30. Update `0x4252E0` queries a vertical segment
from Jimmy root `P` to `P-(0,2500,0)` through `0x47C6E0`; the returned hit at
global `0x5CFC60` supplies the shadow's Y. `0x4253BE–0x42541C` sets shadow
position to `(playerX, hitY+height/2-2, playerZ)`. With default height30 the
distance is therefore `abs(playerRootY-hitY-13)`. Global `0x4F8210 !=0`, a
failed query, or absent shadow leaves the previous distance unchanged.
Ground-distance semantics are directly supported, but the exact original
query filter/surface selection remains unverified.
## Walking follow camera
Default fields at `0x437740` are local eye `(0,200,-350)`, target `(0,80,0)`,
and interpolation coefficients `(1.6,1,1.6)`. Normal nongadget walking sets
complete `+0x84C=10` at `0x438CC6`; camera construction adjusts those to:
```text
desiredEye = transformLocal(0, 200-2*10, -350) = transformLocal(0,180,-350)
lookTarget = transformLocal(0, 80+1.9*10, 0) = transformLocal(0,99,0)
```
Eye construction is `0x439625–0x439652`; target construction
`0x4396A9–0x4396DA`. The factor at `0x4AFCE8` is **double 1.9**.
`0x472980` transforms the local point by actor Euler rotation and position.
Normal interpolation at `0x4397B1–0x4397F1` is:
```text
camera += (desiredEye - previousCamera) * (1.6, 1.2, 1.6) * obstructionFactor * dt
```
The extra 0.2 in Y comes from double `0x4A2AD0`. Unobstructed factor is 1;
`0x43B820` performs a scene ray query, modifies the desired eye if hit, and
returns factor 1.5. The precise obstruction geometry and reverse-run camera
remain unported details. A special flag `+0x851` instead uses 0.2 on every
axis. The ordinary code looks toward the target using the camera position
saved at the start of the handler (`+0x714,+0x718,+0x71C`), then writes the
viewport angles; copying a conventional look-at using the new eye is a small
but real approximation.
## Actor pivot, scale and collider
No reliable original capsule/cylinder dimensions or actor-specific model
translation/scale were recovered in this investigation. Jimmy InitObject's
call with `(0,600,100)` is a **position setter**, slot `0x318`, and supplies
no collider dimensions. Shape-change hook `0x462270` reads the shape bounding
radius and six min/max values, forwarding them to object properties; this
does not establish a capsule radius or the player-specific collision proxy.
Raw standing model bounds, the GAM root placement and the preview sole
correction remain separately documented in existing scene/gameplay findings.
A capsule based on raw mesh width/height and a separate simulation-feet
origin is a port approximation. Neither the observed floor contact nor the
raw bounding box proves an original scale factor or root-to-feet offset.
## Checks and remaining work
Instruction ranges were re-read with bounded `objdump -d -M intel` commands;
float/double constants and jump tables were independently decoded from file
bytes with `tools/binary/pe_inspect.py` and Python `struct`. This caught three
material preliminary errors: key strafe signs, assuming the target yaw
accumulates, and interpreting the look-target multiplier as a float.
Outstanding: original frame phase order/cadence; reverse timer writer;
long-hold jump/repeat comparison; shadow query surface selection; original
collision proxy and shape converter mode-2/pivot behavior. No runtime fidelity
claim follows from the static formulas or a successful port build.