live2d-web documentation

Motion and expression

Control motions, sequences, idle weights and expressions.

Playback results and fades

motion() preserves the simple Promise<void> contract. Use playMotion() when completed, interrupted, skipped and disposed must be distinguished. Sequence stops at the first non-completed result.

const result = await character.playMotion('TapBody', 0, {
  fadeInMs: 250,
  fadeOutMs: 400,
})
 
await character.sequence([
  { group: 'TapBody', index: 0 },
  { group: 'Idle', index: 0 },
])
 
await character.expression('smile', { fadeInMs: 500 })

Authored defaults stay intact

Omit fade options to preserve model3, motion3 and exp3 settings. Per-parameter motion fades remain stronger than a playback-wide override.

Choose priority and observe completion

Use normal priority for application actions, idle priority for background playback and force only when the current motion must be replaced. playMotion() resolves with completed, interrupted, skipped or disposed; asset and render failures still reject. Branch on the result instead of inferring completion from a timer.

const result = await character.playMotion('TapBody', 0, { priority: 'normal' })
if (result.status === 'completed')
  await character.expression('smile')

Configure idle and expression ownership

Weighted idle selects only indices with positive weights, and the weights array must match the group size. Calling another expression fades the previous one according to its playback options. clearExpression() is an immediate reset; use it for deterministic teardown rather than as a cross-fade command.