Files
Neutron/docs/gameplay/jimmy-turn-animation.md

120 lines
6.9 KiB
Markdown
Raw Permalink 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 grounded turning poses
Recovered 2026-11-05 for restoring turn animation without replacing the recently
recovered movement implementation. All addresses are preferred-base EXE VAs;
the corresponding file offsets below are VA minus `0x400000` for this image.
Original files remain untouched.
## Evidence and confidence
**Recovered static facts:** retained REA original EXE disassembly
`artifacts/jimmy-movement-audit/rea-original-disassembly.json`, evidence
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`;
EXE SHA-256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
`tools/binary/jimmy_turn_animation.py` checks fixed range hashes, source strings,
thresholds and actual ASE identities. JN-Engine's original `C3DJimmy.md` index
was a constructor/resource lead; its replacement movement is not evidence here.
## State owners and selection
Jimmy's complete actor owns signed speed `+0x6C8` and signed short side substate
`+0x82A`; the game interface is complete actor `+0xC0`, so these become `+0x608`
and `+0x76A` inside `437940`.
| Source VA / file offset | Recovered behavior |
| --- | --- |
| `438F6E / 38F6E` | Ground input handler clears complete `82A`. This is an input-phase write, not an unconditional player-update reset. |
| `4391BD / 391BD` | Keyboard Right writes `+1` to `82A`. |
| `439230 / 39230` | Keyboard Left writes `-1`; keyboard Left wins when both directions are held. |
| `437A8C / 37A8C`, `437AA8 / 37AA8` | Jump-held and unsupported cases leave the ordinary grounded selection path. Existing control/global busy gates also precede this path. |
| `437AC9 / 37AC9` | Compare **signed speed** with float **10.0**, stored at `48E5EC / 8E5EC`. Speed `>10` requests `RUN` regardless of side substate. |
| `437B18 / 37B18` | For speed `<=10`, read side substate. Zero proceeds to the existing primary-action/STOP decision. |
| `437B68 / 37B68`, `437B7E / 37B7E` | Side `-1` requests `LEFT` if complete vtable `+15C` predicate is false. |
| `437B85 / 37B85`, `437B91 / 37B91` | Other nonzero side requests `RIGHT` if the same predicate is false. |
| `437B72 / 37B72`, `437B85 / 37B85` | True primary-action predicate suppresses that side pose request, retaining the current action rather than switching to a turn. |
`+15C` binds to `42A7A0 / 2A7A0`: global `4F83E0` makes it false;
otherwise it returns OR of bytes `509834`, `509845`, `509849`, `509AC4`.
Mapping this to the port's ordinary Fire input is a scoped implementation
interpretation, not a claim that every original input source is now reproduced.
Ground input also writes `82A` for analog/mouse and camera-timer paths at
`439021`, `43904C`, `43907D`, `4390AD`, `439104`, `43914C`. Restoring keyboard
turn animation need not add or retune these movement paths. Preserve the field
across the project's already recovered input/player ordering; clearing it in a
pose getter would destroy the source state relationship.
## Animation request versus acceptance
Complete vtable `+150` binds to the Jimmy animation selector `43AFF0`; requests
above are not unconditional playback switches.
* `43AFF8–43B00E / 3AFF8–3B00E`: compare requested/current logical animation name;
the identical-name case returns at `43B597`, preserving animation time.
* `43B273–43B284 / 3B273–3B284`: compare complete signed speed `6C8` with zero.
X87 C0 test branches to `43B597` for negative speed (also unordered), before
STOP/FALL/LEFT/RIGHT handling. **Backpedal therefore must keep BACK precedence**
even when `437940` would otherwise request a turn. Explicit BACK handling is
earlier at `43B227–43B270`.
* `43B32A–43B375 / 3B32A–3B375`: LEFT request calls action helper `+148`, then
generic start `+E0(LEFT,1)` at `43B351`, and clears body acceleration XYZ.
* `43B378–43B3C3 / 3B378–3B3C3`: RIGHT mirrors it, generic start at `43B39F`.
The start argument **1** is directly observed, also used for RUN and BACK.
Looping these sustained poses in the existing port player is the bounded
interpretation. Full original generic animation frame/end semantics and special
HIT/SPLAT/FENCE/LADDER guards are outside this small restoration; do not replace
the complete animation selector with a newly invented priority table.
## Resources and playback contract
Constructor `422AC0` registers `HILEFT` with `jimleft.ase` through pushes
`422B42 / 22B42` and `422B47 / 22B47`; the corresponding RIGHT registration is
`422B56 / 22B56` and `422B5B / 22B5B`. Strings live at `4EF250`, `4EF248`,
`4EF238`, `4EF230`. Generic animation start `40DD90` prefixes logical names
with `HI` in the high-detail path (`40DE95`, HI string `4ED3DC`), producing the
registered identifiers. Low-detail prefix is `LOW`, not `LO`.
Both supplied turn ASE files contain one `01jimmy` mesh, **6 samples**, times
`0,480,960,1440,1920,2400`, **10 fps**, **480 ticks/frame**, and **426 vertices**
per sample. They have 814 faces but no UVs; extract with textured `jimstop.ase`
as the morph base, retaining its face/UV topology as existing morph extraction
already does. This is not a separate skeletal animation or a yaw transform.
Implementation contract for ordinary controlled grounded movement:
1. Retain the source side substate as input state, Left `-1`, Right `+1`, zero
on each actual ground-input call; retain state between phases.
2. Existing jump/air/control/action ownership keeps precedence. Keep BACK for
negative travel. Positive speed above 10 keeps RUN.
3. At nonnegative speed up to 10, side state selects matching LEFT/RIGHT unless
primary action owns the request. Zero direction follows existing idle/action.
4. Load `jimleft` and `jimright` with `jimstop` topology, loop through the existing
morph player, and avoid restarting the same clip on every update.
5. Do not change physical yaw, body target, acceleration, jump or jetpack rules
merely to make the clips appear. The current turn-only keyboard behavior
reaches speed zero after its existing acceleration/coast logic; forward plus
turn normally exceeds the RUN threshold.
## Implementation and verification boundary
Before this restoration, `LabSimulation.Pose` had no turn poses, the preview
library had no LEFT/RIGHT mapping, and the preparation default omitted both
files. Parent integration owns those runtime/extractor changes and their C#
regressions. This investigation changes no gameplay code.
The helper validates immutable original identity and static evidence, and parses
the real turn ASEs. It does **not** run original code, launch the original game,
or claim Linux/Windows visual verification. Runtime checks should cover idle
turn/release, both directions, forward+turn RUN, backpedal+turn BACK, jump/air
priority, action suppression, repeated-pose time continuity, and an actual scene
view. Remaining questions: source generic playback timing/end behavior and all
special-action interactions beyond this bounded ordinary pose restoration.
Reproduce the evidence guard from `GamePort/`:
```sh
python3 tools/binary/jimmy_turn_animation.py ../Original
```