Using XState to coordinate Three.js character animations

Disclaimer: This is not a definitive guide, improvements and feedback are more than welcome!

When creating a character with a complex animation flow, it is a common practice to use a finite-state machine. Popular game engines, such as Unity and Unreal, have built-in solutions to handle state machines in order to queue animation clips. When using JS, however, developers can pick from a multitude of libraries, including XState.

XState is a JS/TS library for state machine modelling and orchestration. It's easy to get started with, but its learning curve gets steeper quickly. Therefore, getting this done was a journey searching through forums, documentations and trial and error.

Goal

Create a character that walks, runs and dances, sits down and does push-ups.

Resources used

• Three.js
• XState
• A Humanoid model
• Ten individual animations:
  • Regular animations: Dancing, Idle, Running, Pushing-up, Sitting and Walking
  • State-Transition animations: Idle to Push-up, Push-up to Idle, Sit to Stand and Stand to Sit

Relevant XState Concepts

• State: The machine's status or mode.
• Events and Transitions: Event is a signal that causes a transition. Transition is a change from one state to another.
• Actions: It's an effect fired when a transition happens, be it on entry or exit.
• Context: Data stored in a state machine

Assumptions

• The character should start from Idle state
• The character should be able to walk, run, do push-ups and sit down from Idle
• Regular animations should run in loop, until another action is fired
• All State-Transition animations should be uninterruptable
• "Idle to Push-up" and "Stand to Sit" should run once before looping "Pushing-up" and "Sitting", respectively, effectively starts
• When transitioning from "Pushing-up" or "Sitting", "Push-up to Idle" and "Stand to Sit" should run once

Solution

Character model and animations were loaded using Three.js.

State Machine

Mermaid diagram of the state machine. A more detailed version can be seen at Stately.ai.

State Machine Context

• currentAction: The Animation to be played
• velocity: How fast should the model move

Setting up State-Transition animations

(
    [
      'Idle to Push-up',
      'Push-up to Idle',
      'Sit to Stand',
      'Stand to Sit',
      'Open Door',
    ] as HumanoidActions[]
  ).forEach((actionName) => {
    actions[actionName].loop = THREE.LoopOnce; // important for triggering finished event
    actions[actionName].clampWhenFinished = true;
  });

Playing an uninterruptable action

In order to play an uninterruptable action, a promise actor will be created. It reads the action to be played from input and adds an event listener to mixer that will be triggered once the action is finished.

playUninterruptableAction: fromPromise(
        async ({ input }: { input: { action: HumanoidActions } }) =>
          new Promise((resolve) => {
            playAction(input?.action);
            const callback = () => {
              mixer.removeEventListener('finished', callback);
              resolve(undefined);
            };
            mixer.addEventListener('finished', callback);
          }),
      ),

Instancing and Listening to State Machine changes

const actor = createActor(setupHumanoidMachine(crossfadeMixer)).start();

actor.subscribe((state) => { 
  if (state.context.currentAction === previousSnapshot?.context.currentAction) return;
  crossfadeMixer.playAction(state.context.currentAction);
  previousSnapshot = state;
});

Controls

In this case, PressControls were implemented. Every time the user presses anywhere in the screen, an event of type Walk or Run, depending on how far away from the character it clicked, will be sent to the actor.

const controls = new HumanoidControls(
  mesh,
  intersectionObject,
  (type: Events) => actor.send({ type }),
  mouse,
);

Result

• Live demo
• Code