Files
Neutron/docs/gameplay/grappler.md
T

132 lines
8.7 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 source contract and integration gate
Continuation: [scalar implementation and30 copied-original cases](grappler-component.md).
The component remains isolated; live ray/body/camera/helper gates below still apply.
Later [aim/constraint checkpoint](grappler-query.md) proves the enclosing input
gate:429D00 returning true prevents later primary attachment dispatch. The leaf
helper's lack of duplicate material checks must not be read as a bypass.
2026-11-03. Item7/raw7, using the supplied target6 decompiler bodies as leads,
then independently reading the hashed EXE instructions. No friend gameplay code
imported. Static recovery and twelve Python source/projection tests only: no live
Grappler, original gameplay execution or Windows validation is claimed.
## Identity, REA and guarded evidence
Neutron.exe SHA256 is `f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
All addresses below are preferred-base EXE virtual addresses; for these text spans
the file offset is VA−400000. `tools/binary/grappler.py` guards twelve spans,
three virtuals, two dispatch entries, sixteen constants and four strings;
`artifacts/grappler-contract/source.json` records each exact offset/hash.
REA6.8.0/Ghidra12.1.4 with project launcher/profile
`e1ad533d4cc0333c2136fe0894217de2d61feea098240326e78633f9e4ddcbf9`
decompiled jump predicate42A730, Evidence
`ev_4c43cfa8fa5d66c31111d49510aba391f069b446160a448c5544ea042dd452c4`.
Complete replies/export/snapshot are in
`artifacts/grappler-contract/rea-trajectory-20261103/`.
426A70's VA selector failed fallback file mapping; corrected offsets26A70,
29D00 and29C10 mapped correctly but have no recognized procedures in this
default Ghidra analysis. Those explicit errors are retained separately under
`rea-trajectory-offset-20261103/`; no identical retry followed. The older
`rea-controller/` attempt had an IPC denial. This run used the permitted local
Unix socket access and closed both owned sessions. No REA/config repair occurred.
Supporting decompilation is `../../../jn-engine-master/docs/decomp/evidence/
c3djimmy_target6.md`, helpers426A70/429D00/429C10. Its forced `__thiscall`,
`unaff_retaddr` and uninitialized aliases are not ABI proof. Byte-guarded objdump
and known game-interface helpers establish the contracts below; full-Euler/x87
and body execution still need separate references.
## Owners and fields
Jimmy complete pointer owns game interface+C0. Complete vtable4A3BDC has
188→429D00 (swing/aim),1C0→426A70 (held primary),204→429C10 (detach).
These offsets are distinct from movement mode complete+7C4.
| Owner | State and evidence |
|---|---|
| Jimmy complete+B0C | Owned C3DGraplingHook: ctor41EEB0 called422800, pointer stored422810, named at422821..82C; not a nearest serialized hook actor |
| Jimmy complete+B14 | Owned C3DTargetCursor: ctor4453B0 called42255B, stored42256B, named/hidden42257C..59D |
| Jimmy complete+A1C | Companion hidden and movement/collision disabled on equip/attach; cleanup restores only under its own9E8/visibility gates |
| Jimmy complete+1E04 | Loop34 audio handle;−1 sentinel; also touched by pre-mode-check swing helper |
| Globals4F8210/4F82CC | Attached byte / signed16 anchor index; constructor422761/767 initializes zero |
| Global4F8214+index*16 | Float4 anchor, copied from ray hit5CFC60 at426BA7..BD6; no tagged target search |
| Globals4F82B4/B8 | First rope length/current rope length; constructor zeroes both; first-length/scaling write only when B4==0 |
| Globals4F82BC/C0/C4/C8 | Horizontal swing scalars, elapsed damping time, fast-reel target |
| Jimmy complete+864 | Set on attach, cleared detach/cleanup; retain as an action flag until inherited consumers are fully recovered |
| Jimmy complete+7C8..7E0,854..85C | Follow eye/target and smoothing fields changed during equip/attach/detach |
Constructor zeroes the first anchor XYZ and scalars at42276E..7BE. Neither
guarded detach nor raw7 cleanup clears first lengthB4. Full helper persistence
through retained level loads remains a separate lifetime question. The indexed
region permits multiple slots by address arithmetic; do not invent a wrapping
rope/anchor stack: the bounded EXE references inspected show initialization and
reads of index, with no proven advancing writer.
## Input/update and state transitions
426030 receives Jimmy's game interface. After modal/game/control gates it runs
438A60 input then complete188→429D00 at426098; a true result ends Jimmy's active
controller pass. Held primary later reaches1C0→426A70 at4266C8 before the common
energy helper1C4 at4266DB. Thus Grappler attachment has no local energy charge and
precedes that shared zero-energy reject. Do not add an energy cost from menu index.
- **Equip:** jump-table4298E8 slot8 selects4297DD; hide/disable companion,
follow eye(0,50,−350), target(0,150,80), raw mode7. Optional inventory/menu
tutorial command9B remains its own branch.
- **Aim:** 429D00 samples root+Y116. After mode7's fast reel and optional jump
detach, its end portion performs a geometry ray from current root to full-Euler
local point(0,2400,2400), helper47C210. Distance<450 hides cursor and returns
true. Selected-polygon material IDs60..69,80..89,210..219,−1,170 also hide/block.
Polygon without material blocks; material without definition passes this test;
absent selected polygon passes it. A valid cursor is placed100 back from the
hit along ray direction. This is not a query for the nearest3GRA entity.
Its true return at close/rejected surfaces ends426030 before primary dispatch;
rejected-material held fire/consuming Enter may still reel the existing length.
- **Attach / held primary:**426A70 returns false outside raw7; otherwise consumes
primary even on a miss. While unattached it stops+A3C, repeats the root/local
point ray, stores hit anchor, sets current length=distance(root,hit)−100.
If B4==0, scale rope Z by length/600 and preserve first length. Set attached
byte and+864, reset jump word+7E8 and linked jump effect+6C0, emitSFX31, restart
loop34, clear horizontal swing/time, preserve velocityX/Z but setY100.
Fast-reel target=anchorY−rootY−200; eyeY400/Z−650, smoothing(.8,1,.8).
- **Reel:** when already attached and old length>250, subtract250*dt and ensure
loop34. Otherwise stop loop34. There is **no final250 clamp**. Swing helper
independently subtracts950*dt when target<current length, also without clamp.
- **Swing:** root+Y116 is constrained to length from anchor, perturbed by horizontal
scalars*dt*30. Proposed displacement passes through source body47B4B0 before
writing root314; velocityY is then cleared. SetSWING. Update scalars by
−constrained rope offsetX/Z*dt*.17 (stack0C/14, not body displacement64/6C).
At elapsed>=double.2, clamp each±50, multiply .95 when
length<350 else .98, then subtract float.2 **once**, not in a while loop.
Rope model orientation/placement and a separate shadow down-ray are also owned
here. This depends on full Euler/table math and body/camera shared context.
- **Detach:** independent jump predicate42A730 with attached and no held fire
calls204→429C10. Clear attachment/+864, restore eye(0,50,−350), target(0,130,100)
and smoothing(1.6,1,1.6). Multiply swing globals by.96 but **set body velocity
to(0,0,0)**, selectFALL, stop loop34 and hide rope. No invented launch impulse.
- **Collision:** game-interface override42A660 calls base43AA40, clears horizontal
swing and releases if their prior magnitude>60; pointer adjustment−C0 reaches
complete204. Shared collision dispatch/callback ownership remains a live gate.
- **Unequip:** raw7 cleanup4287AC restores eligible companion, detaches, restores
ordinary camera170, clears attached/+864, hides cursor; common tail sets raw−1.
## Implementation boundary and verification
The twelve Python tests verify byte identities, selected-material range edges and
missing-material branches, accepted-hit scalar initialization/reattach retention,
250/950 overshoot behavior, damping threshold/clamp/one-step timing and independent
jump/fire release. Host arithmetic projections explicitly omit x87 intermediate
precision, actual ray traversal, body/camera/actor execution. They do not establish
original runtime parity.
Safe now: use these isolated scalar rules and ownership map as implementation
contracts/tests. **Do not enable live Grappler as nearest-hook/direct pull.** Close
full-Euler ray/filter and selected-material context in VR08; body47B4B0 under
attached state including callback42A660; model/pose placement and shared camera
ownership; fresh/retained helper lifetime and control-loss cleanup. B4's first
length retention and simultaneous jump/fire are necessary regressions. REA's
missing function boundaries could be addressed on a copied analysis project using
the supplied explicit-boundary approach, without blindly trusting forced ABI.