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

124 lines
7.6 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 aim, constraint and contact checkpoint
Historical component checkpoint; liveVR08 integration now supersedes its pending
gates. See [Grappler live status](grappler-live.md) for current scope and tests.
2026-11-03. Continues [scalar checkpoint](grappler-component.md). Adds a bounded
VR08 ray/material adapter and isolated aim/rope-constraint/post-base contact
implementation. **Grappler is not enabled in live gameplay yet.** The next gates
are shared body collision state, camera and helper presentation/lifetime.
## Corrected active-input ownership
The attachment leaf426A70 accepts a ray hit without repeating the cursor filter.
That does not mean ordinary input can attach to every hidden-cursor surface:
- 426084 calls438A60 input, then426098 calls complete188→429D00.
- 42609E tests AL;4260A0 branches to4269C3 on true.4269C3..4269CD is a direct
epilogue/return, before later primary1C0→426A70 at4266C8.
- Aim distance<450 hides the cursor and returns true; rejected material does
the same. Both therefore end the remaining active-input pass. Ordinary Jimmy
normal/frame publication still runs separately, as previously recovered.
- The rejected-material branch42A4F8..42A535 may subtract250*dt when held fire
or consuming Enter46A3E0(13) accepts and old rope length>250. The close-distance
branch does not execute that reeling. Neither adds a final length clamp.
- 42A7A0 already polls Enter among primary inputs; the extra consuming Enter path
is separate and short-circuited when the primary predicate is true. The managed
component receives those predicates; keyboard state consumption belongs to its
future caller, not this pure geometry API.
This corrects the earlier interpretation that cursor rejection could simply be
bypassed by held primary. No live behavior had been connected to that assumption.
GrapplerAim.EndsActiveInput records the enclosing return, rather than only whether
a fire button happened to be held.
## Source evidence and implemented scope
Authoritative EXE f5281076…1aea8 and OMT2.dll3ec41ead…54943 are required by
`tools/binary/grappler_query.py`. Full hashes, each span hash/file offset and the
native generator/executable/log identities are in the committed numeric fixture.
Text file offsets below are VA−400000. Runtime globals are not file offsets.
| Source span, exclusive end | File offset | Contract |
| --- | --- | --- |
|42A406..42A652|2A406|Aim hit/miss, strict450 threshold, selected polygon/material/definition distinction, blocked ranges, cursor point and early return.|
|429EA0..429FA4|29EA0|Anchor minus root+116, X/Z perturbation by swing*dt*30, original DLL quick-magnitude normalization, rope-length constraint and desired root before body clipping.|
|42A69B..42A6F1|2A69B|After base contact, zero swing X/Z; only sqrt(X²+Z²)>60 dispatches detach and sets Jimmy action latch1E25.|
|426030..4260A6,4269C3..4269CD|26030,269C3|Input→aim→true-return gate, separate from later primary helper.|
|42A7A0..42A7D6,46A3E0..46A3FB|2A7A0,6A3E0|Primary held predicate and consuming key-array read.|
Selected polygon global695D54 points to material+4, definition+0C, ID+8; global
5CFC60 holds the hit point. Missing polygon or definition passes the material
gate; present polygon without a material blocks. IDs60..69,80..89,210..219,−1,170
block. Visible cursor position uses hit−100*normalized(full ray), not normalized
hit offset. Normalization uses the original quantized quick_magnitude.
VR08 constructor's game table4D00D0 has slot134 at4D0204→475CD0, whose exact
bytes32C0C21800 return false while popping its24-byte arguments. Therefore the
existing NC/checkpoint admission and wall-first/grid/FIFO query are valid there.
Actual VR08 has240 polygons and only collision material IDs0/2/3/4, all ordinary.
GrapplerRay rejects other levels/profiles instead of inventing material context.
It queries the actual root and full-Euler local(0,2400,2400), not root+116.
OriginalCameraRay.TraceSelectedGeometry captures hit plus original polygon
metadata together. It uses the existing traversal and is independent of the
modern camera query toggle. Camera-only disabling must not disable gadget rays.
Tests retain a farther first-hit blocked material instead of silently selecting a
nearer allowed material. No global source state is manufactured from cursor art.
The source constraint stores normalized X/Y before scaling, while Z retains its
unrounded intermediate. Managed code preserves that order with double arithmetic;
general x87 identity remains unclaimed. Zero-vector normalization is explicitly
outside the finite modern component boundary (the source produces nonfinite
geometry); it is not silently repaired with a new position.
## Original-code and port verification
`grappler_query_probe.c` copies three bounded EXE slices into private memory,
relocates whitelisted operands, calls our copied original DLL quick_magnitude,
and supplies synthetic ray/material/cursor/primary/detach accessors. It never
runs the game entrypoint, actual world ray traversal, body dispatcher, base
contact43AA40, camera, rope renderer or full detach lifecycle. The constraint
exits before47B4B0; impact starts after43AA40. These bounds matter.
42 observations complete in the isolated copied Wine32 environment with no
network or Original mount:23 aim,10 constraint and9 post-base impact cases.
Combined with the previous30 scalar observations,72 copied-original observations are
checked by10 managed groups. New vector tolerance is.004 units (including large
coordinates); scalar checkpoint retains.0002. Flags and owner/gate states compare
exactly. The actual VR08 authored start yields two cardinal aiming hits with
retained material identities. No original gameplay/render comparison is claimed.
18 Python Grappler source/projection/evidence groups,11 existing camera groups,
13 Rocketship groups and main .NET10 build pass. Final two-frame lab gameplay
readback is byte-identical to the prior corrected-camera baseline. Actual VR08
geometry preview also renders two frames; both runs enable Vulkan validation and
report zero errors.539 original files verify unchanged. No new gameplay package
was needed; playable packages remain70cba65.
Logs: artifacts/grappler-query/{probe/wine.log,probe/capture.json,managed-final.log,
python.log,camera.log,rocketship.log,build-final.log,gameplay.log,vr08.log,
originals.log}. One synthetic first-hit test initially used the opposite of the
source winding; its failed log is retained and the fixture winding was corrected.
The first leaf guard expected a plain return, then was corrected to the actual
stdcall24-byte return before importing references.
REA's existing47C210 evidence
ev_ff5aab3bdc275e6626753743a3567a556f698209ad9f65689cf49a4b5f56107d
and43AA40/47B4B0 evidence in grappler-component.md remain supporting static
records. A new local REA/Ghidra426030 pseudocode query was not recognized; the
complete error/export/closed snapshot are retained in
artifacts/grappler-live/rea-input/. No repeated selector/config repair or
successful pseudocode is claimed. Exact guarded caller bytes plus the copied
aim execution establish the early-return correction.
## Next integration
Carry the original shared sphere/selected-contact context across ordinary
physics and the attached47B4B0 call, including42A660→43AA40. Do not treat the
post-base contact suffix alone as full collision integration. Then finish helper
rope/cursor material/transforms, follow-camera fields and equip/detach/control
loss/RETURN persistence. The cursor's retainedsprites Canv8 is already exported
for Baseball; rope HIROPE→rope01.ASE still needs a verified runtime binding.
Only then enable boundedVR08 with input-driven attach/reel/swing/detach checks.