State Machine Playback

Overview

For more information on designing and building state machines in the Rive editor, please refer to State Machine Overview. A Rive state machine is a set of animation states and the transitions between them. At runtime there is limited ability to observe or modify the state directly. This is by design, as this would limit the ability of a designer in Rive to modify the state machine without creating breaking changes. Instead, state machines are indirectly controlled through transitions conditioned on Data Binding properties. A designer assigns a default state machine for each artboard in the Rive editor. They may create multiple state machines, each representing a different configuration of states and transitions. When rendering a Rive file and artboard, you may choose which state machine to play. If no state machine is specified, the default state machine for that artboard is used.

Controlling Playback

State machines play by “advancing” over time. This is done once per frame by the amount of time between frames. For example, for a graphic running at 60 frames per second, the state machine would be advanced by approximately 16.67 milliseconds (1/60th of a second) each frame. This advancing evaluates keyframes, transitions, data bindings changes, and ultimately the visible artboard elements to create the illusion of motion over time. Each runtime provides a way to control whether the state machine is playing. When paused or stopped (if the runtime supports stopping), the state machine does not advance and the last rendered frame remains visible. When playing from pause, the state machine resumes from where it left off, whereas when playing from stop, it restarts from the entry state. Whether or not a state machine plays automatically depends on the value of the autoplay (or similarly named) property in each runtime. This is typically true by default. It may be useful to set this to false if you want to configure the state machine and artboard, e.g. through data bindings, before initial playback. In addition to the paused/stopped state, state machines may also “settle”. This is an optimization where the Rive runtime detects that no further changes will occur (for example, if there are no active transitions or animations). While settled the state machine will also stop advancing. This improves performance and energy use by avoiding unnecessary calculations. State machines are unsettled by external actions that change their state, such as user input or data binding changes. You can additionally force a state machine to unsettle by calling play, though it may immediately re-settle if there is no further work to be done.

Playing State Machines

Autoplay the State Machine

To autoplay a state machine immediately after it loads, 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',
    onLoad: () => {}
});

Controlling State Machine Playback

You can manually play and pause the State Machine using the play, pause, and stop methods.

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

const handlePlay = () => {
  r.play()
}

const handlePause = () => {
  r.pause()
}

const handleStop = () => {
  r.stop()
}

Autoplay the State Machine

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 />;
}

Controlling State Machine Playback

You can manually play and pause the state machine using the play, pause, and stop methods.

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

const handlePlay = useCallback(() => {
  rive?.play();
}, [rive]);

const handlePause = useCallback(() => {
  rive?.pause();
}, [rive]);

const handleStop = useCallback(() => {
  rive?.stop();
}, [rive]);

return (
  <div>
    <RiveComponent />
    <div style={{ marginTop: 12 }}>
      <button onClick={handlePlay}>Play</button>
      <button onClick={handlePause}>Pause</button>
      <button onClick={handleStop}>Stop</button>
    </div>
  </div>
);
}

New Runtime (Recommended)
Legacy Runtime

By default, RiveView automatically uses the default artboard and state machine configured in the Editor. In most cases, you only need to provide the file prop.For programmatic control, you can optionally specify artboardName and stateMachineName props to use a different artboard or state machine.

export default function PlaybackExample() {
  const { riveFile } = useRiveFile(
    'https://cdn.rive.app/animations/vehicles.riv'
  );

  return (
    <View style={styles.container}>
      <View style={styles.riveContainer}>
        {riveFile ? <RiveView file={riveFile} style={styles.rive} /> : null}
      </View>
    </View>
  );
}

Controlling State Machine Playback

For more control, you can manage playback and set the artboard/state machine combination:

autoPlay

boolean

default:"true"

Automatically start playing the state machine.

artboardName

String

The name of the artboard to display.If not set, the default artboard will be used, as configured in the Editor.

stateMachineName

String

The name of the state machine to play.If not set, the default state machine will be used, as configured in the Editor.

And manage play, pause, and reset on the Rive view reference.

import { Fit, RiveView, useRive, useRiveFile } from '@rive-app/react-native';

export default function PlaybackExample() {
  const { riveViewRef, setHybridRef } = useRive();
  const { riveFile } = useRiveFile(
    'https://cdn.rive.app/animations/vehicles.riv'
  );

  const play = () => {
    riveViewRef?.play();
  };

  const pause = () => {
    riveViewRef?.pause();
  };

  const reset = () => {
    riveViewRef?.reset();
  };

  return (
    <View style={styles.container}>
      <View style={styles.riveContainer}>
        {riveFile ? (
          <RiveView
            file={riveFile}
            hybridRef={setHybridRef}
            autoPlay={false}
            artboardName="Truck" // specify the artboard to play
            stateMachineName="bumpy" // specify the state machine to play
            style={styles.rive}
          />
        ) : null}
      </View>
      <Button onPress={play} title="Play" />
      <Button onPress={pause} title="Pause" />
      <Button onPress={reset} title="Reset" />
    </View>
  );
}

Autoplay the State Machine

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

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

Controlling State Machine Playback

You can manually play and pause the State Machine using the play and pause methods.

import Rive, { RiveRef } from 'rive-react-native'

export default function App() {
  const riveRef = React.useRef<RiveRef>(null);

  const handlePlayPress = () => {
    riveRef?.current?.play();
  };

  const handlePausePress = () => {
    riveRef?.current?.pause();
  };

  return (
    <View>
      <Rive
        resourceName="truck_v7"
        stateMachineName="bumpy"
        ref={riveRef}
      />
      <Button onPress={handlePlayPress} title="play">
      <Button onPress={handlePausePress} title="pause">
    </View>
  );
}

There are a number of ways to play/select a state machine in Flutter.

When Using `RiveWidgetController` (Recommended)

When you create a RiveWidgetController it will use the default state machine, or you can specify a state machine by name or index.

// Default state machine
var controller = RiveWidgetController(riveFile);
// By name
controller = RiveWidgetController(
  riveFile,
  stateMachineSelector: StateMachineSelector.byName("State Machine 1"),
);
// By index
controller = RiveWidgetController(
  riveFile,
  stateMachineSelector: StateMachineSelector.byIndex(0),
);

Passing this controller to a RiveWidget will automatically play the state machine.

@override
Widget build(BuildContext context) {
  return RiveWidget(controller: controller);
}

You can mark the controller as active to play/pause the state machine (advancing and drawing):

final controller = RiveWidgetController(riveFile);
controller.active = false;

The StateMachineSelector can also be passed to RiveWidgetBuilder to specify which state machine to use:

return RiveWidgetBuilder(
  fileLoader: fileLoader,
  stateMachineSelector: StateMachineSelector.byIndex(0),
  builder: (context, state) => switch (state) {
    /// ...
  },
);

When Using `StateMachinePainter`

When using StateMachinePainter, you can specify the state machine to use by passing an optional name.

// Default state machine
final painter = rive.StateMachinePainter(withStateMachine: _withStateMachine);
// By name
painter = rive.StateMachinePainter(
  withStateMachine: _withStateMachine,
  stateMachineName: 'State Machine 1  ',
);

Creating a State Machine Directly

Create the state machine directly from an Artboard:

final artboard = riveFile.defaultArtboard()!;
// Default state machine
var stateMachine = artboard.defaultStateMachine();
// By name
stateMachine = artboard.stateMachine('State Machine 1');
// By index
stateMachine = artboard.stateMachineAt(0);

Autoplay the State Machine

By default, RiveViewModel will automatically play the given state machine.

SwiftUI

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

UIKit

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

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

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

        viewModel.setView(stateMachineView.riveView)
    }
}

Play

If you set autoplay to false you can simply play the active animation or state machine.

simpleVM.play()

Pause/Stop/Reset

Based on certain events in your app you may want to adjust the playback further.

simpleVM.pause()
simpleVM.stop()
simpleVM.reset()

Compose
Legacy

By default, the Rive composable will select and create the default state machine specified in the Rive editor. To specify a different state machine, you must first create a StateMachine object from an Artboard.

Compose

State machine objects can be created in Compose using the rememberStateMachine function, which takes an artboard and name of the state machine.

val artboard = rememberArtboard(myRiveFile, "My Artboard")
val stateMachine = rememberStateMachine(artboard, "My State Machine")

Outside of Compose

Alternatively, you can create a state machine outside of Compose contexts. Note that with this approach you are responsible for managing the state machine’s lifecycle and must eventually close it with StateMachine::close() when no longer needed, or leveraging its AutoClosable interface with a use block.

val artboard = Artboard.fromFile(myRiveFile, "My Artboard")
val stateMachine = StateMachine.fromArtboard(artboard, "My State Machine")
...
stateMachine.close()
artboard.close()

Using the State Machine

Once you have a state machine, you can pass it to the Rive composable via the stateMachine parameter.By default the Rive composable will play the selected state machine. To toggle the play/pause state, set the playing parameter, triggering a re-composition. This is also used to replicate the auto-play behavior of other runtimes - simply set playing to false if you need to perform initial setup and set to true once ready.

Rive(
  myRiveFile,
  artboard = artboard,
  stateMachine = stateMachine,
  playing = true // Or false to pause
)

By default RiveAnimationView will auto-play the selected state machine.⚠️ The legacy API allows for playing multiple linear animations and state machines simultaneously. This is discouraged due to complexity and divergence from other runtimes. Prefer to use a single state machine controlling all animation through states and transitions.

Using XML Layouts

<app.rive.runtime.kotlin.RiveAnimationView
    app:riveResource="@raw/my_rive_file"
    app:riveStateMachine="My State Machine"
    app:riveAutoPlay="true" />

Using Kotlin

animationView.setRiveResource(
    R.raw.my_rive_file,
    stateMachineName = "My State Machine",
    autoplay = true
)

Controlling Playback

You can control the state machine’s playing state using the same APIs as those for linear animation playback (i.e. play, pause, and stop). When doing so, ensure you set the isStateMachine parameter to true.

animationView.play("My State Machine", isStateMachine = true)
animationView.pause("My State Machine", isStateMachine = true)
animationView.stop("My State Machine", isStateMachine = true)

Runtime Fundamentals

App Runtimes

State Machine Playback

Overview

Controlling Playback

Playing State Machines

Autoplay the State Machine

Controlling State Machine Playback

Autoplay the State Machine

Controlling State Machine Playback

Controlling State Machine Playback

Autoplay the State Machine

Controlling State Machine Playback

When Using `RiveWidgetController` (Recommended)

When Using `StateMachinePainter`

Creating a State Machine Directly

Autoplay the State Machine

SwiftUI

UIKit

Play

Pause/Stop/Reset

Compose

Outside of Compose

Using the State Machine

Using XML Layouts

Using Kotlin

Controlling Playback

Runtime Fundamentals

App Runtimes

​Overview

​Controlling Playback

​Playing State Machines

​Autoplay the State Machine

​Controlling State Machine Playback

​Autoplay the State Machine

​Controlling State Machine Playback

​Controlling State Machine Playback

​Autoplay the State Machine

​Controlling State Machine Playback

​When Using RiveWidgetController (Recommended)

​When Using StateMachinePainter

​Creating a State Machine Directly

​Autoplay the State Machine

​SwiftUI

​UIKit

​Play

​Pause/Stop/Reset

​Compose

​Outside of Compose

​Using the State Machine

​Using XML Layouts

​Using Kotlin

​Controlling Playback

Overview

Controlling Playback

Playing State Machines

Autoplay the State Machine

Controlling State Machine Playback

Autoplay the State Machine

Controlling State Machine Playback

Controlling State Machine Playback

Autoplay the State Machine

Controlling State Machine Playback

When Using `RiveWidgetController` (Recommended)

When Using `StateMachinePainter`

Creating a State Machine Directly

Autoplay the State Machine

SwiftUI

UIKit

Play

Pause/Stop/Reset

Compose

Outside of Compose

Using the State Machine

Using XML Layouts

Using Kotlin

Controlling Playback