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.

4.7 KiB Raw Blame History Unescape Escape