133 lines
8.2 KiB
Markdown
133 lines
8.2 KiB
Markdown
# 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.
|