# Research: body physics on Godot 4.7 + Box3D — verified capabilities

Companion to `vr-body-physics-hugs.md` (prior art + recommendation). This file grounds that
recommendation in what the LOCAL stack actually supports. Everything [S] was verified by the
orchestrator directly against `.vendor/godot-box3d/` source and the pinned docs at
`/home/foxyz/Projects/Games/.shared/godot-docs-4.7/`. Researched 2026-10-01.

## 1. Joint inventory on Box3D (v0.2.6, verified in source)

- [S] Implemented joint types (`src/joints/`, dispatch in
  `src/servers/box3d_physics_server_3d.cpp`): **pin** (`_joint_make_pin`, line 942),
  **hinge** (`_joint_make_hinge`, line 1003), **slider** (line 1068), **cone-twist**
  (line 1100 — LOCALLY PATCHED to b3WeldJoint, see `godot-box3d-weld.md`).
- [S] **Generic6DOFJoint3D is NOT supported** — `_joint_make_generic_6dof` (line 1126) is a
  hard `ERR_FAIL_MSG("Box3D: Generic6DOFJoint3D is not supported; use PinJoint3D, HingeJoint3D,
  or SliderJoint3D instead.")`. Any design must not rely on 6DOF drives.
- [S] **Hinge motors WORK** (`src/joints/box3d_hinge_joint_impl_3d.cpp`): `HINGE_JOINT_FLAG_ENABLE_MOTOR`
  → `b3RevoluteJoint_EnableMotor`; params `HINGE_JOINT_MOTOR_TARGET_VELOCITY` +
  `HINGE_JOINT_MOTOR_MAX_IMPULSE` → `b3RevoluteJoint_SetMotorSpeed/SetMaxMotorTorque` (lines 22–24,
  128–131). It is a VELOCITY motor with a torque clamp — position control = per-tick PD:
  `targetVelocity = (targetAngle − angle) × gain`, clamped, with `maxImpulse` as the force budget.
  This is the Box3D primitive for active-ragdoll limb drives (phase 2 of the hugs design).
- [S] Body modes exist (`_body_set_mode`, line 448); constant forces/torques work
  (`_body_add_constant_torque` line 749) — already proven in production by PhysicsHands'
  90 N chase (RigidBody3D, mass 0.4, gravity off, CCD, `ApplyTorque` verified earlier).

## 2. Godot 4.7 skeleton/modifier APIs (pinned docs, `classes/*.rst`)

- [S] Available and current: `SkeletonModifier3D` (base, `_process_modification_with_delta`),
  `IKModifier3D`, `LookAtModifier3D`, `CopyTransformModifier3D`, `ConvertTransformModifier3D`,
  `ModifierBoneTarget3D`, `LimitAngularVelocityModifier3D`, `RetargetModifier3D`,
  `BoneAttachment3D`, `PhysicalBone3D` + `PhysicalBoneSimulator3D`, `SkeletonProfileHumanoid`.
- [S] `SkeletonIK3D` remains deprecated (known trap, HANDOFF §2). `XRBodyModifier3D` and
  `XRFaceModifier3D` exist (OpenXR body/face tracking — future spike material).
- [I] For the placeholder rig (no Skeleton3D), none of these apply yet — the plan keeps the
  procedural `BodyRig` boxes and adds physics BODIES that the boxes follow (CopyTransform-style
  reads in `_Process`), then re-home the same chase bodies onto a real skeleton later via
  `BoneAttachment3D`/`SkeletonModifier3D`. Migration path stays intact.

## 3. Drive patterns that work on this stack

- [S] **PD-driven rigid follow is PROVEN on Box3D at 90 Hz** — PhysicsHands is exactly that
  (desired velocity `(target−pos)/dt`, force-clamped to 90 N). A heavier torso body is the same
  pattern with a larger mass and larger budget; the 0.4 kg hands' stability across grab v5's
  saga is the empirical evidence the pattern holds.
- [S] Kinematic drive + physical reaction alternative: `AnimatableBody3D` pushes dynamics in
  Godot; but a kinematic chest is INFINITE mass — it would shove NPC bodies without ever being
  resisted, breaking the mutual-force requirement from `vr-body-physics-hugs.md` §4. [I] Rejected
  for the chest; fine for the WorldPanel.
- [I] No built-in "spring to target pose" body/joint in Godot or Box3D — confirmed absence;
  every drive is hand-rolled PD (hands already do it; hinge motor is the solver-native version).

## 4. Collision strategy

- [S] Layers/masks live on `CollisionObject3D` (standing trap). Current use: 1 = world, 2 = UI;
  hands layer 1/mask 1. Proposal: 3 = player body (torso + future arm segments), torso mask = 1|3
  (world + itself-if-needed), hands mask 1|3 so palms can rest on the own chest; exclude
  torso↔own-forearm pairs later via joint `ExcludeNodesFromCollision` equivalents — Box3D has no
  pair-exclusion API [I, verify when needed]; simplest is disjoint masks per limb until proven
  otherwise.

## 5. Recommendation for VR Messs

Follow `vr-body-physics-hugs.md` §5. Verifications add two facts to it:
- Phase 2 limb drives are buildable TODAY on the patched addon: hinge velocity motors + per-tick
  PD toward the analytic IK angles (no Generic6DOF, no 6DOF drives — design accordingly).
- Phase 1 needs NO new addon work: torso = RigidBody3D chase-driven (hands pattern, bigger mass),
  arms stay analytic IK, palms + torso give mutual contact. Sickness guard: camera stays
  kinematic; torso chases the HMD, never welds to it; cap tug coupling below the chase budget.