Fundamentals

Adding Rive Assets

To add a .riv file to a Unity project, simply drag it into the Project Window. Once dropped, a Rive Asset will be automatically created.

Now you can display the Rive Asset within a Rive Panel and Rive Widget or create a custom script using the low-level API to display the graphic.

File

A Rive.File contains Artboards, StateMachines, and Animations.

If you’re working with the Rive Panel and Rive Widgets components, the Rive Widget will automatically handle loading the underlying Rive File from the assigned Asset.
You only need to use this class directly if you want control of the lifecycle of the Rive File, or if you need to load the file from an external source like a CDN.

The Rive.File class also provides several methods to load Rive content into Unity:

If the file is already in memory, a cached version will be returned to improve performance and avoid redundant loading.

1. From a Rive Asset (.riv file)

You can load a Rive.File from an imported .riv asset in the inspector:

public Rive.Asset asset; // pass in .riv asset in the inspector
private Rive.File m_file;

...

private void Start()
{
    if (asset != null)
    {
        m_file = Rive.File.Load(asset);
    }
}

2. From a Unity TextAsset

You can load a Rive.File from a Unity TextAsset. This is useful if you have the bytes bundled as a TextAsset in the Unity project.

public TextAsset riveTextAsset; // assign in the inspector
private Rive.File m_file;

...

private void Start()
{
    if (riveTextAsset != null)
    {
        m_file = Rive.File.Load(riveTextAsset);
    }
}

3. From a Byte Array

If you have the raw bytes of a .riv file, you can load it directly from a byte array. This method provides flexibility if you’re loading the file data from a custom source or dynamically (e.g. from a CDN-stored file):

private byte[] riveFileBytes; // Your byte array, loaded from remote storage, for example.
private Rive.File m_file;

...

private void Start()
{
    if (riveFileBytes != null)
    {
        m_file = Rive.File.Load(riveFileBytes, "myRiveFileName");

    }
}

Artboards

Artboards contain State Machines and Animations.

Using a Rive Widget component, you can select from a list of available artboards within a given Rive File.

Artboards are instantiated from a Rive.File instance:

private Artboard m_artboard;

...

m_artboard = m_file.Artboard(0); // by index
m_artboard = m_file.Artboard("Arboard 1"); // by name

State Machines

A StateMachine contains Inputs and Events, for more information see Unity State Machines and Rive Events.

Using a Rive Widget component, you can select from a list of available state machines within a given Artboard.

State Machines are instantiated from an Artboard instance:

private StateMachine m_stateMachine;

...

m_stateMachine = m_artboard?.StateMachine(); // default state machine
m_stateMachine = m_artboard?.StateMachine(0); // state machine at index
m_stateMachine = m_artboard?.StateMachine("Name"); // state machine with name

They also control advancing (playing) an animation:

private void Update()
{
    m_stateMachine?.Advance(Time.deltaTime);
}

Rendering

In Unity, Rive renders to a RenderTexture that you can display in your Scene by attaching to a Material or anywhere else you would use a Render Texture within your project.

The Rive Panel automatically renders its Rive Widgets to a Render Texture.

Using the Rive Canvas Renderer, you can display a Rive Panel within a uGUI Canvas.

To display a Rive Panel on a GameObject’s mesh, use the Rive Texture Renderer.

The Rive Panel automatically renders its Rive Widgets to a Render Texture.

Using the Rive Canvas Renderer, you can display a Rive Panel within a uGUI Canvas.

To display a Rive Panel on a GameObject’s mesh, use the Rive Texture Renderer.

Layout and draw commands are managed through the Rive.Renderer.

For a more complex example drawing a texture directly to a camera, see the getting-started project in the examples repository.

The following is a basic example script behaviour to render a given Rive asset to the provided renderTexture. The animation is played by calling .Advance() on the State Machine.

See Animation Playbackfor more general information on playing animations and state machines at runtime.

using System.Collections;
using UnityEngine;
using UnityEngine.Rendering;
using UnityEditor;
using Rive;

using LoadAction = UnityEngine.Rendering.RenderBufferLoadAction;
using StoreAction = UnityEngine.Rendering.RenderBufferStoreAction;

public class RiveTexture : MonoBehaviour
{
    public Rive.Asset asset;
    public RenderTexture renderTexture;
    public Fit fit = Fit.contain;
    public Alignment alignment = Alignment.Center;

    private Rive.RenderQueue m_renderQueue;
    private Rive.Renderer m_riveRenderer;
    private CommandBuffer m_commandBuffer;

    private Rive.File m_file;
    private Artboard m_artboard;
    private StateMachine m_stateMachine;

    private Camera m_camera;

    private void Start()
    {
        // If on D3d11, this is required
        renderTexture.enableRandomWrite = true;
        m_renderQueue = new Rive.RenderQueue(renderTexture);
        m_riveRenderer = m_renderQueue.Renderer();
        if (asset != null)
        {
            m_file = Rive.File.Load(asset);
            m_artboard = m_file.Artboard(0);
            m_stateMachine = m_artboard?.StateMachine();
        }

        if (m_artboard != null && renderTexture != null)
        {
            m_riveRenderer.Align(fit, alignment, m_artboard);
            m_riveRenderer.Draw(m_artboard);

            m_commandBuffer = m_riveRenderer.ToCommandBuffer();
            m_commandBuffer.SetRenderTarget(renderTexture);
            m_commandBuffer.ClearRenderTarget(true, true, UnityEngine.Color.clear, 0.0f);
            m_riveRenderer.AddToCommandBuffer(m_commandBuffer);
            m_camera = Camera.main;
            if (m_camera != null)
            {
                Camera.main.AddCommandBuffer(CameraEvent.AfterEverything, m_commandBuffer);
            }
        }
    }

    private void Update()
    {
        if (m_stateMachine != null)
        {
            m_stateMachine.Advance(Time.deltaTime);
        }
    }

    private void OnDisable()
    {
        if (m_camera != null && m_commandBuffer != null)
        {
            m_camera.RemoveCommandBuffer(CameraEvent.AfterEverything, m_commandBuffer);
        }
    }
}

Create a Unity RenderTexture and Material in Assets
Assign the RenderTexture to the Material
Drag this behaviour to a GameObject and attach the material
Link the .riv asset and RenderTexture on the RiveTexture (custom script) behaviour

Game Runtimes

​Adding Rive Assets

​File

​1. From a Rive Asset (.riv file)

​2. From a Unity TextAsset

​3. From a Byte Array

​Artboards

​State Machines

​Rendering

Adding Rive Assets

File

1. From a Rive Asset (.riv file)

2. From a Unity TextAsset

3. From a Byte Array

Artboards

State Machines

Rendering