N.E.K.O: Skill for Claude Code

VRM SpringBone Physics Debugging

This skill covers common issues with VRM hair/clothing physics using @pixiv/three-vrm and how to fix them.

Common Symptoms

1. Hair flies upward or explodes outward on load
2. Hair sticks out horizontally like there's an invisible wall
3. Hair is stiff and doesn't move naturally
4. Physics works but starts from wrong position

---

Root Cause 1: Incorrect Delta Time (Most Common - 90%)

Problem

The vrm.update(delta) function expects delta in seconds, not milliseconds. If delta is too large, physics "explodes".

Diagnosis

// Add this to your animation loop
console.log('delta:', delta);
// Should be ~0.016 for 60fps, NOT 16 or larger!

Solution

// Correct implementation using THREE.Clock
const clock = new THREE.Clock();

function animate() {
    requestAnimationFrame(animate);
    
    let delta = clock.getDelta();
    // Clamp to prevent explosion on tab switch or lag
    delta = Math.min(delta, 0.05);  // Max 50ms
    
    if (vrm) {
        vrm.update(delta);
    }
    
    renderer.render(scene, camera);
}

---

Root Cause 2: SpringBone Colliders (Very Common)

Problem

VRM models have invisible spherical colliders (usually on head/body) that prevent hair from penetrating. Virtually ALL VRM models have oversized colliders, causing hair to appear stuck horizontally in mid-air.

Root Cause Analysis

Confirmed Facts

1. UniVRM Export Bug Exists (#673):

   • When colliders are on scaled objects, the radius doesn't normalize with the mesh
   • Gizmo shows correct size in editor, but exported collider is larger
   • Issue documented with reproducible steps

2. three-vrm Uses Radius Directly (source):

   const distance = length - objectRadius - this.radius;  // radius not scaled by world matrix