VR-Mess/HANDOFF.md

# VR Messs — Agent Handoff

Read `AGENTS.md` in the repo root first — it is the authoritative project brain. This file
orients you; AGENTS.md governs. Verify every claim here against the code when you touch it
(code wins over both docs if they disagree).

## 1. What this project is

VR anime-character **scene viewer** — Koikatsu-VR-class, but with real physics hands.
**Not a game**: no loops, quests, progression. Explore, interact, touch, pose — that's the product.
This repo is the experimentation lab: designs are hypotheses validated with cheap throwaway spikes.

TERMINOLOGY (owner-corrected — use precisely):
- **"getting a body"** = the physical rig (torso/arms/hands, the interaction body).
- **"embodying"** = viewing from a character's perspective in an animation (view-follow + avatar).
  Two separate systems. Never call the rig milestone "embodying".

## 2. Toolchain & environment

- **Godot 4.7.2 mono** (binary `godot-mono`), **C# / .NET 8** (dotnet SDK 10 present). PCVR, desktop-only.
- **Physics: Box3D** via `addons/godot-box3d` GDExtension (bearlikelion server-replacement, v0.2.6);
  setting `physics/3d/physics_engine="Box3D Physics"`. Exactly ONE `.gdextension` file may exist —
  a stray duplicate double-loads the library and breaks the server ("required virtual method" errors).
  **The addon is LOCALLY PATCHED** (grab v5.3 depends on it): the wrapper now maps Godot's
  ConeTwistJoint3D → Box3D's b3WeldJoint (rigid grab weld). Originals in `addons/godot-box3d/bin-stock/`;
  source + rebuild recipe + patch in `.vendor/` (`.vendor/box3d-weld.patch`,
  `.vendor/godot-box3d/`, see `research/godot-box3d-weld.md`) — **only the Linux binary is
  patched**; Windows/macOS binaries are stock (ConeTwist still errors there until rebuilt).
  **Second patch (2026-10-02): `Generic6DOFJoint3D` → Box3D ball (spherical, cone/twist limits, torque-capped
  motor = MUSCLE) / weld / drive (motor joint)** — fork branch `generic-6dof-joint`, `.vendor/box3d-generic-6dof.patch`,
  details + C# muscle recipe in `research/godot-box3d-6dof.md`. Spring stiffness/damping are Box3D Hz/ratio.
  Jolt fallback = flip that one project-setting line; all gameplay code stays standard
  RigidBody3D/StaticBody3D/CharacterBody3D so the flip is lossless.
- Runtime stack: **WiVRN + WayVR** on Linux. Headset + runtime support hand tracking (treat as available).
- Renderer **Forward+** (Mobile is the docs' VR recommendation; deferred until profiling justifies).
- Build: `dotnet build`. Headless validation: `godot-mono --headless --fixed-fps 90 --path . scenes/<spike>.tscn`
  (`--fixed-fps 90` runs physics faster than real time at the real 90 Hz tick — the 49-scenario
  collapse spike takes seconds instead of minutes). Spikes and their pass lines:
  `physics_spike` "SPIKE: overall PASS", `weld_spike` "WELD: …", `grab_spike` "GRAB: …",
  `body_spike` "BODY: …", `collapse_spike` "COLLAPSE: …", `arm_spike` "ARM: overall PASS",
  `sixdof_spike` "6DOF: overall PASS" (run FIRST with `weld_spike` whenever the addon binary changes),
  `truebody_spike` "TRUEBODY: overall PASS" (no physics; plain `--headless`). All eight PASS 3× as of this handoff. Headless asset import:
  `godot-mono --headless --import`.
- Engine logs: `~/.local/share/godot/app_userdata/VR Messs/logs/godot.log` — **read after user
  playtests instead of guessing**.
- **Docs rules (project's #1 failure mode)**: only the local pinned 4.7 docs at
  `/home/foxyz/Projects/Games/.shared/godot-docs-4.7` (full manual + class ref in `.rst`; rg it).
  Web fallback only `https://docs.godotengine.org/en/4.7/...` — version goes IN the URL, never `/latest/`.
  NEVER trust training-memory API names. Known traps: `AudioStreamWAV` is `AudioStreamWav` in C#;
  collision layer/mask live on `CollisionObject3D`, NOT `CollisionShape3D`; `SkeletonIK3D` is
  deprecated in 4.7. If docs and compiler disagree, grep the shipped
  `/usr/lib/godot-mono/GodotSharp/Api/Debug/GodotSharp.dll`.

## 3. Current systems (scripts/)

- **Main.cs** — OpenXR startup: finds `OpenXRInterface`, `UseXR`, VSync off, VRS XR mode; wires
  session signals (begun/visible/focussed/stopping/`PoseRecentered` → re-emitted as C# signals
  FocusLost/FocusGained/PoseRecentered). On session begin: picks highest refresh rate ≤
  `MaximumRefreshRate` (export, 90) and sets `Engine.PhysicsTicksPerSecond` to it. Pauses tree on
  focus lost. No OpenXR → flat preview fallback (PushWarning, scene still runs).
- **Locomotion.cs** — locomotion manager. Spawn anchoring ONCE on first `FocusGained` (HMD xz to
  `SpawnPoint` + spawn yaw; real head height and pitch kept — `PlacePlayer` pins arrival height).
  `PoseRecentered` is deliberately IGNORED for placement (WiVRN spams it at ~90 Hz; logged once).
  Teleport: aim + trigger edge, fade to black 0.12 s in / 0.25 s out, near markers within
  `MarkerNearDistance` (1.2 m) hide fully (disc/beam/label) and are not targetable. Lasers via
  `UpdatePointer`: shown only when aiming at something interactive (marker or panel) AND beyond
  `LaserMinDistance` (0.35 m). Also builds the stylus pointer tip per controller. `ReturnToSpawn()`
  is public (panel Spawn knob calls it).
- **AnchorMoveMode.cs** — grab-world movement, ANCHOR semantics. One-hand grip moves the player
  OPPOSITE to hand motion (full 3D); both grips = anchor translation + in-place yaw turn around the
  head. Grip is suppressed while that hand prop-grabs (`PropGrabber.IsGrabbing`) or the panel is
  near (`WorldPanel.IsBlocking`). **All deltas and turn pivots in WORLD space** (tracking-space math
  made turns orbit the map center — do not regress). Drives `XROrigin3D` directly.
- **PhysicsHands.cs** — physical palm bodies chasing the controller poses: 0.4 kg boxes (flat slab,
  thumb-side face), gravity off, CCD, **layer 4 (player hands)/mask 1|4** — NOT colliding with the
  chest (layer 3), excluded both ways. Chase = desired velocity `(target-pos)/dt`
  force-clamped to `HandMaxForce` 90 N; rotation hard-locked by setting angular velocity to the
  controller's rotation error (clamped to 120 rad/s). Safety: stuck (> 0.2 m for 1 s) → snap +
  log; > `SnapDistance` 2 m → silent teleport snap — BOTH SUSPENDED for a hand while
  `PropGrabber.IsGrabbing(controller)` (a joint legitimately holds the hand back; teleporting a
  jointed hand yanks the prop — the grabber's grip break runs first instead, rip at 0.8 m).
  Hand ghosts: translucent palm boxes shown at the controller pose when the physical hand lags
  > 0.1 m — ghosts belong to the HANDS, not props. Static `GetBody(controller)` lookup used by
  grabber and rig. The chase target passes through `PhysicsArms.ConstrainHand` first (arm
  coupling); the stuck snap is also suspended while that coupling is active.
- **PropGrabber.cs** — grab v5.3: SOLVER-OWNED RIGID WELD via a LOCALLY PATCHED addon (needs
  `research/godot-box3d-weld.md` + the v5.2 history in `research/vr-two-handed-grab.md` — the
  pin joint's hidden spring targets IDENTITY and made every earlier iteration a "winch":
  point constraint + rotator, which the owner rejected as not-how-grab-works: ball orbiting
  the palm, anvil surface drifting under the palm). Grip edge grabs nearest prop in group
  "prop" from palm point (`GrabRadius` 0.16 m, fallback hand center `CenterGrabRadius` 0.12 m)
  — palm-proximity only. On grab: creates a **`ConeTwistJoint3D`** (mapped by the patch to
  Box3D's `b3WeldJoint`) parented under PropGrabber, NodeA = physical hand body, NodeB = prop,
  `SwingSpan = 0`, `TwistSpan = 0`, `Position` = palm point, `ExcludeNodesFromCollision = true`.
  The weld LOCKS THE RELATIVE POSE AT CREATION (the patch pre-corrects frame B with both
  bodies' rotations — no identity-target snap). Configure Position + NodeA + NodeB + spans +
  bias BEFORE `AddChild` — mandatory ordering (configuring after raced Box3D and produced dead
  joints). **NO script forces/torques/damp anywhere** — v5.2's whole servo (PD, gravity
  joints) — v5.2's whole servo (PD, gravity
  feed-forward, MaxHeldSpin, AngularDamp raise) is DELETED; the solver owns everything and
  weight flows through the weld into the hand's 90 N budget honestly. **NO per-tick joint
  re-positioning** — the weld is not a hand-following pivot (moving the node after creation
  does nothing). **BOTH hands weld RIGID (bias 0) — v5.3.1** (the owner rejected the soft
  secondary: it gave ~10-15 cm, "feels like a joint again"; hand₁+prop+hand₂ rigidly welded
  is one composite body, and incompatible controller demands resolve through the HANDS
  lagging, not the object stretching — spike-measured anchors 2–3 mm under full opposite
  tug). If a future jitter appears under wrist-conflict, reintroducing a soft secondary bias
  is the fallback. NO promotion machinery — with both welds rigid from grab, takeover is
  automatic (the survivor's weld simply persists). Grip break:
  prop-local anchor vs live palm point > `GripRipDistance` (0.8 m) instant rip;
  > `BreakDistance` (0.25 m) sustained > `BreakTime` (0.25 s); both hands > `BreakDistanceBoth`
  (0.4 m) breaks two-handed (no promotion on simultaneous break); with a rigid weld these
  rarely fire — they are the stretch/anomaly safety net; when a two-handed hold releases one
  hand, the composite rings briefly (~3° peak, decays < 1 s — stored weld stress discharging). NEW escape hatch: hand body lagging
  its controller beyond `PhysicsHands.SnapDistance` (2 m) → "grip dragged off" instant break
  (heavy props can drag the hand since PhysicsHands' snap is suspended while gripping).
- **PropShop.cs** — builds table (StaticBody3D) + spawns prop table from `Specs[]` (ping pong 2.7 g
  → anvil 50 kg), Label3D captions, CCD for < 0.1 kg, group "prop". `Respawn()` = Reset knob.
- **WorldPanel.cs** — prop-UI panel, PARENTED UNDER `XROrigin3D` (fixed in player's room; revert =
  reparent to Main + fix node paths). Summoned/dismissed via `ax_button` (A/X; menu_button belongs
  to the runtime). Knobs: Spawn (return to spawn + recall panel in front of head), Ping, Reset
  (PropShop.Respawn), Close. Panel/knob bodies: **CollisionLayer 2, CollisionMask 0** (props pass
  through); all CollisionShapes disabled while hidden (`SetShapesEnabled`, deferred). Pointer tip is
  a 12 cm stylus cone; knobs hover-highlight and PRESS ON CONTACT (tip within 4.5 cm, 400 ms
  cooldown) — physical buttons; trigger still presses laser-hovered knobs. Click = code-generated
  `AudioStreamWav` PCM (no asset). Draggable direct or via laser at fixed ray distance, re-orients
  toward head while gripped. `IsBlocking(controller)` (within 0.45 m) makes Locomotion defer
  grab/teleport; `IsPanelCollider(node)` identifies interactive colliders for lasers.
- **TeleportMarker.cs** — `scenes/teleport_marker.tscn`: disc + beam + Label3D, group
  "teleport_marker", StaticBody pick box. `SetNear` hides visuals, `SetHighlighted` swaps colors.
- **PhysicsTorso.cs** — the player's PHYSICAL CHEST (body-physics Stage 1). Implemented
  2026-10-01; the first playtest's NaN collapse is root-caused + fixed (servo math, see §5).
  One RigidBody3D box (0.22×0.5×0.13, 30 kg, gravity off, CCD, contact monitor), chase-driven
  toward an HMD-derived target: target = head − 6 cm back + torso-yaw basis·(0, −0.42, +0.06)
  + `ReachOffset` (fed by PhysicsArms' reach budget). Linear drive = the PhysicsHands pattern at
  body mass (force-clamped PD, `MaxForce` 2400 N ⇒ 80 m/s², `MaxSpeed` 6 m/s). Orientation =
  slewed angular-velocity servo toward the yaw target (Kp 20 rad/s per rad, spin cap 10 rad/s,
  alpha cap 150 rad/s²) — self-rights when shoved, holds yaw. `SnapDistance` 2 m snap safety
  covers teleports. Camera stays KINEMATIC — the torso chases the head, never the reverse
  (Boneworks sickness lesson). Yaw spring (HMD + hands blend) MOVED here from BodyRig.
  Collision: layer 3 (player body), mask 1|3 — props/floor touch it, own hands do NOT
  (hands moved to layer 4; excluded both ways — no self-collision, VRChat/Nimso precedent).
  Owns its torso mesh (hidden until the body first arrives at target). Spike:
  `scenes/body_spike.tscn` must print **"BODY: overall PASS"** (pair-rule proofs: one-way
  floor contact, hand-through-chest exclusion, prop-contact two-way; track/yaw/impact/snap/
  self-right asserts).
- **PhysicsArms.cs** — body-physics **Stage 2: physical arm segments** (2026-10-02). Per side an
  upper-arm (2.0 kg) and forearm (1.2 kg) RigidBody3D box, gravity off, CCD, **layer 5 (player
  arms) / mask 1** — collide with world + props, never with the own chest, hands or each other.
  NO joints (Box3D has no usable 3-DOF shoulder/wrist joint — PinJoint's identity spring, no
  Generic6DOF — and AGENTS.md forbids joints between tracked bodies): each segment PD-chases
  its analytic 2-bone IK pose, solved EVERY PHYSICS TICK from the PHYSICAL chest shoulders to
  the PHYSICAL hand bodies (IK moved here from BodyRig: soft IK 0.98; elbow picked on its circle as an ANGLE around the arm axis relative to a torso-frame
  down/back/out reference: 85% of the angle the HAND suggests — the forearm continues behind
  the wrist along the CONTROLLER's (aim pose) forward axis, not the physics palm's, so a palm
  fighting contact can't swing the elbow — clamped to ±110° (never through the inward/up side)
  and rate-limited to 6 rad/s (no 180° flips; spike: 1.8 cm/tick max vs 13.8 unclamped);
  capped at max(shoulder, wrist) + 5 cm height). **Hierarchical
  budgets** (Nimso muscle model) from `BodyMassStat` 60 kg: hand 90 N ≺ forearm 180 N ≺ upper
  arm 360 N ≺ chest 2400 N. Orientation = slewed angular-velocity servo via
  `BodyMath.RotationError`; segment roll follows the body's current X axis (no flips).
  Safety: 1 m snap (teleports), `ResetIfNonFinite`. Also owns calibration (arm lengths +
  shoulder width from first head height > 0.5 m; segments spawn then) and the torso LEAN
  toward overreaching hands → `PhysicsTorso.ReachOffset`, computed OPEN-LOOP from
  `PhysicsTorso.NominalTarget/TargetBasis` (the head-derived pose without the lean). The old
  closed loop (lean from the body's own shoulders) made the chest hunt back and forth —
  owner-reported, spike-measured 1.1 m/s → 0.019 m/s after the fix. Props held by a hand get
  a collision exception with that side's arm segments (`SetHeld`, called by PropGrabber) —
  a 180 N forearm shoving a prop welded to a 90 N hand was a fight. **Stage 2b hand coupling**
  (`ConstrainHand`, called by PhysicsHands before chasing): while an arm segment is in
  contact, the hand may lead the forearm's end by at most `HandArmSlack` 3 cm — a blocked
  forearm holds the hand back and the hand ghost shows the controller. Free arms never limit
  the hand. Fixes the owner's "palm behind the anvil, forearm rests on it" clip (drawn
  forearm 3.9 cm into the anvil → 0; the collider was always fine at ≤ 6 mm). Exposes
  `Shoulder/Elbow/Wrist/ElbowTarget/WristTarget(side)`; `Elbow` = where the two physical
  segments meet. Spike: `scenes/arm_spike.tscn` (stretch-beyond-reach chest settle, hug elbows out
  0.17 m (old pole: 0.02), held 50 kg anvil stable + forearm out of it, track gap, fast swing, arm pushes a prop
  with the hand clear, forearm blocked by a bar without tunneling + quiet while pinned,
  teleport snap, NaN-injection reset, chest undisturbed by own arms).
- **BodyRig.cs** — placeholder rig VISUALS only: head cube (HMD-driven) + arm boxes drawn
  shoulder (PhysicsArms, from the chest body) → PHYSICAL elbow → hand wrist, stretched to stay
  connected (an obstructed segment shows as a displaced elbow). Hidden until PhysicsArms
  calibrates. IK, calibration and reach budget moved to PhysicsArms; torso mesh + yaw spring
  live in PhysicsTorso.
- **Calibration.cs + BodyProfile.cs (body step 1, 2026-10-02)** — ONE-TIME T-POSE CALIBRATION (owner design:
  VRChat-FBT-like, persists, forced on launch if missing). `BodyProfile` = the player's real metrics (eye height,
  stature = eye/0.936, shoulder half-width = 0.1295·stature, shoulder drop below the eyes, upper arm/forearm in
  the 0.186:0.146 Winter split, stored 1.5 cm SHORT so the real elbow never locks first). `Prefs` stores it in
  **`prefs.json` next to the executable (editor builds incl. headless: the project folder) — gitignored,
  portable (copy the file)**. `Calibration` (node in group "calibration", `Recalibrate()` for the menu) loads it;
  if missing it shows a head-locked Label3D and runs `TPoseDetector`: arms level (±8 cm), at shoulder height,
  symmetric about the head (±10 cm), to the sides (not forward), span 1.0–2.4 m, every point within 3 cm of where
  the hold began (jitter-proof) for 1 s → measure: arm = (wrist span − shoulder width)/2 − margin. Body systems
  (PhysicsTorso, PhysicsArms, BodyRig, TrueBody) WAIT for `BodyProfile.Current`; recalibration rebuilds them.
  Flat preview (no headset) can't calibrate → no body there (expected). Headless spikes that inject a head use
  `BodyProfile.Estimate(eye)`; CollapseSpike sets a fixed standing profile (posture never shrinks the body).
- **ArmSolver.cs** — the shared analytic 2-bone solve (moved verbatim from PhysicsArms: soft IK 0.98, pole as an
  angle about the arm axis vs torso-frame down/back/out, 85% controller-forward suggestion read nearest the current
  angle, ±110° clamp, 6 rad/s, elbow height cap). NEW: minimum reach |upper − fore| + 1 cm (unequal anatomical
  segments made the law of cosines invalid for hands right at the shoulder).
- **TrueBody.cs (body step 1)** — `TrueBodySolver`: Nimso's TRUE BODY — the derived pose of the real body from
  head + controllers + profile (trigonometry, not IK): neck pivot 9 cm below / 7 cm behind the eyes (head frame);
  chest yaw = the HMD/hands yaw spring; chest pitch = crouch lean (crouch measured at the NECK PIVOT so nodding
  isn't crouching; up to ~43°) + ¼ of head pitch-down; neck base along chest-up/head-up average; pelvis hangs
  0.288·stature below the shoulder line through a critically damped 2.5 Hz spring (hip lag/sway, hips kick back in
  a crouch); MOVING SHOULDER GIRDLE: past 98% reach the shoulder joint travels toward the hand within anatomical
  limits (out +3/in −2, up +7/down −2, forward +8/back −3 cm) plus a scapulohumeral shrug up to 4 cm overhead;
  arms via ArmSolver. `TrueBody` node solves every physics tick and draws a translucent cyan DEBUG SKELETON
  (`TrueBody.ShowDebug`) for in-headset judgement. Step 2 (muscle ragdoll) will drive its joints toward this pose.
  Spike `scenes/truebody_spike.tscn`.
- **BodyMath.cs** — shared servo math. `RotationError(target, current)` = shortest-arc
  axis·angle via `2·atan2(|xyz|, W)` — **the only allowed way to compute servo rotation
  errors** (`Quaternion.GetAngle()` NaNs at W = 1.0000001, `GetAxis()` is un-normalized near
  identity — the Stage-1 collapse). `ResetIfNonFinite(body, target, who)` — escape hatch run
  by every driven body (hands, chest, arm segments).
- **CollapseSpike.cs** + `scenes/collapse_spike.tscn` — Stage-1 collapse regression with the
  full body (chest + arms + hands): 9 solver-stacking scenarios (seated chest in the static
  table, two-hand-welded 50 kg anvil + the logged grab sequence, real PropShop sweep) + 40
  slow-yaw-drift scenarios (the root-cause repro: old code NaN'd 7/40). Must print
  "COLLAPSE: overall PASS" (49/49).
- **GrabSpike.cs** + `scenes/grab_spike.tscn` — headless grab regression (v5.3): a hand stand-in
  (0.4 kg body, `HandMaxForce` 90 N chase) grabs a 1 kg prop via ConeTwist weld (server type
  verified, configure-before-AddChild); drag 2 m + 360° fast-spin sub-phase — asserts RIGID
  relative pose (grab-rotation error < 2° drag / < 3.5° spin, anchor separation < 1 cm — the
  winch/orbit regression; 2° is the gravity-on floor for an off-center grab, don't tighten
  below that); two-handed phase (second weld soft, bias 0.3): primary anchor < 1 cm rigid
  under full tug, tug give bounded < 0.25 m (recovers), follow-regime anchor < 0.05 m; then
  primary releases, survivor weld recreated rigid (takeover) and rigidity re-asserted.
  Reach-timeout guards; must pass 3× in a row (never accept flaky).
- **WeldSpike.cs** + `scenes/weld_spike.tscn` — regression for the PATCHED ADDON itself: two
  bodies welded via ConeTwistJoint3D (bias 0 rigid, then bias 0.5 soft); asserts relative-pose
  rigidity under torque/force (rot < 2°, sep < 1 cm), bounded excursion + full recovery for
  the soft weld. Run this FIRST whenever the addon binaries change.
- **BodySpike.cs** + `scenes/body_spike.tscn` — headless regression for the physical torso:
  pair-rule proofs on Box3D (one-way floor contact; hand-config body passes through the chest
  with the chest undisturbed; prop-config body transfers contact), then track (walk pattern,
  error < 6 cm), yaw (90°/1 s turn: peak < 15°, settled < 4°), impact (5 kg at 3 m/s: dip
  < 0.2 m, recovers < 2 cm, never tunnels, rebounds), teleport snap, self-right (< 3° after
  a pitch impulse). Must print **"BODY: overall PASS"** 3× deterministic.

Research (`research/`): **`nimso-project-tx.md`** (exhaustive study of Nimso's Project TX player from 82 of his
video transcripts in `research/sources/nimso-transcripts/` — the design being recreated; read first for body work),
`vr-physics-rig-hexabody.md` (Boneworks/BIMOS rig reference + Box3D native joint mapping), and seven full sourced reports — `vr-arm-ik.md`, `vr-arm-ik-deep.md`,
`vr-grabbing.md`, `vr-two-handed-grab.md` (grab v5.0→5.2 history + the verified Box3D pin
joint internals + dated CORRECTION section), `godot-box3d-weld.md` (the addon patch: weld
mapping, param table, build recipe, risks), `vr-body-physics-hugs.md` (player-body physics +
hug prior art: Boneworks' one-powered-body lesson, active-ragdoll recipes, hug = wrap +
mutual force + reactivity; phased design), `vr-body-physics-godot.md` (verified Box3D
capabilities: no Generic6DOF, hinge VELOCITY motors work, PD-follow proven by the hands).
**READ these before re-researching those topics or changing the grab/IK/body implementations**
— they carry the reasoning behind the current designs. Stink-O's box3d-godot (custom components, 8 joint types) remains the documented
plan-B if the patched-wrapper path is ever abandoned (owner pointed at it; adopting it means
leaving the standard RigidBody3D stack).

Scene wiring (`scenes/main.tscn`): Main → WorldEnvironment, Sun, Floor, XROrigin3D (XRCamera3D,
LeftHand, RightHand, WorldPanel), SpawnPoint, 3 TeleportMarkers, Locomotion, AnchorMoveMode,
PropShop, PropGrabber, PhysicsHands, PhysicsTorso, PhysicsArms, BodyRig, FadeLayer/Fade
(physics order matters: hands → chest → arms, so the arm IK reads this tick's bodies). Action map: `openxr_action_map.tres`.
Floor StaticBody mask 1|3|4|5 (collision_mask 29).

## 4. Architecture decisions that must not regress

- **World-space grab/turn math**: all grab deltas and two-hand turn pivots computed in WORLD space.
  Tracking-space math made two-hand turns orbit the map center. Do not regress.
- **Box3D PinJoint3D quirks (grab history v5.0–v5.2)**: Box3D's PinJoint3D is a TRUE ball joint
  with ANCHORS CAPTURED AT CREATION (not vanilla Godot origin-pinning). The joint node's
  position is READ EVERY TICK (re-setting `GlobalPosition` each tick = hand-following pivot).
  Its hidden rotational spring (hertz = bias × 30) targets IDENTITY — aligns the two bodies'
  world orientations, uncapped, hits both bodies; that was the root of the v5.0–v5.2 grab
  misbehavior (see the CORRECTION section of `research/vr-two-handed-grab.md`). The positional
  (point-to-point) tuning (engine default 60 Hz/ζ2.0 clamped to 0.25×tick) is NOT reachable
  from the wrapper. IMPULSE_CLAMP is a warned no-op.
- **Box3D WeldJoint via the local patch (grab v5.3 lives on it)**: the patch maps Godot's
  ConeTwistJoint3D → `b3WeldJoint`, PRE-CORRECTING frame B with both bodies' rotations so the
  weld locks the relative pose at creation. Bias semantics are INVERTED vs the pin joint:
  bias 0 = MAX stiffness (rigid), bias 0.3 = 9 Hz give. Swing/twist spans > 0 and
  softness/relaxation are warned no-ops (the weld has no limits). The weld is NOT a
  hand-following pivot — moving the joint node after creation does nothing, and none is needed.
  Only the Linux binary is patched (`bin-stock/` holds originals; `.vendor/` the source,
  patch, and rebuild recipe). Pin/hinge/slider paths untouched — grab v5.2.1 remains runnable
  as fallback (git history). Stink-O's box3d-godot (custom components, more joint types) is
  the plan-B.
- **Collision layers**: 1 = world, 2 = UI. Panel/knob bodies are layer 2 mask 0 (props pass through
  the menu); **1 = world+props, 2 = UI, 3 = player body (chest), 4 = player hands, 5 = player arms** —
  no self-collision between any own body parts (props/table/floor mask 1|3|4|5, hands 4/1|4,
  chest 3/1|3, arm segments 5/1). Layers/masks live on `CollisionObject3D`, never `CollisionShape3D`. The
  body_spike proves the pair rules on Box3D.
- **Servo rotation errors only via `BodyMath.RotationError`** — never `Quaternion.GetAngle()`
  / `GetAxis()` (NaN at W = 1.0000001 killed the chest in the first body playtest).
- **No joints between player body parts** — arms are chase segments; Box3D can't do a
  shoulder/wrist joint cleanly (see PhysicsArms).
- **Ghosts belong to hands, not props** — the whole arm gets a ghost later.
- **Standard-RigidBody3D-only** for scene objects and tracked bodies, so the Jolt fallback stays lossless.
- **`pose_recentered` is never used for placement** — WiVRN fires it continuously (~90 Hz);
  reacting to it was the original view-locked-forward bug.
- Panel parented under `XROrigin3D` (deliberate feel); grip thresholds polled as Floats (0.6),
  bool actions unreliable across runtimes.

## 5. Known issues / open questions

- **Body Stage 1 chest collapse — ROOT-CAUSED + FIXED (2026-10-01), awaiting owner re-playtest.**
  The first in-headset session NaN'd the chest ("head detaching from the body"). Cause was
  SCRIPT MATH, not the solver: the orientation servo used `Quaternion.GetAngle()` = `2*acos(W)`
  (Godot C# `Mathf.Acos` is unclamped) → NaN when rounding put W at 1.0000001, which a seated
  still player reaches because `GetAxis()` (raw xyz when W > 1−1e-6) collapsed the servo gain
  inside 0.16° and parked the body where a slowly drifting target crosses it. Fixed with
  `BodyMath.RotationError` (atan2-based) in torso + hands, plus `BodyMath.ResetIfNonFinite`
  escape hatch on every driven body. Deterministic repro + regression:
  `scenes/collapse_spike.tscn` (old code 42/49, fixed 49/49). Solver stacking (chest in
  static table + two-hand-welded 50 kg anvil) was tested and is stable. Full record:
  `research/body-stage1-failure-brief.md` (RESOLUTION section). **RULE: never use
  `Quaternion.GetAngle()/GetAxis()` for servo errors — use `BodyMath.RotationError`.**
- **Body Stage 2 arms — owner playtest 1 (2026-10-02)**: "works fine for the most part";
  reported forearm clipping through a held anvil, chest jitter when stretching one arm,
  elbows mostly pointing down / unnatural. Fixed: open-loop lean (jitter), hand-driven
  elbow + height cap, held-prop exceptions. The exact screenshot clip (forearm through the
  held anvil) was NOT reproduced headless across 3 anvil heights — the drawn forearm is a
  straight line from the PHYSICAL elbow to the hand wrist, so any elbow below a held object's
  near edge can still draw through it; re-check in-headset.
- **Body Stage 2 arms — owner playtest 2 (2026-10-02)**: jitter fixed, elbows "pretty
  good". Reported: occasional 180° elbow flip → angle clamp + rate limit, elbow now from the
  controller pose; forearm clipping when RESTING the forearm on the anvil with the palm behind
  it → measured: collider fine, DRAWN forearm 3.9 cm in (the hand was somewhere a straight
  forearm can't connect to) → hand coupling. Owner raised max_physics_steps_per_frame to
  12–14: harmless but NOT a quality knob (only catch-up ticks); Box3D's solver quality is
  compiled in (`SUB_STEP_COUNT` 4 in `src/spaces/box3d_space_3d.cpp`, contactHertz 30) — the
  fork could expose them if contact stiffness ever matters.
- **Body Stage 2 (physical arms) — remaining watch-list.** Things to watch in the first
  playtest: elbow drawn displaced when a segment is blocked (that's the honest physics view),
  arms sweeping props when seated at the table, any stutter at fast swings (spike: ≤ 6 cm
  joint lag at 2 Hz × 0.4 m). Known gaps by design (Stage 2b, feel-driven): a blocked forearm
  does NOT hold the hand back, and forces on the arms don't reach the chest — both need a
  coupling decision (script-side feedback vs joints) the owner should weigh in on after
  feeling 2a.
- **Arm length was too short** (owner, playtest) — the placeholder rig derives arm length from the head height at
  first frame (×0.46, clamped 0.50–0.72 m). Fix with the ragdoll rebuild: saved calibration profile (stand straight +
  "arm circles" sphere fit), see `research/vr-avatar-arm-length.md`.
- **Chest plows table props** when seated at the table (props thrown up to ~3.8 m/s by the
  2400 N chest). Honest physics; tune by feel.
- **AnchorMoveMode NEEDS FIXING (owner playtest report, 2026-10-01)** — two-hand turning
  is NOT working as intended (not 2-anchor based) and simultaneous two-hand movement acts
  weird. NOTE before fixing: owner is considering replacing grab-locomotion with physics
  thumbstick movement if the body-physics track lands (Nimso-style) — see next-steps item
  about the locomotion decision; don't over-invest in anchor-loco until that's decided.
- **Teleport + lasers are BROKEN** — owner report; both were experiments anyway and are
  NOT current issues. Locomotion.cs's marker/laser machinery may be resurrected or deleted
  when the locomotion direction is decided; WorldPanel's laser-hover knobs still reference
  the laser system, so a deletion needs that decoupling first.
- **Locomotion direction undecided** — owner's lean: full physics thumbstick movement if
  the body track goes the Nimso way (stick pushes the physics body; sway/jog detection
  class of solutions). Anchor-grab locomotion was a scene-viewer-era design; the fix-or-
  replace decision rides on the body-physics track outcome.
- **Project direction note (owner, 2026-10-01)** — initially a scene viewer; messing with
  physics made gameplay-first a live possibility (scene viewer second). NOT decided —
  hinges on whether the body-physics track works painlessly. Affects prioritization only;
  nothing to change in code/docs until decided.

- **Grab v5.3.1 — VALIDATED in-headset (owner: "it just works")** — the grab saga is closed.
  Solver-owned rigid weld via the locally patched addon (ConeTwistJoint3D → b3WeldJoint),
  rigid two-handed, takeover automatic. Headless: grab/weld/physics spikes all PASS 3×.
  Known honest physics, not bugs: ~1.2° elastic sag on off-center grabs under gravity
  (lever-dependent, mass-independent), brief ~3° ring when one hand of a two-handed hold
  releases, and a heavy prop genuinely strains/drags the 0.4 kg hand (that IS the weight
  feel). Angular hold strength on heavy props one-handed = Box3D's solver stiffness floor
  (0.25×tick clamp ≈ 22.5 Hz at 90 Hz) — the documented next lever is raising
  `Engine.PhysicsTicksPerSecond` above the refresh rate (global experiment, only with
  owner go-ahead).
- **Hand reaction / weight-through-hand** — restored for real in v5.3: the weld transmits
  prop weight/forces through the solver into the 0.4 kg hand's 90 N chase budget. Validate
  the heft in-headset.
- Palm offset signs (left +, right −) are taste choices — flip if grabs feel mirrored.
- Near-extension arm shake should be fixed by soft IK (`SoftIKFactor` 0.98) — unvalidated
  in-headset; lower toward 0.95 if shake persists.
- One-frame arm jumps on hand-body snap/teleport (stuck snap, SnapDistance, teleport).
- IK research applied except anything marked open in `research/vr-arm-ik*.md`.
- Hand tracking spike not started (`XRHandTracker` through WiVRN, see `openxr_hand_tracking.rst`).
- Head cube front face can peek at extreme down-angles (bump `HeadBackOffset` if it bothers).
- Real character model: import pipeline owned elsewhere (consumes Skeleton3D + AnimationPlayer).
  Migration path for IK: `SkeletonIK3D` deprecated in 4.7 → custom `SkeletonModifier3D`
  (`_process_modification_with_delta`) with our own analytic 2-bone solve (no built-in supports an
  elbow pole) + `LookAtModifier3D` for head→neck look distribution (head authoritative, neck
  cosmetic, stacked above head's). HL:Alyx shipped hands-only deliberately (arms mislead without
  proprioception) — keep arms cheap and honest.

## 6. Tuning knobs

| Constant | File | Value | Controls |
|---|---|---|---|
| `HandMaxForce` | PhysicsHands.cs | 90 N | hand chase force; also used by GrabSpike stand-in |
| `HandMass` | PhysicsHands.cs | 0.4 kg | hand body mass |
| `HandMaxSpin` | PhysicsHands.cs | 120 rad/s | hand rotation-lock clamp |
| `StuckDistance` / `StuckTime` | PhysicsHands.cs | 0.2 m / 1.0 s | stuck snap (logged) — SUSPENDED while that hand grips |
| `SnapDistance` | PhysicsHands.cs | 2 m | silent teleport snap of hand body — SUSPENDED while that hand grips |
| `GhostLagDistance` | PhysicsHands.cs | 0.1 m | when the hand ghost shows |
| `RigidWeldBias` | PropGrabber.cs | 0 | weld bias for BOTH hands (v5.3.1): 0 = MAX stiffness (rigid) — INVERTED vs pin-joint bias semantics; raise only as a fallback if two-handed wrist-conflict jitters |
| `GripRipDistance` | PropGrabber.cs | 0.8 m | instant release, no timer (checked before the break timer) |
| `BreakDistance` / `BreakTime` / `BreakDistanceBoth` | PropGrabber.cs | 0.25 m / 0.25 s / 0.4 m | grip break: sustained anchor separation (single hand) / both-hands threshold |
| `GrabRadius` / `CenterGrabRadius` | PropGrabber.cs | 0.16 m / 0.12 m | palm-point / hand-center grab range |
| `PalmGrabOffset` | PropGrabber.cs | ±0.045 m along hand +X (left +, right −) | grab point on the palm (taste choice) |
| Grip/trigger thresholds | several files | 0.6 | polled Float edges |
| `SoftIKFactor` | PhysicsArms.cs | 0.98 | shoulder→hand distance clamp before IK solve (lower toward 0.95 if shake persists) |
| `PoleHandWeight` / `PoleSmoothRate` | PhysicsArms.cs | 0.85 / 12 | share of the hand-suggested elbow angle (from the controller's forward axis); exp smoothing of the angle |
| `PoleMaxAngle` / `PoleMaxSpeed` | PhysicsArms.cs | 110° / 6 rad/s | elbow angle clamp around the down/back/out reference + rate limit (anti-flip) |
| `HandArmSlack` | PhysicsArms.cs | 0.03 m | how far a hand may lead its forearm's end while the arm is in contact |
| `ElbowRiseAllowance` | PhysicsArms.cs | 0.05 m | elbow capped at max(shoulder, wrist) height + this (no chicken wings) |
| `TorsoYawHandsWeight` / `TorsoYawForwardness` / `TorsoYawSmoothRate` | PhysicsTorso.cs | 0.6 / 0.3 m / 12 | torso yaw spring: hands blend / forwardness normalizer / exp smoothing (≈200 ms) |
| `TorsoMass` / `MaxForce` / `MaxSpeed` | PhysicsTorso.cs | 30 kg / 2400 N / 6 m/s | chest chase budget (force-clamped PD) |
| `OrientKp` / `OrientMaxSpin` / `OrientMaxAlpha` | PhysicsTorso.cs | 20 / 10 rad/s / 150 rad/s² | chest orientation servo (yaw hold + self-right) |
| `SnapDistance` | PhysicsTorso.cs | 2 m | chest teleport snap safety |
| `armTotal` | PhysicsArms.cs | clamp(0.46×headHeight, 0.5, 0.72) | total arm length, 50/50 split |
| `LeanReachFactor` / `LeanSmoothRate` | PhysicsArms.cs | 0.95 / 6 per s | torso lean starts past 95% reach (open-loop from the nominal chest pose), exp-smoothed ≈170 ms |
| `ReachBudgetMax` | PhysicsArms.cs | 0.25 m | horizontal torso offset clamp |
| `ReachVerticalMin/Max` | PhysicsArms.cs | −0.05 / +0.12 m | vertical torso offset clamp (stops upward oscillation) |
| `HeadBackOffset` | BodyRig.cs / PhysicsTorso.cs | 0.06 m | keeps the head cube out of the view |
| `TorsoBackOffset` / `TorsoDrop` | PhysicsTorso.cs | 0.06 / 0.42 m | chest target below/behind the head |
| `BodyMassStat` | PhysicsArms.cs | 60 kg | scales the arm budgets (N/kg below) |
| `ForearmForcePerKg` / `UpperArmForcePerKg` | PhysicsArms.cs | 3 / 6 N/kg (180 / 360 N) | arm segment chase budgets (hand 90 ≺ fore ≺ upper ≺ chest 2400) |
| `ForearmMass` / `UpperArmMass` | PhysicsArms.cs | 1.2 / 2.0 kg | arm segment masses |
| `SegmentMaxSpin` / `ForearmMaxAlpha` / `UpperArmMaxAlpha` | PhysicsArms.cs | 40 rad/s / 1500 / 1000 rad/s² | arm segment orientation servo caps |
| `SnapDistance` | PhysicsArms.cs | 1 m | arm segment teleport snap |
| `ShoulderRise` | PhysicsArms.cs | 0.25 m | shoulder height above the chest body center |
| `LaserMinDistance` | Locomotion.cs | 0.35 m | laser hidden nearer than this (tip touch instead) |
| `MarkerNearDistance` | Locomotion.cs | 1.2 m | near markers hide + become untargetable |
| Fade times | Locomotion.cs | 0.12 s in / 0.25 s out | teleport fade |
| `PressContactDistance` / `PressCooldownMs` | WorldPanel.cs | 0.045 m / 400 ms | knob press on contact |
| `DirectGrabRadius` / `TipHoverRadius` / `TipLength` | WorldPanel.cs | 0.45 / 0.07 / 0.12 m | panel grab / tip hover / stylus reach |
| `MaximumRefreshRate` | Main.cs | 90 | physics tick = chosen refresh rate |

## 7. Next steps (in order)

0. **Owner playtest of body step 1** — T-pose calibration (forced on first launch; delete `prefs.json` to redo,
   or the menu's Recalibrate), arm length should now match; judge the cyan True Body skeleton (shoulders that
   shrug/reach, crouch lean, hip sway, elbows). Then body step 2 = the muscle ragdoll on the 6-DOF joints.
1. **Owner re-playtest of the body (chest fix + Stage 2 arms)** — the Stage-1 collapse is
   fixed (`collapse_spike` 49/49); feel is unvalidated in-headset. Read the log after.
2. **Locomotion decision** — owner report 2026-10-01: two-hand anchor turning broken (not
   2-anchor based), simultaneous two-hand movement acts weird, teleport + lasers broken
   (experiments, not current issues). Owner's candidate replacement: physics thumbstick
   movement if the body track lands. Fix-or-replace rides on item 1's outcome; teleport/
   laser machinery gets resurrected-or-deleted with it (WorldPanel's laser-hover knobs
   must decouple first if deleted).
3. **Grab points on special objects** — grab is palm-proximity to the prop origin today;
   special objects may want authored grab anchors (see `research/vr-grabbing.md` taxonomy).
4. **Body Stage 2b (feel-driven)** — after the owner feels the 2a arms: couple obstruction
   back into the hands (blocked forearm limits the hand) and arm forces into the chest; then
   head collider. Decide calibration for seated sessions (see §5).
5. **Hand tracking spike** — `XRHandTracker` through WiVRN; controller tip and fingertip must feed
   the same cursor concept (interaction must not assume controllers).
6. **Neck/head look system** — `LookAtModifier3D` head→neck distribution (needs a real skeleton).
7. **EMBODYING** — view-follow + avatar remapping (chest calibration transform); experiments only
   after head/neck look override exists. Theory until proven.
8. **UI milestone** — deliberate full action-map pass + SubViewport/composition-layer decision for
   dense screens (at most ONE such screen; everything else stays props).

## 8. Working agreements

- Read `AGENTS.md` fully before working; it overrides this file where they differ.
- Agent-orchestration workflow: the orchestrator delegates to subagents and reviews their output.
- **Escalation channel**: the owner has a smart external agent for hard problems/number
  crunching — the orchestrator says so when stuck or when a problem exceeds its own
  capability, and the owner forwards. It starts with ZERO project context, so problem
  statements must be fully self-contained (constants, constraints, desired output; no
  repo references). Likely first candidates: per-joint PD gain derivation for the
  hierarchical muscle budgets; Box3D stiffness-clamp vs physics-tick-rate math.
- The USER playtests in VR and reports feel — nothing "works" until the owner confirms in-headset.
- Engine logs (`~/.local/share/godot/app_userdata/VR Messs/logs/godot.log`) are the diagnosis
  source after playtests — read them instead of guessing.
- Spikes are cheap and throwaway; a failed experiment is progress, not rework.
- No GDScript-only addon dependencies (Godot XR Tools is reference-only); C# everywhere.