Files
Neutron/docs/gameplay/grappler-camera.md
T

126 lines
6.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.
# Grappler follow camera: local fields, consumers and live adapter
2026-11-03. Static recovery against Neutron.exe SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Originals remain untouched. All VAs below have PE file offset VA−400000 at
the guarded sites. `tools/binary/grappler_camera.py` emits actual mapped offsets,
span hashes, virtual targets and constants to
`artifacts/grappler-camera-live/source.json`. Its twelve tests exercise a bounded
Python projection, not original game execution or a live camera comparison.
## State writers are not camera poses
Jimmy complete+7C8/7CC/7D0 stores local eye XYZ; +7D8/7DC/7E0 local look XYZ;
+854/858/85C stores follow gains. These fields feed shared viewport eye
+44/48/4C and pitch/yaw +50/52 through the active follow callback. They are not
ready-to-use world coordinates or camera height/distance parameters.
| State / original writer | Eye local | Look local | Stored gains XYZ |
|---|---|---|---|
|Normal defaults437740..43778D, complete170|0,200,−350|0,80,0|1.6,1,1.6|
|Equip42981A..429844|0,50,−350|0,150,80|**Unchanged**|
|Attach426D59..426D7F|X unchanged,400,−650|**Unchanged**|.8,1,.8|
|Attached detach429C34..429C74|0,50,−350|0,130,100|1.6,1,1.6|
|Cleanup4287FC..42880A|Detach then normal defaults|Detach then normal defaults|Normal defaults|
Detach429C10 is a strict no-op when attached4F8210 is already false. Cleanup
still calls437740 in that case. Equip does not clear attachment or first rope
length in its selected branch. Higher-level selection/cleanup order owns those
transitions. Attaching again after detach retains look(0,130,100); equipping
again restores look(0,150,80). Always rebuilding a generic "attached camera"
would erase this observable difference.
## Ordinary walking follow
Complete124→438BC0 uses the normal subpath439625..4398EF when special camera
flag828 is false. The source adjustment complete84C defaults to10 and normal
walking resets it to10 at438CC6 when its enclosing camera/gadget conditions
permit; Grappler raw7 is not the special raw6 exception.
The effective points are:
```
eye = root + fullEulerRotate(eyeX, eyeY − 2*adjustment, eyeZ)
look = root + fullEulerRotate(lookX, lookY + 1.9*adjustment, lookZ)
gain = (storedX, storedY + .2, storedZ)
```
439652 and4396DA invoke game384→472980, the full logical Euler point
transform, using the source negative Z/X/Y table rotation. Thus equipped normal
eyeY is30 and lookY169 at zero rotation; attached eyeY380. Neither is a direct
substitution into the port's existing ordinary hardcoded follow offsets.
439658..439686 caches desired eye at complete804..810. Normal4397B1..4397F8
multiplies each delta by its effective gain, obstacle gain and dt; there is no
final interpolation-factor clamp in this path.
Flag828 can instead choose a different transformed/cached eye and uniform
gains; flag851 selects fixed .2 smoothing independent of the normal branch.
These are explicit excluded branches, not proven absent from every level.
## Ordinary airborne follow
Complete128→439900 captures OLD viewport eye at439E33.439E38..439E6B
passes raw eye locals to complete120→43A5D0. This helper does **not** add120
to Y:120 is a virtual-slot coordinate. At43A5EA it reads logical Euler, then
43A5F0..43A67B uses pitch0, yaw=`AddAxis(logicalYaw, complete6D4)`, and logical
roll. The helper applies the table rotation, reads root310 at43A6FB, and adds
root XYZ. Complete6D4 is the source turning accumulator, not a camera-local Y
offset. Negative yaw addition follows the previously recovered truncation/360
seam from `RocketOrientation.AddAxis`.
439E81..439EAA transforms unadjusted look locals using game384 full Euler.
For ordinary movement mode other than2,43A03C..43A06C uses **fixed**
gains(1.2,2,1.2), multiplied by obstacle gain and dt. It never reads stored
854..85C there. Attached air therefore uses eyeY400, with look150/80 on first
attach or130/100 after detach/reattach. Body pitch affects the look but not air
eye pitch; body roll affects both. Turn accumulator affects only air eye yaw.
Movement mode2 has separate Bubble gains and flag851 still selects its special
.2 branch. Do not claim these ordinary Grappler formulas cover those branches.
## Shared obstruction and old-eye orientation
Both paths call complete16C→43B820 after computing points. Its caller supplies
look by value and desired eye by pointer; the two preliminary actor310 reads
are not additional point offsets.47C210(false) traces look→eye with original
static grid/order/filter semantics. On hit43B884..43B8F4 writes:
```
desiredEye = look − .75*(look − hit) = .25*look + .75*hit
obstacleGain = 1.5 # miss returns1
newEye = oldEye + (desiredEye − oldEye) * gain * obstacleGain * dt
aim = look − oldEye # deliberately NOT look − newEye
```
Walking captures old eye in complete714/718/71C before this path and uses it
at439830..439865. Air captures old eye in locals and uses it at43A09F..43A0CE.
OMT vector `angles` IAT48D108 yields signed14-bit orientation; subsequent
viewport delta arithmetic gives the new quantized pitch/yaw. Reusing the Rocket
orientation helper is justified; using its gain2 obstacle callback instead of
the Jimmy gain1.5 is not. See [camera-ray-predicate.md](../checkpoint/camera-ray-predicate.md)
for the independently recovered obstruction query.
## Adapter recommendation and verification boundary
Keep a small mutable source-local camera state with the exact writers above.
For bounded VR08, dispatch ground versus air with the stored movement-mode
decision recovered in438A60, then use full source transforms and one source
camera ray. Preserve shared viewport history and compute aim from old eye.
Do not use support alone to pick a camera branch, reset look on each attach,
apply stored gains to air, or post-correct with a second collision query.
Resetting camera state at a reconstructed scene boundary must follow the actual
PostLoad/default/control event; the persistent-state report is separate.
REA was used through the existing local launcher on a generated EXE copy.
The first new helper request mistakenly supplied VA as a numeric file offset;
the corrected file offset3A5D0 mapped to43A5D0 but Ghidra12.1.4 had no recognized
procedure there. Both complete failures are retained in
`artifacts/grappler-camera-live/rea-eye*/`. No pseudocode success is claimed and
no unchanged failed request was repeated. Existing successful REA evidence for
437740 is ev_d2502f41c45731b86d4365634fbc6f0d1b3b70d880fd5741275fd36f1d585aa4;
47C210 is ev_ff5aab3bdc275e6626753743a3567a556f698209ad9f65689cf49a4b5f56107d.
Guarded disassembly supplies the missing follow/eye entries.
Unresolved: runtime original-versus-port VR08 camera comparison; flag828/851
transitions outside the bounded normal case; complete scene-entry shared-camera
cache continuity. No new copied-original camera probe was run in this chunk.