rive-runtime

Rive's C++ runtime — the lowest-level Rive runtime. Loads .riv files,
advances state machines and animations, and draws via the abstract
Renderer interface. The built-in GPU renderer (RiveRenderer) has
RenderContextImpl backends for Metal, Vulkan, D3D11, D3D12, and OpenGL/WebGL.
Rive's Apple, Android, Flutter, Unity, Unreal, and web runtimes all wrap this
library.
Features:
- Loading artboards and their contents from
.riv files.
- Querying state machines from artboards.
- Mutating the artboard hierarchy (the same mechanism used by state machines) and
efficiently solving those changes via
Artboard::advance.
- A state-of-the-art vector renderer for Metal, Vulkan, D3D12, D3D11, and
OpenGL/WebGL.
- An abstract
Renderer interface for hooking up an external vector renderer.
Rive overview
Rive is an agent-native 2D and 3D engine for games, apps, and interactive UI. Use it as your whole engine, or add it to the products you already have. Build with your coding agent through the Rive CLI, or draw, rig, and animate by hand with the professional design and animation tools in the Rive Editor. Both work on the same files. Open-source runtimes, no royalties or runtime fees. Rive files (.riv) play natively on web, mobile, desktop, game engines, consoles, smart TVs, and cars.
Build with your agent
Paste this into Claude Code, Codex, Cursor, or any agent that runs commands on your computer:
Install the Rive CLI from rive.app/cli. Build a game HUD as a Rive file and render it in my C++ engine with rive-runtime.
Your agent installs the Rive CLI, writes the scene, and opens a preview window that rebuilds every time it saves. Keep giving it notes, or open the same file in the Rive Editor and shape it by hand. Trying it needs no account. Writing the .riv that ships in your game needs a free Rive account. Free exports play a short Rive splash screen; paid plans export without it. See Getting started with the Rive CLI.
Prerequisites
- A C++17 toolchain:
- macOS: clang from Xcode Command Line Tools (
xcode-select --install).
- Linux: clang from your distro (e.g.
apt install clang).
- Windows: Visual Studio 2022 with the C++ Clang Compiler for Windows
and MSBuild support for LLVM (clang-cl) toolset individual components.
- git — the build script clones a pinned
premake5 on first run.
On Windows, install Git for Windows and during setup pick
"Use Git and optional Unix tools from the Command Prompt" so that
sh.exe ends up on PATH.
- Platform SDK for the renderer you're targeting:
- macOS / iOS: Xcode.
- Windows: Windows SDK (for D3D).
- Linux: a Vulkan or OpenGL development environment.
- Vulkan: the Vulkan SDK.
Build
The build is driven by premake5 wrapped by a
helper script:
build/build_rive.sh — macOS / Linux (bash) / Windows (MinGW).
build/build_rive.ps1 — a PowerShell convenience wrapper for Windows; it
shells out to the bash script, so a bash environment (Git for Windows /
MinGW, see Prerequisites) must still be on PATH.
The helper self-installs the pinned premake version on first run and dispatches
to the right build system for your platform (gmake2 on macOS/Linux, MSBuild on
Windows). It must be run from a directory that contains a premake5.lua —
typically tests/, which builds the core library, the GPU renderer, and the
player sample app.
macOS / Linux
git clone https://github.com/rive-app/rive-runtime.git
cd rive-runtime/tests
../build/build_rive.sh release
Windows
git clone https://github.com/rive-app/rive-runtime.git
cd rive-runtime\tests
..\build\build_rive.ps1 release
Common variants
(On Windows, substitute build_rive.ps1 for build_rive.sh.)
build_rive.sh (no args) — debug build for the host.
build_rive.sh release clean — clean then build release.
build_rive.sh ninja release — use Ninja instead of make/MSBuild.
build_rive.sh ios release — cross-compile for iOS.
build_rive.sh android release — cross-compile for Android (defaults to arm64).
build_rive.sh ninja release wasm — cross-compile for WebAssembly.
build_rive.sh --toolset=msc release (Windows) — build with MSVC's cl.exe
instead of clang-cl. The build supports both toolchains; the lua warning
suppressions cover MSVC too.
See the comment header at the top of
build/build_rive.sh
for the complete flag reference.
Build outputs
Artifacts land in out/<config>/ relative to the directory you built
from (typically tests/). The config directory encodes any OS/arch flags
you passed:
out/release, out/debug — host build.
out/ios_release, out/android_arm64_release, out/wasm_release —
cross-compile builds.
| Artifact |
Description |
librive.a / rive.lib |
Core runtime library. |
librive_pls_renderer.a / rive_pls_renderer.lib |
GPU renderer. |
player / player.exe |
Sample app — loads and renders a .riv file. |
out/<config>/goldens, out/<config>/gms, out/<config>/bench |
Test harness binaries (regression, golden-image, benchmarking). |
librive_decoders.a, librive_harfbuzz.a, … |
Supporting libraries. |
Testing
The runtime's primary form of testing is golden testing — rendering
known scenes and diffing the output against checked-in reference images
via the goldens and gms test harness binaries (built into
out/<config>/goldens and out/<config>/gms).
See tests/
for how to run and rebaseline goldens.
Unit tests are secondary and use the
Catch2 framework. From the repo root:
cd tests/unit_tests
./test.sh
Unit tests live in tests/unit_tests/runtime/ (core runtime) and
tests/unit_tests/renderer/ (renderer). To add a test, create an
xxx_test.cpp file in the appropriate directory — the harness picks it up
automatically.
Code formatting
rive-runtime uses clang-format.
- macOS:
brew install clang-format.
- Windows: already installed if you have the prerequisites — VS 2022's
C++ Clang Compiler component ships
clang-format.exe alongside
clang-cl.exe at
C:\Program Files\Microsoft Visual Studio\2022\<edition>\VC\Tools\Llvm\x64\bin\.
You can also install LLVM standalone from
llvm.org or via winget install LLVM.LLVM.
- Linux: install via your distro's package manager (e.g.
apt install clang-format).
Memory checks (macOS only)
To run the tests under macOS's built-in leaks tool:
cd tests/unit_tests
./test.sh memory
This wraps the test binary with leaks --atExit, which ships with macOS —
no install required. The memory flag is ignored on Linux and Windows.
Disassembly explorer (macOS / Linux)
To inspect generated assembly per cpp file, install the
Disassembly Explorer
VSCode extension. A disassemble task is provided in .vscode/tasks.json.
The underlying gen assembly task invokes clang++ directly, so it needs
clang++ on PATH — works out of the box on macOS (Xcode CLI tools) and most
Linux distros, but not on a default Windows + VS install (which provides
clang-cl.exe, not clang++.exe).
Reach the task from Tasks: Run Task, or bind a key in keybindings.json:
[
{
"key": "cmd+d",
"command": "workbench.action.tasks.runTask",
"args": "disassemble"
}
]