DynamicBone

Secondary motion (jiggle, sway, lag) for tails, ears, hair, ropes and cloaks, simulated in the engine: put DynamicBone on the ROOT bone of a chain and its subtree swings and settles under gravity, wind and the character's motion, kept out of the body by DynamicBoneCollider capsules. A whole body going limp is a Ragdoll; a hand or a foot placed on a target is IK.

• make a tail, ears or hair swing and bounce when the character moves
• keep a tail or a cape from passing through the body
• make a cloak or cape hang from the shoulders and follow the body's turn
• keep hair or a tail above the floor
• blow hair or a cloak in the wind
• turn the jiggle off for a cutscene, or reset it after a teleport
• make a rope of plain nodes hang and swing

Platforms: iOS, Android, desktop, the web player and the le.codes viewer app; not on the web (Web Lite) or in headless tests — check DynamicBone.supported; there it warns once, the animation plays as it is, and dynamicBone.chain stays empty.

At a glance

const main = async () => {
  const scene = new Scene()
  const fox = await Model.load(asset('./fox.glb'))
  scene.add(fox)
  scene.open()
  fox.anim.playLoop('walk')

  const tail = fox.bone('tail')!.aspect(DynamicBone, {
    stiffness: [0.5, 0.15],        // stiff at the base, loose at the tip
    damping: 0.1,
    gravity: 2,                    // m/s²
    angleLimit: [30, 45],          // degrees off the animated direction
    radius: 0.03,                  // metres, for the collisions
  })
  for (const ear of ['earend', 'R_earend']) fox.bone(ear)!.aspect(DynamicBone, { stiffness: 0.6, damping: 0.2, angleLimit: 30, radius: 0.01 })
  fox.bone('Hips')!.aspect(DynamicBoneCollider, { radius: 0.11, to: 'chest' })   // a capsule the tail stays out of

  tail.dynamicBone.floor = 0       // and above the ground plane y = 0
  console.log(`tail chain: ${tail.dynamicBone.chain.map((b) => b.name).join(' > ')}`)
}
main()

Swinging bone chains: DynamicBone options

bone.aspect(DynamicBone, { … })
bone.dynamicBone                 // the aspect — every field is live (pushed when it changes)
bone.dynamicBone.chain           // Node[] — the chain's bones, root first
bone.dynamicBone.particles       // Vec3[] — simulated world positions: the bones, then a tip per leaf
bone.dynamicBone.reset()         // snap onto the animated pose next frame (a teleport, a camera cut)
bone.dynamicBone.guide([{ bone, at, weight }])   // world points bones are drawn to each substep; replaces, [] clears

Any node tree works, not only a skinned model: a rope of plain nodes, with bones naming its joints. Per-bone values (DynamicBoneCurve) take one number for the whole chain or a [root, tip] pair interpolated down it by depth — a tail stiff at the base and loose at the tip.

A child bone that carries a DynamicBone or a DynamicBoneCollider when the chain attaches is left out of it, with its subtree (it is another chain, or the body).

Turn it off for a cutscene, reset after a teleport: weight, reset()

const main = async () => {
  const scene = new Scene()
  const fox = await Model.load(asset('./fox.glb'))
  scene.add(fox)
  scene.open()
  const tail = fox.bone('tail')!.aspect(DynamicBone, { stiffness: [0.5, 0.15], gravity: 2 })

  tail.dynamicBone.weight = 0          // a cutscene: the tail plays the animation exactly
  tail.dynamicBone.weight = 1          // back to the simulation, re-armed on the animated pose
  fox.position = [20, 0, 0]            // a teleport…
  tail.dynamicBone.reset()             // …snaps the chain onto the pose instead of whipping it
}
main()

weight blends in between (0–1). A root jump longer than teleport metres in one frame resets the chain by itself; call reset() for a shorter jump or a camera cut.

Keep a tail or cape out of the character's body: DynamicBoneCollider

A capsule (or a sphere) on a body bone that the chains' bones cannot pass through — hips and chest under a tail, arms and back under a cape.

bone.aspect(DynamicBoneCollider, { radius?, offset?, end?, to?, oneSided? })

Neither end nor to = a sphere at offset. A collider is picked up by every DynamicBone of the same model with colliders: 'auto' or 'humanoid', or used where it is listed.

When it runs: after animation and IK, before skinning

The stage runs after the late phase and the IK chains, before skinning — the Animator, an active ragdoll and late-phase bone writes are its input.

See also

• Animator — the pose the chains follow
• IK and feet — solved just before this stage
• Model — model.bone(name)