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).