VR-Mess/research/vr-physics-rig-hexabody.md

# Research: the Nimso / Boneworks-family physics player rig (2026-10-02)

**Read `nimso-project-tx.md` first** — the exhaustive transcript study of Project TX (the design VR Messs
is copying). This file keeps the Boneworks/BIMOS reference (useful for room-scale reconciliation and joint
values) and the Box3D joint mapping (§4). The BIMOS locoball rig is NOT the target design: Project TX has no
ball/capsule — the player is a muscle-driven ragdoll (§6–7 below and the TX doc).

Goal (owner): copy Nimso's VR physics character controller as closely as possible. [S] = sourced,
[I] = inference. Read before touching the player body / locomotion.

## 1. What Nimso has published (primary sources)

- [S] Nimso's internals are NOT documented anywhere public — no source, no write-up. The technique lives in
  his YouTube videos (`youtube.com/@NimsoStudios`) and itch pages/comments.
- [S] Walk-O-Motion comments (developer replies, https://nimsostudios.itch.io/walk-o-motion-vr-with-physics/comments):
  - "Half your body is a spring joint that acts as your legs" — you slide over low ledges by crouching.
  - "I didn't program climbing, or pole vaulting, or rope swinging" — "side effects of physically attached
    hands"; "all I did was make your hands attach things correctly to your character body".
  - "there is no top speed" (jogging harder = faster); jumps are "literally just tiptoeing quickly";
    "you can use the analogue to move in air slightly"; joints "stabilised and slightly weakened … to be much
    more realistic".
- [S] Hybrid Presence devlog (2019): "purely Physics based motion" → "a slight lag … between the VR Tracking
  and applying motion"; a smoothing attempt made it worse, so it was reverted to direct motion; physics rate
  raised to 90 Hz (https://nimsostudios.itch.io/hybrid-experimental/devlog).
- [S] HYBRID Test Chamber (https://nimsostudios.itch.io/hybrid-test-chamber-tech-demo): stick = direction,
  starts slow; sway in place = faster walk; jog in place ("natural bounce frequency") = run; two-handed items
  blend primary-hand rotation with secondary-hand position; "Shoulder Logic hasn't been implemented yet".
- [S] Hybrid Locomotion 2 is "the backend VR Rig and Locomotion system behind … ProjectTX"; modes Hybrid
  (walk-in-place + stick direction), Accessibility (seated), Exploration (playspace-averaged steering).
- [S] Later work (Spatial Syntax article): fully physics-based body + hands, "interaction retargeting between
  characters of very different sizes and strengths"; arm muscles can't lift the full body weight one-handed
  and strength depends strongly on arm angle.
- [I] Everything public places Nimso in the Boneworks "hexabody" family: a physics body whose lower half is a
  spring "leg", hands jointed to that body (forces flow both ways), physics-native locomotion. His
  differentiators are the locomotion input layer (sway/jog detection), muscle-angle strength, proportions
  retargeting, and later full active-ragdoll legs (Project TX). Those need the video extractions.

## 2. The family's documented structure

- [S] Boneworks player = 6 rigidbodies; Bonelab added arms + chest (11); Marrow 2 = 18 bodies, legs added,
  ball removed (Brandon Laatsch, https://x.com/BrandonJLa/status/2009741997897044046).
- [S] Boneworks: movement input goes through "a highly frictionized rigidbody sphere"; collision only on hands,
  head and foot-ball (https://boneworks.fandom.com/wiki/1Marrow_Interaction_Engine).
- [S] HexaBody (commercial Boneworks clone, https://cloudwalker2020.github.io/HurricaneVR-Docs/manual/hexabody/hexabody.html):
  rolling locoball; crouch/jump by raising/lowering the lower ball/knee; "inverse forces applied to the player
  via the Hand rigidbodies"; fender collider slightly larger than the ball stops wall-climbing; fixed-height
  body with Eye Height calibration (sit mode = raise camera; stand mode = scale the tracking space).

## 3. BIMOS — the open-source reference implementation (MIT, https://github.com/KadenZombie8/BIMOS)

Verified by reading the source and the `[BIMOS] Player Rig.prefab` joint data (2026-10-02):

| Body | Mass | Joint (to) | Config |
|---|---|---|---|
| LocomotionSphere | 20 kg (5 kg mid-jump) | — | rolled by SETTING angularVelocity = (moveDir rotated 90° about up) × WalkSpeed 7.5 (Run 15); maxAngularVelocity ∞; high-friction material when grounded (slope ≤ 50°), low when not; anti-roll force on slopes |
| Fender | 5 kg | Fender→Sphere | linear locked, angular free (ball joint) — bumper around the ball |
| Pelvis | 40 kg | Pelvis→Fender | ONLY Y free, limited 0.65 m; Y drive spring 80 000, damper 10 000, max 10 000 N; target = −FenderPelvisOffset (crouch: 0.2–0.55, tiptoe 0.65) = **the spring legs** |
| Head | 1 kg | Head→Pelvis | only Y free; Y drive spring 5e7 (rigid); target = pelvis.y − camera.y each tick |
| HeadCollider | 1 kg | same as Head | |
| Hands | 2 kg each | Hand→**Head** | linear LIMITED 0.67 m (reach sphere), XYZ drive spring 10 000 / damper 500 / max 5000 N; angular free with slerp drive 300 / 10 / max 100; targetPosition = controller target − head position, targetRotation = controller rotation |

- Rig layer ignores self-collision. Physics at **144 Hz** (`Time.fixedDeltaTime = 1/144`).
- **The XR rig is PARENTED TO THE PELVIS** — the camera rides the physics body.
- **Room-scale** (`RoomScaleMovement`): each fixed step, `delta = camera.xz − rig.xz`; `MovePosition` every body
  (sphere, fender, pelvis, head, and hands if grounded) by `delta`; then subtract `delta` from the camera
  offset. Real walking becomes physical body motion, so walls stop it; the camera follows wherever the body
  ended up. Vertical: head joint target from camera height; camera offset y from the leg compression.
- **Turning**: rotate the controller rig about the pelvis (snap 45° default / smooth).
- **Jump**: anticipation crouches the leg spring, release softens the spring by crouch depth
  (`41000/crouch − 26000`) → the legs push off; legs retract/extend in air; sphere mass dropped to 5 kg in air.
- **Scale**: `rig.localScale = 1.65 / HeadsetStandingHeight` — fixed-size character, scaled tracking.

## 4. Mapping to Godot 4.7 + Box3D (our fork)

- [S] Box3D natively has every joint the rig needs (`.vendor/godot-box3d/box3d/include/box3d/`):
  `b3PrismaticJoint` (spring hertz/damping, target translation, limits, motor) = leg/head sliders;
  `b3MotorJoint` (linear/angular springs with max force/torque, retargetable via `b3Joint_SetLocalFrameA/B`)
  = hand drives; `b3DistanceJoint` (length range) = 0.67 m reach sphere; `b3SphericalJoint` (cone/twist
  limits, target-rotation spring, torque motor) = ball/fender and later shoulders/wrists.
- [S] The wrapper exposes only pin/hinge/slider (slider ignores springs)/cone-twist(→weld, our patch);
  `Generic6DOFJoint3D` is a hard error. Godot's `Generic6DOFJoint3D` has per-axis linear/angular springs
  (stiffness, damping, equilibrium point), limits and motor force limits — the ConfigurableJoint analog —
  and Jolt implements it, so mapping it in the fork keeps gameplay code on standard nodes (Jolt fallback).
- [S] Wrapper supports axis locks (→ b3 motion locks), `cast_motion`, `intersect_ray`, `get_rest_info`.
- [I] Unity drive (spring k, damper c) ↔ Box3D (hertz, ζ): hertz = √(k/m)/2π, ζ = c / (2√(k·m)) using the
  driven body's effective mass. BIMOS legs (k 80 000, c 10 000, ~45 kg) ≈ 6.7 Hz, ζ ≈ 2.6; hands (k 10 000,
  c 500, 2 kg) ≈ 11 Hz, ζ ≈ 1.8. Box3D clamps spring hertz to ≤ ¼ of the substep rate (stable).

## 5. Implications for VR Messs

- Our current body is the inverse of the family design: bodies chase world-space targets and the camera is
  kinematic; nothing transmits hand forces into the body. The family design makes the body the player and
  the hands jointed to it — that single change is what makes walls, climbing, push-offs emerge.
- Our arm segments, grab welds, NaN hardening and spike harness carry over; PhysicsHands' world chase and
  PhysicsTorso's head-chase get replaced by joint drives on the rig.

## 6. Project TX itself — from Nimso's own video transcripts (2026-10-02)

Method: `yt-dlp --skip-download --write-auto-subs` over the 85 physics/TX/Hybrid videos of
`@NimsoStudios` → 80 auto-caption transcripts (~184k words; scratchpad, not committed — re-pull with the
same command). Auto-captions are noisy; quotes below are his words, lightly de-garbled. NOTE: a Google-AI
summary the owner relayed claimed Nimso wrote BIMOS — false (BIMOS is KadenZombie8's A-level project);
AI summaries of his channel blend sources, prefer transcripts.

- [S] **No locoball, no capsule — the player IS a ragdoll.** "right now the entire player system is a full
  rag doll — no Collision exists outside of the rag doll" (3-DOF FULL TILT, D4SfYp2e1oI). The whole
  character can rotate ("full tilt") — designed in from day one because every system must handle it.
- [S] **No IK.** "IK-Less Control" (9IDhcrzJtY4): the arm is a physics joint chain with bone/muscle limits;
  the hand is driven to the tracked point and the elbow lands where the joints put it — "when my elbow
  touches the wall my hand is exactly where I want it". Elbow steered by "a simple calculation" from hand
  twist. Joint limits replace IK constraints.
- [S] **Three layers** (New Physics New Control 9f7Bq_R_wHs; Scalable VR Body yPsCuuNM3lM):
  1. **True Body** — from head + 2 controllers + the user's measured profile: "derived elbow positions,
     logical shoulder control", chest position + rotation, hip position "with a little bit of velocity and
     acceleration control on the hip". "not true IK — just a bit of extra trigonometry to decide where the
     elbow is based on the shoulder and the hand".
  2. **Scaled Body** — True Body retargeted to the avatar's proportions/profile (Mario, Bowser…), scaling
     from the shoulder so full stretch stays full stretch; avatar bones mapped via a profile system, offsets
     auto-generated.
  3. **Ragdoll** — generated "with a single button" from the avatar profile; colliders custom-modelled
     anatomical shapes; "the spine is holding itself in its angular, the elbows are holding themselves in
     the angular" (joint angular drives to the scaled pose) + hands driven to tracked points. Interpolated
     for rendering; everything runs in FixedUpdate.
- [S] **Strength is emergent from the joint drives**: a weight held far out can't be lifted, close to the
  body it can, over the shoulder/overhead it can be held one-handed; "the elbow is no longer pushing up …
  on the hand because of the wrist strength" when extended; leaning on a wall works until the arm extends.
- [S] **NPCs use the identical ragdoll** fed by animation/AI instead of tracking; stumble/balance;
  "tension controls" (loose when idle) planned (Muscle based Ragdoll g84iUSVoQUI).
- [S] **Locomotion = a separate "ground control" system**; at the rewrite the ragdoll legs "just don't have
  collision at the moment — I'm doing some clever work on the ground"; slopes beyond some angle can't be
  climbed with no special-casing; small steps are stepped over. Camera is itself a physics collider
  ("climb on the camera"). Movement direction is "hybrid": hand-directed, falling back to head-directed
  when hand rotation is "illogical" (sword swings).
- [S] Feel goal: "it should never feel like a rag doll"; hands "super nice and soft"; differs from Bonelab
  by tuning — "more damped in certain areas, slightly weaker and stronger in certain areas".
- [S] Joint stability trick (tutorial nArwDeA2Ko4): welded objects merged into ONE compound rigidbody with a
  corrected centre of mass instead of fixed joints — kills light-on-heavy wobble.
- [S] **Procedural legs, zero animation** (New Adaptive Leg System i7F4V9K6SlU): gait is not a 50/50 step timer —
  at speed both feet leave the ground (flight phase), stepping rate stays lazy while stride/lift change;
  adapts to moving ground, crouch, swimming kicks, any avatar. Hip is flexible ("hip kicks out") → crawling
  through tiny gaps. "there's no physics capsule or anything like that, there's no character controller object
  … it's just all a ragdoll and the actual collisions happen on the character body" → leaning over tables works
  because the collision is at the real hip/spine/chest.
- [S] **Tracking is a guide, never the final pose**: only the HMD camera is 1:1; hands/hips/feet are derived
  targets the physics tries to reach ("you have to use the tracking as a guide system"). Even full-body
  tracking wouldn't change that. Works without controllers (hand tracking) — the derivation is the system.
- [S] **Ground/leg force exists and scales with mass**: on-screen ground force ~1100 N standing, ~5000 N
  spike on jump; Master Chief 430 kg, Kirby 30 kg; "it changes the mass of the character … which means the
  grounding has to be stronger as well, so the leg strength is stronger"; "full physics on the ground detection";
  "not as simple as just having a ground system that simply goes down". Per-avatar leg strength → jump height
  (Mario high, Grunt low), per-avatar speed.
- [S] **Avatar adaptation** (ADVANCED BODY ADAPTATION WGgPrne7Ctk): user metrics → any character; arms scaled
  from a chest centre line at the shoulder point (not Bonelab's hand-pull scaling) so hands meet when real hands
  meet; per-character POSE profiles (Eggman crouches by pushing the hip out, not folding the belly); colliders
  match the avatar; jump by body motion (no button) in exploration mode.
- [I] **What remains unpublished**: the exact ground-control force law (support spring on the pelvis from ground
  detection is the obvious reading), joint drive gains/torque budgets, the elbow "simple calculation", gait math.
  These are tuning/derivation details to rebuild, not architecture.

## 7. Architecture to build (Project-TX-faithful, Box3D)

1. **True Body** (C#, every physics tick): head + 2 controllers + user profile → target pose for every bone
   (chest pos/rot incl. crouch lean, shoulders, trig elbows steered by hand twist, hip with velocity/acceleration
   lag). Our BodyRig/PhysicsArms IK + torso-yaw math is the seed.
2. **Scaled Body**: retarget to the avatar profile (placeholder boxes first; real characters later).
3. **Ragdoll player**: pelvis, spine/chest, head (collider, camera reference), upper arms, forearms, hands,
   thighs, shins, feet. Joints: spherical (cone/twist limits) for shoulders/hips/wrists/neck/spine, revolute for
   elbows/knees. **Muscles = per-joint angular PD via torque-capped joint motors** toward the True-Body local
   rotations (hierarchical budgets) — strength emerges. Hands additionally pulled to the tracked targets with a
   force-capped drive (guide only). No capsule, no ball.
4. **Ground control**: ground detection under the feet/pelvis → support force on the pelvis (leg strength ∝
   mass), horizontal movement force with acceleration limits from stick / room-scale; procedural leg targets.
5. **Camera**: HMD stays 1:1 relative to the head body; the play space follows the ragdoll (room-scale deltas
   become body motion, BIMOS-style), so walls stop both stick and real walking.
Box3D needs from the fork: spherical joint with cone/twist limits + torque-capped motor (`b3SphericalJoint`),
revolute motor (already mapped via HingeJoint3D), a force-capped target drive (`b3MotorJoint`).