Research: avatar arm length vs real arm length (Porssut 2022, Ponton CHI 2024, fitted avatars 2023, VRChat/Bonelab/Nimso) -> decision: fitted physics body + calibrated arm length, avatars as skins; fix seated-arm wording

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

HANDOFF.md

@@ -302,10 +302,9 @@ Floor StaticBody mask 1|3|4|5 (collision_mask 29).
   does NOT hold the hand back, and forces on the arms don't reach the chest — both need a
   coupling decision (script-side feedback vs joints) the owner should weigh in on after
   feeling 2a.
-- **Seated calibration** — BodyRig calibrates proportions from the head height at first
+- **Arm length was too short** (owner, playtest) — the placeholder rig derives arm length from the head height at
-  frame; seated (1.01 m) clamps arm length to the 0.50 m minimum, so normal reaches saturate
+  first frame (×0.46, clamped 0.50–0.72 m). Fix with the ragdoll rebuild: saved calibration profile (stand straight +
-  `ReachOffset` and lean the chest into the table (stable, but wrong proportions). Needs a
+  "arm circles" sphere fit), see `research/vr-avatar-arm-length.md`.
-  standing calibration step or a seated mode — owner's call.
 - **Chest plows table props** when seated at the table (props thrown up to ~3.8 m/s by the
   2400 N chest). Honest physics; tune by feel.
 - **AnchorMoveMode NEEDS FIXING (owner playtest report, 2026-10-01)** — two-hand turning

research/nimso-project-tx.md

@@ -376,8 +376,9 @@ Default anthropometry when only height H is known — **Winter, Biomechanics and
   T-pose/max-reach calibration override arm length (armLen = (wingspan − 2·0.129H)/2 − grip offset); model the
   clavicle as its own driven segment (sternoclavicular → glenohumeral, 0.129H) with elevation/protraction limits
   so reach "beyond" the arm comes from shoulder lift/protraction + chest lean, exactly Nimso's "the shoulder moves
-  up as you lift your arm". Seated play: calibrate standing once and keep the profile (seated head height must not
+  up as you lift your arm". Arm length must come from a saved calibration, never from the current head height
-  shrink the body — the VR Messs playtest bug).
+  (the placeholder rig derived it from head height ×0.46, clamped to ≥ 0.50 m — the owner's "arms were just short").
+  Full decision + sources: `vr-avatar-arm-length.md`.
 
 ## 4. Still unknown (must be designed/tuned by us)
 Exact ground-control force law and gains; muscle drive gains/torque budgets per joint; the elbow "simple

research/vr-avatar-arm-length.md

@@ -0,0 +1,70 @@
+# Research: avatar arm length vs the player's real arm length (2026-10-02)
+
+Question (owner): get arm length right first time — should the player's body be fitted to the player, or should
+the player embody an existing (stylized/anime) avatar with its own proportions, VRChat-style? Decide once.
+[S] = sourced, [I] = inference.
+
+## 1. What the research says
+
+- [S] **The one mismatch that breaks embodiment: the REAL arm reaching full extension while the virtual arm is
+  still bent** (virtual arm longer than real, or offset forward). Porssut et al., *Reaching articular limits can
+  negatively impact embodiment in VR*, PLOS ONE 2022 (https://journals.plos.org/plosone/article?id=10.1371%2Fjournal.pone.0255554):
+  a 5.5 cm offset; ownership fell from ~0.66 to 0.45 and "more than one body" feelings rose when the real elbow hit
+  its limit first; the opposite (avatar arm straight, real arm bent) was tolerated. Advice: "the user never reaches
+  full arm extension by surprise"; if calibration can't be perfect, "choose to have the virtual limbs slightly
+  SHORTER than the real ones". The elbow's own end-stop is "internal haptic feedback" the brain trusts.
+- [S] **Virtual arm shorter than real → the hand can't reach the controller.** Ponton et al., *Stretch your reach*,
+  CHI 2024 (https://arxiv.org/html/2407.08011, https://dl.acm.org/doi/10.1145/3613904.3642268): avatars scaled
+  uniformly from height left an average 26.3 cm (SD 4.7) reach shortfall; of five strategies, STRETCHING the arm
+  to keep the hand on the controller was best for embodiment, proprioception and preference; a free-floating
+  controller kept location but broke continuity; capping the hand at avatar reach was worst. Rendering the
+  controller doesn't matter. A too-LONG virtual arm (untested there) only bends the elbow — reach is unaffected.
+- [S] **Fitted skeletons beat uniform scaling.** Ponton et al., *Fitted avatars: automatic skeleton adjustment for
+  self-avatars in VR*, Virtual Reality 2023 (https://arxiv.org/pdf/2307.09558): uniform scaling by eye height
+  "assume[s] … the same ratios between bone lengths as the user" → controller-to-wrist errors; their fitting
+  reduced hand error by 4–14 cm (male) / 2.6–8 cm (female). Method: (1) uniformly scale the avatar by eye-height
+  ratio, (2) resize upper-arm/forearm bones to the measured arm length. **Arm length measurement: the user swings
+  both STRAIGHT arms in circles; a sphere fitted to the controller positions gives the SHOULDER JOINT centre (sphere
+  centre) and ARM LENGTH (radius, shoulder→wrist).** Neck from head rotations. Embodiment gains appeared "only when
+  the initial avatar proportions differed from the user's" — i.e. exactly the stylized-avatar case. Some avatars
+  needed arms stretched by 12–23 cm.
+- [S] Body ownership tolerates large DELIBERATE changes when movement stays synchronous — up to ~3× arm length
+  (Kilteni et al., *Very Long Arm Illusion*, PLOS ONE 2012, https://journals.plos.org/plosone/article?id=10.1371%2Fjournal.pone.0040867).
+  Proportion is not the problem; a reach/extension mismatch is.
+- [S] **VRChat** measures avatars by ARM SPAN by default (scales so the avatar's arms match yours — hands right,
+  floor/feet often wrong, worse with long-legged anime/MMD avatars) or by HEIGHT (feet right, recommended for
+  full-body tracking) (https://docs.vrchat.com/docs/ik-20-features-and-options). Community limb-scaling prefabs
+  stretch avatar arm/leg bones to the user (https://nanochip.gumroad.com/l/avatarlimbscaling); shoulder-mobility
+  add-ons extend reach when real arms exceed the avatar's.
+- [S] **Bonelab** asks height + T-shirt size with fine-tuning of wingspan, chest, waist, hips, inseam, and runs a
+  "body remapping system" so differently-shaped avatars keep a realistic range of motion
+  (https://www.uploadvr.com/bonelab-avatar-system/, https://roadtovr.com/bonelab-custom-avatar-mod-levels-items-vehicles/).
+  Players report: arms too short for them → "my arm held straight out keeps wanting to lift my character up off the
+  ground" and climbing feels broken because hands aren't 1:1 — the PHYSICS-BODY version of the Ponton shortfall.
+- [S] **Nimso (Project TX)** keeps a TRUE BODY from the user's metrics (height, floor, arm length = shoulder joint
+  → wrist, set so real full stretch = in-game full stretch) and a separate SCALED BODY for avatars, scaling reach
+  from the shoulder so full stretch still maps to full stretch (see `nimso-project-tx.md`).
+
+## 2. Decision for VR Messs
+
+**The physics body is the player's real body; any avatar is a skin fitted onto it.**
+
+1. **Physics ragdoll proportions = the player's calibrated metrics** (Nimso's True Body; the research's "fitted"
+   method). Shoulder joint positions and arm length come from measurement, never from current head height, so
+   standing, seated or lying play all use the same body.
+2. **Calibration (one-time, saved profile):**
+   - Stand straight → eye height + floor (Nimso's "stand straight, touch the ground").
+   - "Arm circles" ~10 s: swing both straight arms; sphere-fit each controller trail → shoulder centres
+     (sphere centres, gives shoulder width and height) and arm length (radius − wrist-to-grip offset).
+   - Skip / failure fallback: Winter/Drillis-Contini ratios from eye height (`nimso-project-tx.md` §3).
+   - Store arm length ~1–2 cm SHORT of the measured value (Porssut: never let the real elbow lock first); the
+     physics hand then trails the controller by that margin only at full stretch.
+3. **Stylized / anime avatar = visual skin on the fitted skeleton** (the fitted-avatar pipeline): uniform scale by
+   eye-height ratio, then resize the avatar's upper-arm/forearm bones to the calibrated arm length (hands not
+   stretched). The anime look survives (head/torso/legs proportions untouched); only arm bone lengths adapt. No
+   bespoke player model needed — any humanoid works.
+4. **"Become a different-sized character" (Bonelab/Nimso Scaled Body)** stays on the back-burner; if built, it must
+   preserve the extension invariant (scale reach from the shoulder so real full stretch = virtual full stretch).
+5. Shoulder girdle: model the clavicle as a driven segment (shrug/protraction ~ a few cm) so overhead/forward
+   reach beyond the arm comes from the shoulder, as in real bodies and in Nimso's "shoulder lifts as you raise the
+   arm".