State Machine Playback

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 animation states and manage the transition between them that can be programmatically controlled with Data Binding (recommended) and Inputs.

Playing state machines

State machines are instantiated by providing a state machine name to the Rive object when instantiated.

Web

To auto-play a state machine by default, simply set autoPlay to true.

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

Web

To auto-play a state machine by default, simply set autoPlay to true.

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

React

To auto-play a state machine by default, simply set autoPlay to true.

export default function Simple() {
  const { RiveComponent } = useRive({
    src: 'https://cdn.rive.app/animations/vehicles.riv',
    stateMachines: "bumpy",
    autoplay: true,
  });

  return <RiveComponent />;
}

React Native

To auto-play a state machine by default, simply set autoPlay to true.

  <Rive
    resourceName={'vehicles'}
    autoplay={true}
    stateMachineName="bumpy"
  />

Flutter

To autoplay a state machine by default, simply set the stateMachines property at instantiation:

RiveAnimation.network(
    'https://cdn.rive.app/animations/vehicles.riv',
    fit: BoxFit.cover,
    stateMachines: ['bumpy'],
);

In the above snippet, at instantiation time, the runtime will create a StateMachineController reference implicitly and immediately play the state machine.

If you’d like further control over the state machine in cases where you may want to prevent autoplaying the state machine, you can instead pass your own reference to a StateMachineController to the RiveAnimation widget at instantiation time with the isActive property set to false. Below is an example of what this might look like:

class _ExampleState extends State<ExampleState> {
  /// Controller for playback
  late StateMachineController _controller;

  void _onInit(Artboard artboard) {
    var ctrl =
      StateMachineController.fromArtboard(artboard, 'some-state-machine')!;
    ctrl.isActive = false;
    artboard.addController(ctrl);
    _controller = ctrl;
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Play/Pause Example'),
      ),
      body: Center(
        child: RiveAnimation.asset('assets/example.riv', onInit: _onInit),
      ),
      floatingActionButton: FloatingActionButton(
        // Play/Pause the state machine
        onPressed: () => {
          _controller.isActive
              ? _controller.isActive = false
              : _controller.isActive = true
        },
        tooltip: 'Play/Pause',
        child: const Icon(Icons.arrow_upward),
      ),
    );
  }
}

As you change the isActive property of the StateMachineController, you’ll see that the current state may pause advancing through the render loop. This is useful in cases where you may want to load in your Rive on screen, but delay playing until a loading sequence occurs, or some data comes back for your application.

Apple

Specify a starting state machine by setting the name of the state machine via stateMachineName when instantiating the RiveViewModel.

SwiftUI

var stateChanger = RiveViewModel(
    fileName: "skills",
    stateMachineName: "Designer's Test"
)

class StateMachineViewController: UIViewController {
    var viewModel = RiveViewModel(
        fileName: "skills",
        stateMachineName: "Designer's Test"
    )

    override public func loadView() {
        super.loadView()

        guard let stateMachineView = view as? StateMachineView else {
            fatalError("Could not find StateMachineView")
        }

        viewModel.setView(stateMachineView.riveView)
    }
}

Android

Via XML

<app.rive.runtime.kotlin.RiveAnimationView
    android:id="@+id/simple_state_machine"
    android:layout_width="match_parent"
    android:layout_height="400dp"
    app:riveResource="@raw/skills"
    app:riveStateMachine="Designer's Test" />

Via Kotlin

animationView.setRiveResource(
    R.raw.simple_state_machine,
    autoplay = true,
    stateMachineName = "Designer's Test"
)

Additionally, you can use the same APIs from animation playback (i.e play, pause, and stop) to control state machine playback, as long as you set the isStateMachine attribute to true.

animationView.play(
    "Designer's Test",
    Loop.AUTO,
    Direction.AUTO,
    isStateMachine = true
)

animationView.pause(
    "Designer's Test",
    isStateMachine = true
)

animationView.stop(
    "Designer's Test",
    isStateMachine = true
)

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];
    },
});

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];
    },
});

We can set a callback to determine when the state machine changes.

<Rive
  resourceName={'skills'}
  autoplay={true}
  stateMachineName="Designer's Test"
  onStateChanged={(stateMachineName, stateName) => {
    console.log(
      'onStateChanged: ',
      'stateMachineName: ',
      stateMachineName,
      'stateName: ',
      stateName
    );
  }}
/>

If you’d like to know which state a state machine is in, or when a state machine transitions to another state, you can provide a callback to StateMachineController. The callback has the name of the state machine and the name of the animation associated with the state transitioned to:

 void _onRiveInit(Artboard artboard) {
  final controller = StateMachineController.fromArtboard(
    artboard,
    'bumpy',
    onStateChange: _onStateChange,
  );
  artboard.addController(controller!);
  _bump = controller.getTriggerInput('bump');
}

void _onStateChange(
  String stateMachineName,
  String stateName,
) =>
    setState(
      () => message = 'State Changed in $stateMachineName to $stateName',
    );

This runtime allows for delegates that can be set on the RiveViewModel. If provided, these delegate functions will be fired whenever a matching event is triggered to be able to hook into and listen for certain events in the Rive animation cycle.

Currently, there exist the following delegates:

RivePlayerDelegate - Hook into animation and state machine lifecycle events
- player: (loopedWithModel riveModel: RiveModel?, type: Int) {}
- player: (playedWithModel riveModel: RiveModel?) {}
- player: (pausedWithModel riveModel: RiveModel?) {}
- player: (stoppedWithModel riveModel: RiveModel?) {}
RiveStateMachineDelegate - Hook into state changes on a state machine lifecycle
- stateMachine: (_ stateMachine: RiveStateMachineInstance, didStateChange stateName: String) {}

You can create your own delegate or mix in with the RiveViewModel, implementing as many protocols as are needed. Below is an example of how to customize a RiveViewModel’s implementation of the RivePlayerDelegate:

class SimpleAnimation: RiveViewModel {
    init() {
        let model = RiveModel(fileName: "truck_v7", stateMachineName: "Drive")
        super.init(model)
    }

    override func setView(rview view: RiveView) {
        super.setView(view)
        rview?.playerDelegate = self
        rview?.stateMachineDelegate = self
    }

    override func player(playedWithModel riveModel: RiveModel?) {
        if let stateMachineName = riveModel?.stateMachine?.name() {...}
    }

    override func player(pausedWithModel riveModel: RiveModel?) {
        if let stateMachineName = riveModel?.stateMachine?.name() {...}
    }

    override func player(stoppedWithModel riveModel: RiveModel?) {
        if let stateMachineName = riveModel?.stateMachine?.name() {...}
    }

    @objc func stateMachine(_ stateMachine: RiveStateMachineInstance, didChangeState stateName: String) {
        var stateMachineNames: [String] = []
        var stateMachineStates: [String] = []
        stateMachineNames.append(stateMachine.name())
        stateMachineStates.append(stateName)
        ...
    }
}

To listen for state changes, when creating a Listener to register on your animation view, you can add the following callback, where you’ll receive the name of the state machine, and the state it transitions to:

val listener = object : Listener {
    override fun notifyStateChanged(stateMachineName: String, stateName: String) {
        // Do something
    }
}
animationView.registerListener(listener)

Runtime Fundamentals

App Runtimes

State Machine Playback

Playing state machines

Web

Web

React

React Native

Flutter

Apple

SwiftUI

Android

Via XML

Via Kotlin

State change event callback

Runtime Fundamentals

App Runtimes

​Playing state machines

​Web

​Web

​React

​React Native

​Flutter

​Apple

​SwiftUI

​Android

​Via XML

​Via Kotlin

​State change event callback

Playing state machines

Web

Web

React

React Native

Flutter

Apple

SwiftUI

Android

Via XML

Via Kotlin

State change event callback