Initial commit: VR Messs workspace (grab v5.3.1, body-physics research)

research/vr-body-physics-godot.md

@@ -0,0 +1,69 @@
+# 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.