DEV Community

Cover image for Using XState to coordinate Three.js character animations
Henrique Ramos
Henrique Ramos

Posted on

4 1 1 2 1

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;
  });
Enter fullscreen mode Exit fullscreen mode

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);
          }),
      ),
Enter fullscreen mode Exit fullscreen mode

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;
});
Enter fullscreen mode Exit fullscreen mode

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,
);
Enter fullscreen mode Exit fullscreen mode

Result

Sentry blog image

How to reduce TTFB

In the past few years in the web dev world, we’ve seen a significant push towards rendering our websites on the server. Doing so is better for SEO and performs better on low-powered devices, but one thing we had to sacrifice is TTFB.

In this article, we’ll see how we can identify what makes our TTFB high so we can fix it.

Read more

Top comments (0)

👋 Kindness is contagious

Discover a treasure trove of wisdom within this insightful piece, highly respected in the nurturing DEV Community enviroment. Developers, whether novice or expert, are encouraged to participate and add to our shared knowledge basin.

A simple "thank you" can illuminate someone's day. Express your appreciation in the comments section!

On DEV, sharing ideas smoothens our journey and strengthens our community ties. Learn something useful? Offering a quick thanks to the author is deeply appreciated.

Okay