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

6.8 KiB
Raw Blame History

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 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.