State Machines
Playing and changing inputs in state machines
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
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.
Inputs can also be set on nested artboards at runtime, see Nested Inputs below.
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.
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 afire()
functionStateMachineInputType.Number
which has avalue
number property where you canget
/set
the valueStateMachineInputType.Boolean
which has avalue
boolean property where you canget
/set
the value
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):
Nested Inputs
You can control the inputs of Nested Artboards at runtime. These inputs are not on the main artboard but on a nested artboard. To set a nested input, you need to know the path where the input exists at an artboard level.
Example
If you load the Menu artboard at runtime and want to set inputs on the nested artboard with the hierarchy name Volume Molecule, the path is Volume Molecule
:
- Use the artboard’s unique hierarchy name, not the artboard’s name.
- Do not include the name of the main artboard. In the example above, the path is
Volume Molecule
, notMenu/Volume Molecule
. - Ensure the nested artboards are marked as exported in the editor to access them at runtime:
You can go as many nested artboards deep as needed. For example, the Volume Molecule artboard shown above has two nested artboards with the following unique hierarchy names:
Volume Component
FX Component
Once you go more than one nested artboard deep the path will be a /
separated string of the unique hierarchy names.
If you load in the Menu artboard at runtime, and want to get/set an input on the FX Component
artboard, the path will be Volume Molecule/FX Component
:
Do not use /
in the name for your components, as that will break the search functionality at runtime.
To set the Volume input for the above example:
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?