Files
Neutron/docs/gameplay/jimmy-render-transform.md

115 lines
7.4 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 logical/render Euler and compatible pivot bridge
2026-11-05. This investigates the original transform before enabling ordinary
up/down airborne tilt. The existing playable movement and upright placement are
the baseline. JN-Engine original class/decompiler notes supplied navigation leads;
its tuned movement and renderer are not copied as behavior references.
## Original facts and state ownership
Authoritative identities are EXE
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`
and OMT2.dll
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
`tools/binary/jimmy_model_bridge.py` guards their ranges, five Jimmy bindings and
both double angle constants. File offsets below are independently PE-mapped.
| VA / file offset | Recovered contract |
|---|---|
|EXE4624B0 /624B0|Jimmy game-interface3DC asks310→472300 for the current logical/body Vec4; copies XYZ to complete44/48/4C without scale or floor/sole subtraction.|
|EXE4624F0 /624F0|Angle publication hook3E0 jumps to473540.|
|EXE473540 /73540|Reads current degree Euler through328→4723F0; each axis is remainder360, multiplied by **double**45.51111111111111 at4D6408 and truncated through47F940, then masked16383. Double360 is4D6410.|
|EXE462500 /62500|Game3E4 stores the three resulting shorts at interface−70/−6E/−6C = complete50/52/54. Position and cached render angles are distinct records.|
|DLL1003FA60 /3FA60|OMediaElement::compute_hxform copies the parent hierarchy; obtains current animation dynamic offset from virtual7C and adds complete44/48/4C. With identity parent, resulting translation is exactly root+dynamic offset. Rotation does not rotate that root.|
|DLL1003FB26..1003FBE3 /3FB26..3FBE3|Reads cached angle shorts52/50/54 with negative signs and rotates the hierarchical basis. Row-vector form is Rz(−roll)·Rx(−pitch)·Ry(−yaw), with unit scale in the probed path.|
|DLL1003FC00 /3FC00|compute_model_matrix consumes the hierarchy and decomposes/re-quantizes its rotation through original angle lookup before publishing the final4×4. This additional precision behavior is distinct from the hierarchical basis.|
473540 does **not** duplicate Y into X: the0C stack load at473586 reads Y, then
pushZ at473595 shifts the stack. The0C load at4735A6 consequently reads original
X. Native asymmetric(-40,45,-15)→(14564,2048,15702) confirms independent axes.
The double render conversion is kept separate from physics472B10's float
45.5111122 factor. Render caching is not permission to mutate current degree
Euler or its destination state. Their phase/state owners remain in LabSimulation.
The position bridge has no hardcoded radius75.9, standing-minimum offset or scale.
Prior mode2 DLL import probes establish original jimstop geometry and zero dynamic
frame offsets for the tested clips; see [original collision](../analysis/original-collision.md).
That does not certify every clip, shape mutation, hierarchy or transform flag.
There is no newly recovered original correction for the port's sole alignment.
## REA and native evidence
The retained EXE instruction Evidence is
`ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904`
in artifacts/jimmy-movement-audit/rea-original-disassembly.json. The DLL REA
inspect-with-objdump Evidence is
`ev_af082632c98b34ccfcedef01466cafa03365e7fbf482496d01a4cda6d2f8f787`,
retained in artifacts/jimmy-model-bridge/rea-dll-disassembly.json. Its16MiB output
cap was reached, so it is a **bounded prefix**, completion unknown, not complete
DLL analysis. All transform ranges used here are present and separately guarded
against original bytes. An initial REA target-path error was corrected by making
a separate generated DLL copy; no missing-target result is cited as analysis.
The OMT probe calls exported compute_hxform and compute_model_matrix against a
synthetic element, identity parent and zero dynamic-offset callback. Fourteen
cases include upright, individual90° axes, full combined axes, ordinary forward/
backward air tilts, negative units,16383/16384 seams, halfturn, tiny angles and
two roots with the same rotation. No game/renderer entrypoint, GPU, body,
animation or audio runs. The original DLL is loaded only from an isolated copy.
The angle probe executes copied473540, original4723F0 getter and462500 setter
with synthetic actor fields. It bypasses CRT exception dispatch at4802CA into
its original finite x87 remainder primitive4802D4;47F940 truncation is original.
Twelve finite cases cover independent axes, negative/fractional degrees, multiple
revolutions, exact angle units, canonical360 and tiny seams. This does not verify
CRT exceptions, nonfinite inputs or the whole object scheduler.
Both isolated Wine32 runs exit0 with their success markers. First-time Wine prefix
creation exceeded the initial capture window; reuse of an already completed local
analysis prefix resolved setup. Successful model and angle logs/capture metadata
are retained separately under artifacts/jimmy-model-bridge. Fixture
`tests/GamePort.JimmyRenderTests/original-render-reference.json` commits all40
observations (14 hierarchy +14 final render matrices +12 angle writes), source
ranges/constants/bindings and generator/probe-EXE/output hashes.
## Implemented helper and explicit modern policy
`JimmyRenderTransform.AngleUnits` follows the recovered finite degree conversion.
`Source(root,euler)` uses those units and the original hierarchical axis order;
its translation is the unrotated root. `Aligned(root,euler,localYCorrection)`
pre-translates local vertices before that source rotation/root transform.
The helpers are pure and reject nonfinite inputs; no broader renderer or asset
rewriting is introduced.
For baseline upright placement, the caller may retain the fixed modern correction
`c = -modelMinimumY - rootHeight`, then use
`Translate(0,c,0) * Source(ActorRoot,Euler)`. For the standing mesh, minimumY is
approximately−64.6165 and the existing logical clearance is75.9, givingc≈−11.2835.
This preserves the upright sole location while combined pitch/roll rotate around
the logical root. The local point(0,−c,0) stays at ActorRoot under every rotation.
It is a **modern compatibility adapter**, not a recovered original pivot offset,
scale or new body clearance. It must not change collision/body support geometry.
The old world-space sole correction is not evidence for the source transform.
## Tests and remaining gates
The managed suite compares all12 original degree writes and14 hierarchical
transforms (basis tolerance1e−6), unit-scale determinant, unrotated translation,
modern upright/combined-tilt pivot invariants and nonfinite rejection. Two Python
groups verify source ranges/constants/bindings and complete native fixture/
provenance. Commands from GamePort:
```
dotnet run --project tests/GamePort.JimmyRenderTests
python3 -m unittest discover -s tests -p test_jimmy_model_bridge.py
```
Both pass. Final OMT model-matrix parity is deliberately **not** claimed. Its
approximate angle decomposition produces up to0.007286333 matrix-coefficient
deviation in the14 saved cases, largest at the16383-unit near-zero seam; ordinary
combined air tilt differs by roughly0.0002..0.0003. The test records that mismatch
instead of treating the final matrices as conforming. Exact decomposition/lookup,
all render flags/parents/dynamic offsets, complete source pivot/clip ownership and
whole-original/native Windows visual comparison remain separate gates. Runtime
integration/route/native checks are owned by the parent movement continuation.