Getting Started

Adding Rive to your Unity game

This article is out of date! Find the new version here.

The rive-unity package is currently in Technical Preview for macOS and Windows. We're hoping to gather feedback about the API and feature-set as we expand platform support. There may be sudden breaking changes between versions and not all Rive runtime features are supported yet - see Feature Support

Example Projects

To quickly experiment with rive-unity, run one of our example projects: https://github.com/rive-app/rive-unity-examples

Installation

The rive-unity package is available to install from GitHub.

You will need a Unity editor that supports OpenGL or D3D11 for Windows, or a Mac with ARM64 (M1, M2, etc) architecture.

On Mac with ARM64 you do not need to configure anything. To manually update select either D3D11/OpenGL for Windows, or Metal for Mac/iOS as the Graphics API under Edit -> Project Settings -> Player in Unity.

You can install the Rive package for Unity by opening the Package Manager and adding the latest tag as a git dependency:

git@github.com:rive-app/rive-unity.git?path=package#v0.1.69

Or through HTTP:

https://github.com/rive-app/rive-unity.git?path=package#v0.1.69

  1. Open Window -> Package Manager

  2. Choose Add package from git URL...

  3. Add the URL with version tag

You can also add and update it manually to your projects Packages/manifest.json file:

"app.rive.rive-unity": "git@github.com:rive-app/rive-unity.git?path=package#v0.1.69",

Assets

A .riv file can be added like any other Unity asset, by dragging it into the Assets folder. You can preview the animation in the inspector by selecting it.

File

A Rive.File contains Artboards, StateMachines, and Animations. There are higher-level behaviors that you can use directly in the Unity editor. Use this class if you need direct control of the lifecycle of the Rive File.

A Rive File can be created from a Rive Asset (.riv):

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

Artboards

An Artboard contains StateMachines and Animations. 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 Events.

State Machines are instantiated from an Arboard 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

Rive Unity renders to a RenderTexture that you can display in your Scene by attaching to a Material or drawing to the camera. Layout and draw commands are managed through the Rive.Renderer.

For a more complex example of 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 Playback for more general information on playing animations and state machines at runtime.

RiveTexture.cs
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);
        }
    }
}

  1. Create a Unity RenderTexture and Material in Assets

  2. Assign the RenderTexture to the Material

  3. Drag this behaviour to a GameObject and attach the material

  4. Link the .riv asset and RenderTexture on the RiveTexture (custom script) behaviour

Last updated