How VRM Spring Bone Physics Works in glTF

VRM handles dynamic secondary animation, such as the movement of hair, clothing, and accessories, through specialized glTF extension properties known as SpringBone. Rather than relying on pre-baked keyframes or proprietary engine setups, VRM stores spring parameters, node hierarchies, and collision volumes directly inside the glTF JSON structure. This article explains how VRM defines these bone springs, details the underlying mathematical parameters, and describes how runtime engines interpret this glTF metadata for cross-platform, real-time physics simulation.

The glTF Extension Architecture

VRM is built on top of glTF 2.0 and utilizes the extension mechanism to declare procedural physics.

  • VRM 0.x: Spring physics are declared under the extensions.VRM.secondaryAnimation property.
  • VRM 1.0: The specification modularized physics under the standardized extension VRMC_springBone, alongside VRMC_node_collider for collision shapes.

Regardless of the specification version, the extension JSON does not store physics simulation logic itself; instead, it defines an execution graph that maps to existing glTF nodes. Runtime applications read these properties and apply dynamic solvers (typically Verlet integration) directly to the target node transforms.

Spring Bone Hierarchy and Springs

In the extension data, springs are grouped into logical chains. Each spring entry identifies a starting bone node within the glTF nodes array:

  1. Root Nodes: The spring definition points to the root of a chain (for example, the base of a hair strand).
  2. Joints: In VRM 1.0, each segment of the chain is explicitly defined as a spring joint with localized physical properties, allowing stiffness or hit radius to vary progressively from root to tip.
  3. Reference Frames: The movement of a spring bone is calculated relative to its parent node, allowing the rest pose to match the model's base skeleton without needing separate bind poses for physics.

Core Physical Parameters

The glTF extension properties dictate how the spring responds to movement, inertia, and external forces:

  • Stiffness (stiffness / stiffnessForce): Determines the force pulling the bone back toward its original local orientation. Higher values result in rigid objects, while lower values make the bone loose and flexible.
  • Damping (dragForce): Simulates air resistance and energy dissipation. It prevents perpetual oscillation by slowing down bone velocity over time.
  • Gravity (gravityPower and gravityDir): Applies a constant directional vector force to the spring. This is used to pull elements downward or simulate constant external forces like wind.
  • Hit Radius (hitRadius): Defines a spherical collision boundary around the spring bone’s joint. This radius is evaluated during collision tests with collider shapes.

Collision Detection via Extension Properties

To prevent dynamic bones from passing through the avatar's body, the extension defines collision structures that link to standard skeleton nodes (such as the head, chest, or arms).

  • Collider Groups (colliders / colliderGroups): Specify nodes that host collision geometry.
  • Collision Shapes: Primarily defined as spheres (center offset and radius) or capsules (spheres connected across an axis).
  • Linkage: Inside the spring definition, an array of indices references which collider groups that specific spring chain should interact with. This selective linkage optimizes performance by avoiding global collision calculations across all bones.

Runtime Execution Workflow

When a VRM-compatible engine imports the glTF file, it executes the following steps:

  1. Parse Extensions: The engine reads VRMC_springBone and identifies all target bone indices and collider nodes.
  2. State Initialization: The initial world transforms of the spring joints are cached as reference positions.
  3. Frame-by-Frame Integration: During each frame update:
    • Parent bone transforms are updated via animation or tracking.
    • Inertia and external forces (gravity, drag, stiffness) update each spring joint's virtual position using numerical integration.
    • Length constraints are enforced to ensure bone lengths remain constant.
    • Collision resolution pushes spring joint spheres outside the bounds of defined collider spheres and capsules.
  4. Transform Application: The resolved positions are converted back into local rotations and applied to the glTF scene nodes before mesh rendering.