The Rive Unity package includes components to help you integrate Rive into your project quickly and easily. These components are a high-level abstraction over the low-level API, handling rendering and pointer input, and providing a unified way of working with Rive across render pipelines.

We recommend working with these components unless you have specific rendering needs or need more control over where Rive fits into your graphics pipeline, in which case you can use the low-level API.

Rive Panel

The Rive Panel is the foundation for displaying Rive graphics in Unity. It acts as a viewport that manages and renders a collection of Rive widgets to a render texture, with the panel’s dimensions determining the render target’s size.

The panel renders multiple widgets to a single render texture, which means you draw different Rive files and artboards to one texture by placing multiple Rive Widgets under the same panel. This is more performant than using multiple panels as each panel renders to a separate texture by default.

Setup

Create an instance: Right-click in the scene hierarchy → Rive → Rive Panel

A Rive Panel simply handles drawing the graphics to a texture. You’ll need to use the Rive Panel with a Panel Renderer to display the texture.

Configuration

PropertyDescription
Custom Render Target StrategyThe strategy to use for rendering the panel. By default, each panel renders to a single RenderTexture that matches the panel’s dimensions. You can provide a different strategy to render to a pool of textures or share a texture between panels.
Update ModeControls how the panel updates widgets: Auto for automatic updates each frame, or Manual for explicit control through Tick().
Disable Editor PreviewUse this to prevent the panel from rendering in Edit mode in the Unity Editor

Properties

PropertyDescription
Widget ContainerThe RectTransform that holds the panel’s widgets.
WidgetsA read-only list of widgets managed by the panel.
Render TextureThe current render texture where widgets are drawn.
Scale In RenderTextureThe scale of the panel within its render texture. Returns Vector2.one if no render strategy is set.
Offset In Render TextureThe offset of the panel within its render texture. Returns Vector2.one if no render target strategy is set.
Is RenderingWhether the panel is currently registered with a render target strategy and actively rendering.

Public Methods

NameDescription
Tick(float deltaTime)Updates all widgets in the panel. Called automatically in Auto mode.
You only need to call this if the Update Mode is set to Manual
StartRendering()Begins rendering the panel if it isn’t already rendering to a render texture.
StopRendering()Stops rendering the panel if it’s currently rendering to a render texture
SetDimensions(Vector2 dimensions)Sets the width and height of the panel.
RegisterInputProvider(IPanelInputProvider provider)Registers a custom input provider for handling pointer events.
UnregisterInputProvider(IPanelInputProvider provider)Removes a previously registered input provider.

Rive Widget

The Rive Widget is the primary component for displaying Rive artboards in Unity. It handles loading Rive files either from assets during edit time or from runtime-loaded files (useful when loading Rive content from a server or Addressables). The component manages artboard and state machine setup, automatically configuring everything needed to display your graphic.

Setup

Create an instance: Right-click in the scene hierarchy → Rive → Widgets → RiveWidget

Rive Widgets must be placed under a RivePanel to be displayed.

Configuration

FieldDescription
AssetThe Rive asset (.riv) to load.
Artboard NameThe name of the artboard to load from the Rive file.
State Machine NameThe name of the state machine to load from the selected artboard.
Hit Test BehaviourHow pointer events are handled (Opaque, Translucent, Transparent, None).
FitHow the artboard should fit within the widget’s bounds. See the Fit docs for more details about the available options.
AlignmentHow to align the artboard within the widget’s bounds
Layout Scale FactorScale multiplier used when in Layout fit mode.
Layout Scaling ModeHow the widget scales in Layout mode ( ReferenceArtboardSize , ConstantPhysicalSize and ConstantPixelSize).
Fallback DPIDPI value to use when screen DPI is unavailable
Reference DPITarget DPI for scaling calculations

Properties

NameDescription
FileThe currently loaded Rive file instance.
ArtboardThe currently loaded artboard instance.
State MachineThe currently loaded state machine instance.
StatusCurrent status of the widget (Uninitialized, Loading, Loaded, Error)

Events

NameDescription
OnRiveEventReportedTriggered when a Rive event is reported from the Rive graphic.
OnWidgetStatusChangedTriggered when the widget’s status changes (e.g., from Loading to Loaded, or Error).

Public Methods

NameDescription
Load(File file)Loads a Rive file using the default artboard and state machine.
Load(File file, string artboardName, string stateMachineName)Loads a Rive file with specified artboard and state machine.
Load(Asset asset)Loads from a Rive asset using the default artboard and state machine. The Rive Widget manages the lifecycle of the loaded file and cleans up the file when the widget is destroyed or when a new asset is passed in.
Load(Asset asset, string artboardName, string stateMachineName)Loads from a Rive asset with specified artboard and state machine. The Rive Widget manages the lifecycle of the loaded file and cleans up the file when the widget is destroyed or when a new asset is passed in.

If you use any Load methods that accept a File instance, you’re responsible for disposing of the File instance when you no longer need it. This is not the case when loading from an Asset as the Rive Widget manages the lifecycle of the underlying file (loading and disposing).

Procedural Rive Widget

The Procedural Rive Widget enables runtime generation of graphics using the Rive’s Renderer. This component lets you create graphics programmatically using Rive’s drawing primitives (paths and paints, etc.). See this example for a practical implementation of a procedural drawing.

Setup

Create an instance: Right-click in the scene hierarchy → Rive → Widgets → Procedural Rive Widget

Procedural Rive Widgets must be placed under a RivePanel to be displayed.

Configuration

PropertyDescription
Procedural DrawingProceduralDrawing instance that defines what to draw.
Hit Test BehaviorHow pointer events are handled (Opaque, Translucent, Transparent, None).

Properties

NameDescription
StatusCurrent status of the widget (Uninitialized, Loading, Loaded, Error).

Events

NameDescription
OnWidgetStatusChangedTriggered when the widget’s status changes (e.g., from Loading to Loaded, or Error).

Public Methods

NameDescription
Load(ProceduralDrawing proceduralDrawing)Loads a new procedural drawing into the widget.

Panel Renderers

Panel renderers connect RivePanel’s render texture to Unity’s display systems. By separating rendering logic from display concerns, we can support different rendering contexts (UI, world space, etc.) while keeping the core Rive functionality consistent.

Each renderer type specializes in a specific Unity rendering pathway, handling details like input systems and render order automatically.

Rive Canvas Renderer

The Rive Canvas Renderer displays Rive content within Unity’s UI system (uGUI). It automatically configures the necessary Canvas components and handles UI-specific concerns like proper render order and raycasting.

The Rive Canvas Renderer controls the size of the Rive Panel based on the uGUI Canvas it is being displayed under.

You can also create a Rive Panel that has been automatically configured to use this component by right-clicking in the scene hierarchy and navigating to the Rive > Rive Panel (Canvas)

Requirements

  • Requires an EventSystem in the scene for pointer input
  • Requires a GraphicRaycaster on the Canvas for pointer input
  • The Rive Panel must be under a uGUI canvas
  • This component must be placed on the same game object as the Rive Panel

Configuration

PropertyDescription
Pointer Input ModeControls whether the renderer accepts pointer input (Enable/Disable).

Properties

NameDescription
Rive PanelThe panel being rendered.

Rive Texture Renderer

Rive Texture Renderer projects Rive content onto materials in your 3D scene. It bridges the gap between Rive’s 2D rendering system and Unity’s 3D material system, making it easy to apply Rive content to any mesh in your scene.

Requirements

  • Must be placed on a GameObject with a MeshRenderer on it. e.g. a Cube, Plane, Quad, or Capsule.
  • Requires an EventSystem in the scene for pointer input
  • Requires a PhysicsRaycaster on the camera for pointer input in 3D space
  • Target GameObject needs a MeshCollider for pointer input

Configuration

FieldDescription
RendererThe Unity Renderer component (e.g., MeshRenderer,) that will display the Rive content.
Material Texture Assignment ModeControls which texture properties are set to the Rive Panel’s render texture: MainTexture sets the _MainTex property on the material. The TextureProperties option lets you select multiple specific texture properties.
Visibility OptimizationDetermines if the RivePanel should stop rendering when the mesh is not visible to the camera.
Pointer Input ModeControls whether the renderer accepts pointer input (Enable/Disable).

Properties

NameDescription
Rive PanelThe panel being rendered to materials.

Public Methods

NameDescription
SetPanel(IRivePanel panel)Assigns a new panel to render.
RefreshMaterials()Updates material references after material changes.

Render Target Strategies

Render Target Strategies control how Rive Panels render to textures. They determine whether panels get individual textures or share a texture atlas, and handle details like texture creation, panel arrangement, and memory management.

Simple Render Target Strategy

The Simple Render Target Strategy is the default rendering approach for Rive Panels, creating a dedicated render texture for each panel. It is automatically added to a Rive Panel if no custom strategy is provided.

This one-to-one mapping between panels and textures provides straightforward memory management.

The component must be attached to the same GameObject as its RivePanel

Configuration

FieldDescription
PanelThe RivePanel this strategy manages (automatically set when on same GameObject).
Draw TimingWhen rendering occurs: Batched (once per frame) or Immediate (instant updates).

Properties

NameDescription
DrawTimingCurrent draw timing mode.

Atlas Render Target Strategy

The Atlas Render Target Strategy enables multiple panels to share a single texture atlas, optimizing memory usage and draw calls.

By default, it uses a simple shelf-packing algorithm to efficiently arrange panels within the atlas, automatically growing the texture as needed while respecting maximum size constraints.

Setup

  1. Create an instance: Right-click in the scene hierarchy → Rive → Render Target Strategies → Atlas Render Target Strategy
  • Assign to panels: Drag the strategy into the Custom Render Target Strategy field on desired panels
  • (Optional) Configure atlas parameters like starting size and resolution limits

Notes

  • Panels sharing the same strategy instance share the same atlas texture
  • Create multiple strategy instances to group panels into different atlases

Configuration

FieldDescription
Starting SizeInitial dimensions of the atlas texture (e.g., 1024x1024).
Max Atlas SizeMaximum dimensions the atlas can grow to (e.g., 2048x2048).
Max Resolution Per PanelMaximum resolution for any single panel. Larger panels are scaled down (e.g., an 800x400 panel with max value of 512 becomes 512x256).
PaddingSpace between panels in the atlas to prevent texture bleeding.
Draw TimingWhen rendering occurs: Batched (once per frame) or Immediate (instant updates).
Custom Atlas Packing ProviderOptional custom packing algorithm (defaults to shelf packing if not specified).

Properties

NameDescription
Packing StrategyCurrent strategy used for arranging panels in the atlas.
Draw TimingCurrent draw timing mode.

Public Methods

NameDescription
Configure(Vector2Int startingSize, Vector2Int maxSize, int maxResPerPanel, int padding)Sets up atlas parameters before initialization.

Pooled Render Target Strategy

The Pooled Render Target Strategy optimizes memory usage by maintaining a pool of reusable render textures. Instead of creating a new texture for each panel or sharing a single atlas, this strategy draws panels to textures from a managed pool, recycling them as needed.

This approach is particularly useful for scenes with dynamic UI elements that appear and disappear frequently. For example, in a game with popup menus or tooltips that show Rive graphics, the strategy can reuse textures as UI elements are shown and hidden, avoiding constant texture allocation and deallocation.

Configuration

FieldDescription
Pooled Texture SizeSize of textures in the pool (all pooled textures share these dimensions). If a given Rive Panel doesn’t match the texture’s aspect ratio, the panel will be resized to fit within the texture while maintaining its aspect ratio.
Initial Pool SizeThe initial allocated size of the pool.
Max Pool SizeMaximum number of textures the pool can contain.
Pool Overflow BehaviorHow to handle requests when pool is full: Flexible (create temporary textures) or Fixed (reject new panels).
Draw TimingWhen rendering occurs: Batched (once per frame) or Immediate (instant updates).

Properties

NameDescription
Pool OverflowCurrent overflow behavior setting.
Pooled Texture SizeCurrent texture dimensions used by the pool.
Initial Pool SizeCurrent initial pool capacity.
Max Pool SizeCurrent maximum pool size.
Draw TimingCurrent draw timing mode.

Public Methods

NameDescription
Configure(Vector2Int textureSize, int initialSize, int maxSize, PoolOverflowBehavior behavior)Sets up pool parameters (must be called before the first Rive Panel is registered).