Getting started
Adding Rive to your Unity game.
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.​
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 it as a git dependency, for example (replace 0.0.0
with the latest tag):
git@github.com:rive-app/rive-unity.git?path=package#v0.0.0
Or through HTTP (replace 0.0.0
with the latest tag):
https://github.com/rive-app/rive-unity.git?path=package#v0.0.0
Open Window -> Package Manager
Choose Add package from git URL...
Add the URL with version tag
You can also add and update it manually to your projects Packages/manifest.json
file (replace 0.0.0
with the latest tag):
"app.rive.rive-unity": "git@github.com:rive-app/rive-unity.git?path=package#v0.0.0",
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);
}
}
Arboards
An 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 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
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 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
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