Files
Neutron/docs/gameplay/grappler-lifecycle.md

133 lines
8.2 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.
# Grappler lifecycle and retained state
2026-11-03. Static source contract, EXE SHA256
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Preferred-base VAs map to raw file offset VA−400000 at the guarded code sites.
Source guards/projection tests are recorded in grappler-camera-live/source.json
and python.log. No original gameplay was executed for this investigation.
## State ownership and reset boundaries
Jimmy complete owns rope+B0C, cursor+B14, companion+A1C and sound handle+1E04.
Raw selected gadget4F0588 and Grappler globals are process storage, not fields
serialized into the TSK inventory. Retained Jimmy is reused by ordinary loads;
its constructor must not be simulated on every scene entry.
| Storage | Fresh Jimmy constructor | Attach | Detach / selected cleanup |
|---|---|---|---|
|attached4F8210|422761→false|426C7F→true|429C28/428810→false|
|anchor index4F82CC, first anchor XYZ4F8214..1C|422767..422782→zero|Current ray hit copied to indexed anchor|No clear|
|first length4F82B4|422796→0|426C24 tests0;426C6B writes current length only on zero sentinel|**Preserved**|
|current length4F82B8|42278C→0|426C1E stores distance−100|Preserved; reel/swing own later updates|
|swingX/Z4F82BC/C0|4227A0/AA→0|426CE2/EC→0|429C7E..CA5 multiply each by float.96|
|elapsed4F82C4|4227B4→0|426D2E→0|Preserved|
|fast target4F82C8|No explicit constructor write; process zero-fill initially|426D4D→anchorY−rootY−200|Preserved|
|complete864 action byte|Not renamed as generic control state|426C85→true|429C2E/428816→false|
|loop34 handle complete1E04|4227CD→−1|Stop old, play new34, save handle|Stop if valid; store−1|
The complete EXE disassembly scan has only two direct writes to first lengthB4:
constructor zero422796 and first-attach assignment426C6B. The inspected retained
Init437890 and full PostLoad423610 route do not repeat that constructor reset;
the global writes in equip/detach/cleanup are bounded above. This supports
retaining B4 across ordinary retained-player loads and re-equips. It does not
establish a disk save/load serialization contract or arbitrary indirect memory
write absence. First attachment's length/600 scales owned rope Z only whenB4=0;
recreating the port visual requires preserving/reconstructing that first scale
as an implementation bridge, not rescaling it from each current length.
Constructor reset is tied to a newly constructed Jimmy, not just a new game
screen. Current length and swing state also survive the listed cleanup paths,
but attach always assigns/reset them. Session storage is appropriate for these
globals; a scene-local active attachment/query reference still needs an explicit
safe boundary in a modern adapter. Such teardown is not evidence that the
original ordinary stage reset attachment.
## Equip, attach, detach and helper visibility
4297DD equip hides the companion via complete58(1), gameD0(0), game214(0)
when present, writes camera locals and raw7. No attach/reset is implicit. The
optional inventory/tutorial menu command9B is a separate branch.
426A70 attachment is reached only after429D00's enclosing aim/blocking gates.
It stops prior +A3C audio, repeats its ray, stores length/anchor/first scale,
sets attached/action, clears jump+7E8 and linked jump effect+6C0, plays one-shot
31 and restarts loop34. It zeros swing scalars/time, preserves velocityXZ,
writes velocityY100, sets fast target, and changes camera fields. The rope's
non-null/resource-visible guard426D85..426D9D calls complete58(0) and records
the visibility-related70 state. The exact owned-resource rendering is separate
from the camera/lifecycle contract.
Held primary while attached reduces length by250*dt only while old length>250,
ensuring loop34; the alternate branch stops that loop. Before raw7 dispatch,
429D5D..429DBB maintains loop34 according to42A7A0 held-primary and attached.
This prelude is not an unconditional loop: it stops a valid handle when the
appropriate predicate fails. Fast reel950*dt and its target test are separate.
Do not combine all sources into a forever-running equipped sound.
429C10 returns immediately if already unattached. Otherwise it clears attached
and action, resets detached camera locals, damps residual swing.96, **sets body
velocity XYZ0**, directly selects FALL, stops loop34 and marks−1, and hides rope
via complete58(1). It does not supply launch velocity, reset first length, clear
movement speed, rewrite jump/movement mode or erase pending impulse. Caller
preparation may do some of those things independently.
Selected cleanup4287AC conditionally restores the companion if its+9E8 gate is
zero: show58(0) only when visibility-related70 is nonzero, then gameD0(1) and
game214(1). It calls detach204, ordinary camera170, clears attached/action again,
hides cursor58(1), and sets raw−1 in common tail428832. The +9E8 guard prevents
unconditional companion visibility restoration. Inactive detach is not an
independent catch-all loop stop; valid source state keeps loop ownership aligned.
The prior independent resource investigation owns exact helper retention/draw.
## SWING is protected from ordinary action requests
The controlled frame calls438A60 then429D00 before later primary426A70. A true
429D00 return ends remaining426030 input only; normal Jimmy437940 still runs.
An attached swing sets logical Euler pitch/roll0 while preserving yaw at429E4A..
429E7C, then requests complete150(`SWING`) at429E84..429E8B before rope/body
constraint work. Ordinary437940's movement/body publication must continue.
Complete150→43AFF0 first compares current action with the requested action and
protected actions. Literal SWING4EF6D8 is checked at43B096..43B0B0; matching
current SWING returns43B597 before RUN/STOP/LEFT/RIGHT conditional changes.
Thus normal437940 requests do not overwrite SWING. Detach uses direct complete
E0(`FALL`,1) and bypasses that conditional action guard. The air jump/FALL path
in437F90 can directly request FALL only for jump modes3/4; attachment already
clears jump mode0. A retained SWING render pose is justified while this contract
holds; it must yield to direct scripted/hit/death action ownership rather than
being a universal per-render override of every action.
## Control and transition events are different boundaries
Source [cutscene-preparation.md](../checkpoint/cutscene-preparation.md) recovers:
| Event | Proven operation affecting Grappler |
|---|---|
|CAM with NULL control|Jimmy438→42AE00→selected cleanup178, then410 speed/velocity preparation, orientation flatten, raw control clear|
|Initial non-none MCA activation|410 first, orientation flatten, then438 selected cleanup and raw clear|
|Later MCA shot|No repeated410/438/raw-clear preparation|
|AI with NULL control|410 and raw clear; **no438 selected cleanup**|
|Raw control owner changes alone|Controlled426030/437940 tail stops; no generic detach follows from that fact|
|RETURN457FF7|Selected cleanup178 before return flags and staging|
|Ordinary LOAD/practice stage43B5A0|No selected cleanup;148→429A00 only stops+A44, distinct from loop34|
|Retained Init/PostLoad|No blanket first-length reset; specific scene/gadget/camera rules remain separate|
410→42AFC0 clears speed/velocity through43A750 and requests conditional STOP.
When SWING is current,43AFF0 can preserve it; do not infer detach from STOP
preparation alone. Menus pause or gate input under their existing phase rules.
Debug noclip is a modern policy, with no source semantics. A chosen noclip/scene
safety detach should be labeled as that adapter boundary and retain proven B4
persistence. Debug force control likewise changes modern effective ownership;
it must not erase already delivered authored selected-cleanup events.
## Remaining questions and claim boundary
The ordinary VR08 lifecycle is sufficiently specified for a bounded live
adapter plus tests for first attach, held reel, jump release, high-contact
detach, reattach, re-equip, CAM/MCA cleanup and RETURN. Save-file serialization
of global first length is not recovered. Whole-original menu/control/render
comparisons, malformed selected/attached/loop combinations and all other
levels' special follow/action policies remain open. These are static facts and
projection checks; managed compilation or VR08 smoke must be reported separately
by the integrating primary, and Windows user testing remains runtime evidence.