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

8.2 KiB
Raw Permalink Blame History

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