vrm-physics_skill

Overview

This skill debugs and fixes VRM SpringBone physics issues when using @pixiv/three-vrm, focusing on hair and clothing that fly upward, stick out horizontally, or behave unnaturally. It provides targeted diagnostics and runtime fixes for common causes: incorrect delta time, oversized colliders from export, scene scaling mismatches, and model configuration errors. Use the provided code snippets to stabilize physics quickly in JavaScript apps.

How this skill works

The skill inspects springBoneManager state, collider radii, joint settings, and the animation loop delta to identify misconfiguration. It offers pragmatic runtime remedies: clamp delta to seconds, reduce or disable collider radii, scale colliders with the scene, and reset or reinitialize spring bone state. It also includes guidance to verify whether the root cause is the model itself and when a Unity/Blender re-export is required.

When to use it

• Hair explodes outward or flies up on load or after tab switching
• Bangs or hair stick out horizontally as if an invisible sphere blocks them
• Physics feels overly stiff or joints are immobile
• Model scaled at runtime and colliders no longer match visual bones
• After importing a VRM and physics behave differently than in the editor

Best practices

• Call vrm.update(delta) with delta in seconds and clamp large deltas (e.g., Math.min(delta, 0.05))
• Apply an empirical collider reduction (default 0.5) and keep the original radius stored for tuning
• When scaling vrm.scene, scale collider radii proportionally to the scene scale
• Use springBoneManager.reset() and setInitState() to recover consistent rest positions after adjustments
• If many joints show _worldSpaceBoneLength: 0, treat as a model export issue and validate in official VRM viewers

Example use cases

• Quickly stabilize hair physics in a web app by clamping delta and applying collider reduction at model load
• Fix bangs that horizontally protrude by disabling or reducing head colliders at runtime
• Adapt VRM models to different screen sizes by scaling collider radii alongside vrm.scene
• Diagnose whether a physics problem is engine-related or a model export issue using the official VRM viewer
• Temporarily disable all colliders to confirm collision vs. gravity-root causes during debugging