For more information on designing and building state machines in Rive, please refer to: State Machine.

Rive’s state machines provide a way to combine a set of animations and manage the transition between them through a series of inputs that can be programmatically controlled. Once a state machine is instantiated and playing, transitioning states can be accomplished by changing boolean or double-value inputs, or firing trigger inputs. The effects of these will be dependent on how the state machine has been configured in the editor.

​
Playing state machines

State machines are instantiated in much the same manner as animations: provide the state machine name to the Rive object when instantiated. Ensure that the Rive instance is set to auto-play on initialization to allow the state machine to start immediately.

Web

const r = new rive.Rive({
    src: 'https://cdn.rive.app/animations/vehicles.riv',
    canvas: document.getElementById('canvas'),
    autoplay: true,
    stateMachines: 'bumpy',
    fit: rive.Fit.cover,
});

​
Controlling state machine inputs

Once the Rive file is loaded and instantiated, the state machine(s) can be queried for inputs, and these input values can be set, and in the case of triggers, fired, all programmatically.

Examples

Inputs

The web runtime provides an onLoad callback that’s run when the Rive file is loaded and ready for use. We use this callback to ensure that the state machine is instantiated when we query for inputs.

<div id="button">
    <canvas id="canvas" width="1000" height="500"></canvas>
</div>
<script src="https://unpkg.com/@rive-app/canvas@2.10.3"></script>
<script>
    const button = document.getElementById('button');

    const r = new rive.Rive({
        src: 'https://cdn.rive.app/animations/vehicles.riv',
        canvas: document.getElementById('canvas'),
        autoplay: true,
        stateMachines: 'bumpy',
        fit: rive.Fit.cover,
        onLoad: (_) => {
            // Get the inputs via the name of the state machine
            const inputs = r.stateMachineInputs('bumpy');
            // Find the input you want to set a value for, or trigger
            const bumpTrigger = inputs.find(i => i.name === 'bump');
            button.onclick = () => bumpTrigger.fire();
        },
    });
</script>

We use the stateMachineInputs function on the Rive object to retrieve the inputs. Each input will have a name and type. There are three types:

  • StateMachineInputType.Trigger which has a fire() function
  • StateMachineInputType.Number which has a value number property where you can get/set the value
  • StateMachineInputType.Boolean which has a value boolean property where you can get/set the value
const inputs = r.stateMachineInputs('bumpy');
inputs.forEach(i => {
    const inputName = i.name;
    const inputType = i.type;
    switch(inputType) {
        case rive.StateMachineInputType.Trigger:
            i.fire();
            break;
        case rive.StateMachineInputType.Number:
            i.value = 42;
            break;
        case rive.StateMachineInputType.Boolean:
            i.value = true;
            break;
    }
});

State change event callback

We can set a callback to determine when the state machine changes state. onStateChange provides an event parameter that gives us the string name(s) of the current state(s):

const r = new rive.Rive({
    src: 'https://cdn.rive.app/animations/vehicles.riv',
    canvas: document.getElementById('canvas'),
    autoplay: true,
    stateMachines: 'bumpy',
    onStateChange: (event) => {
        stateName.innerHTML = event.data[0];
    },
});

​
Nested Inputs

It’s possible to control the inputs of nested artboards programmatically (See Nested Artboards).

In this example our main artboard is called Menu, which has a nested artboard called Volume Molecule, and inside that there are two instances of a nested artboard called Volume Component. We want to be able to control the volume input on each instance of the Volume Components at runtime.

The first step is to go to the Menu artboard, right click Volume Molecule in the Hierarchy, and click Export Name. Notice that the artboard’s name is now wrapped in brackets ([Volume Molecule]), which indicates that this artboard can now be referred to in our code. 

Next we’ll go to the Volume Molecule artboard and make sure our two instances of Volume Component have a unique name in the Hierarchy (in this case we have Volume Component and FX Component).

Do not use ”/” in the name for your components, as that will break the search functionality at runtime.

Just like the previous step, we need to right click [Volume Component] and [FX Component] and click Export Name.

Finally we’ll create the paths that allow us to refer to each nested artboard in our code. The path is the names of the nested artboards in the Hierarchy, separated by a ”/”.

  • Music Volume: “Volume Molecule/Volume Component”
  • FX Volume: “Volume Molecule/FX Component”

If the nested artboard named FX Component was inside the Menu artboard, the path would be ”FX Component”. If it was nested within several layers of nested artboards, the path might be ”Artboard-Nested-Level1/Arboard-Nested-Level2/Artboard-Nested-Level3/FX Component” and so on.

To set the Volume input for the above example:

const rive = new Rive({...});
...
rive?.setNumberStateAtPath("volume", 80.0, "Volume Molecule/Volume Component");

All options:

  • setNumberStateAtPath(inputName: string, value: number, path: string)
  • setBooleanStateAtPath(inputName: string, value: boolean, path: string)
  • fireStateAtPath(inputName: string, path: string)

​
Rive Listeners

If your Rive file has Rive Listeners (Listeners) and you’ve configured your Rive instance with a state machine according to the steps outlined per runtime above, there is no additional configuration or options needed to enable the pointer events to be captured on the Rive instance. The event capturing is handled internally by the Rive widget/component.

However, if you are going about constructing your own render loop and using low-level APIs to drive Rive content, (i.e. Low-level API Usage) , you may need to set up event listeners manually to capture user interaction and pass feedback down to the state machine (i.e. see setup in JS).

Was this page helpful?

Suggest editsRaise issue
LayoutText