Rive Runtime: A Low-Level C++ Renderer and State Machine Engine

What It Solves and Who It Is For

Rive Runtime is the lowest-level C++ implementation of Rive's animation system. It solves the problem of taking a .riv file and turning it into interactive graphics: it loads artboards, queries state machines, mutates the artboard hierarchy, and advances animations via Artboard::advance. The built-in GPU renderer, called RiveRenderer, draws the results through RenderContextImpl backends for Metal, Vulkan, D3D11, D3D12, and OpenGL/WebGL. This is not a drop-in player for end users. It is a library for engineers who need to embed Rive content into a custom engine, a game engine, or a platform that the official wrappers do not cover. The README states that Rive's Apple, Android, Flutter, Unity, Unreal, and web runtimes all wrap this library, so this is the foundation those higher-level integrations build on. If you are not writing C++ or do not need to control the render loop yourself, this is the wrong layer to start with.

How the Renderer and State Machine Fit Together

The core runtime is separate from the renderer. The runtime loads and advances the artboard, and the renderer draws it. The abstract Renderer interface lets you plug in an external vector renderer if the built-in GPU renderer does not fit. The built-in renderer is the interesting part: it claims to be a state-of-the-art vector renderer, and it has multiple backends, meaning the same drawing commands are translated to Metal, Vulkan, D3D11, D3D12, or OpenGL/WebGL depending on the platform. The state machine mutation mechanism is the same one used by state machines, and Artboard::advance efficiently solves those changes. That suggests a data-driven approach where you modify the artboard hierarchy and then advance to recompute the resulting geometry. The documentation does not give a deeper data flow diagram, so the exact pipeline from .riv file to rendered pixels is not fully specified here. But the separation between core and renderer is clear, and the existence of a RenderContextImpl abstraction implies that each GPU backend handles resource creation and command submission in its own way.

Building with Premake5 and the Helper Scripts

The build is not a plain CMake or Makefile. It uses premake5, but you do not install it yourself. The helper script build/build_rive.sh (or build_rive.ps1 on Windows) self-installs a pinned premake version on first run. You must run the script from a directory that contains a premake5.lua, typically tests/. The README gives concrete commands. On macOS or Linux: git clone, cd tests, then ../build/build_rive.sh release. On Windows PowerShell: ..\build\build_rive.ps1 release. The script dispatches to gmake2 on macOS/Linux and MSBuild on Windows. A notable variant is build_rive.sh ninja release to use Ninja instead of make or MSBuild. Cross-compilation targets include ios, android (defaults to arm64), and wasm. On Windows, you can also build with MSVC's cl.exe by passing --toolset=msc, which is useful if you cannot use clang-cl. The build outputs land in out/<config>/ relative to the build directory, with config names like release, debug, ios_release, android_arm64_release, and wasm_release. The main artifacts are librive.a or rive.lib for the core, librive_pls_renderer.a or rive_pls_renderer.lib for the GPU renderer, and a player sample executable.

Testing: Golden Images First, Unit Tests Second

The primary testing strategy is golden testing. The README says the runtime's primary form of testing is rendering known scenes and diffing the output against checked-in reference images, via the goldens and gms test harness binaries. These are built into out/<config>/goldens and out/<config>/gms. This is a strong approach for a renderer, because it catches subtle visual regressions that unit tests might miss. Unit tests are secondary and use Catch2. You run them from tests/unit_tests with ./test.sh. New unit tests are picked up automatically if you create an xxx_test.cpp file in tests/unit_tests/runtime/ or tests/unit_tests/renderer/. There is also a macOS-only memory check: ./test.sh memory wraps the test binary with leaks --atExit. On Linux and Windows, that flag is ignored. If you adopt this library, you should expect to run the golden tests as part of your CI, because they are the main quality gate. The documentation does not explain how to rebaseline goldens in detail, only that you should see tests/ for how to run and rebaseline.

Platform Prerequisites and a Windows Quirk

The prerequisites are specific. You need a C++17 toolchain: clang from Xcode on macOS, clang from your distro on Linux, and on Windows, Visual Studio 2022 with the C++ Clang Compiler for Windows and MSBuild support for LLVM (clang-cl) toolset components. Also, git is required because the build script clones a pinned premake5 on first run. On Windows, you must install Git for Windows and during setup choose "Use Git and optional Unix tools from the Command Prompt" so that sh.exe ends up on PATH. This is a real friction point: the PowerShell wrapper build_rive.ps1 still shells out to the bash script, so a bash environment must be on PATH. That means even on Windows, you are not free of Unix tools. The README also notes that the disassembly explorer task in .vscode/tasks.json invokes clang++ directly, which works on macOS and most Linux distros but not on a default Windows + VS install, because that provides clang-cl.exe, not clang++.exe. So if you rely on that VSCode task on Windows, you need to install LLVM standalone or adjust the path.

Limitations and When It Is the Wrong Tool

This is a low-level library, and that carries costs. There is no high-level scene graph or player widget. You must manage the render context, the artboard, and the advance loop yourself. The documentation does not describe a public API for loading a .riv file beyond saying it loads artboards, so you will need to read the headers or examples. The renderer backends are GPU-specific, and you must have the corresponding platform SDK: Windows SDK for D3D, Vulkan SDK for Vulkan, Xcode for Metal. If you target a platform without one of these, the built-in renderer will not work, and you must write your own Renderer implementation. Also, the build system is unusual: premake5 is pinned and self-installed, which can be a problem in air-gapped or strictly controlled build environments. The golden test workflow requires checked-in reference images, which means you need a process for updating them when you intentionally change rendering behavior. That is not trivial. If you just need to show Rive animations in a web page or a mobile app, use the official wrappers. This library is for people who need to integrate at the C++ level and are willing to deal with the build and testing complexity.

Alternatives and How They Differ

The obvious alternative is to use one of the higher-level Rive runtimes, such as the Flutter or Unity packages, which wrap this library. Those give you a ready-made component that handles the render loop and platform specifics. The difference is architectural: the wrappers hide the Artboard::advance and Renderer interface, so you lose direct control but gain convenience. Another alternative is to use a different vector animation format, like Lottie with the lottie-web or lottie-android libraries. Lottie renders JSON-based animations and has a different runtime model: it uses the platform's native rendering (often Canvas or Core Animation) rather than a custom GPU renderer. Rive's approach with a custom GPU renderer can produce more consistent results across platforms, but it requires the backend support that Rive provides. If you need to render .riv files and you are not willing to write C++ code, Lottie is not a drop-in replacement because it does not read .riv files. The real choice is between using this low-level runtime directly or using a wrapper that already exists for your platform. The README lists the wrappers, so you should check if your target is covered before going low-level.

Maintenance, Upgrades, and License

The repository is under the MIT license, which is permissive and allows commercial use without a copyleft requirement, but it does not include a patent grant or warranty, so you should review the full license text before shipping. The project is not archived and has a main branch, but the material does not include recent release tags or a changelog, so the release cadence is unknown. The build script pins a specific premake5 version, which suggests that upgrades to premake5 are deliberate and may require changes if you update the script. The README does not describe a migration path for version upgrades. You will need to track upstream changes by watching the main branch or the repository commits. The code formatting is enforced with clang-format, and the project provides a .vscode task for disassembly exploration, which indicates a developer workflow that expects clang-format to be installed. The goldens are checked in, so upgrading the renderer may require rebaselining images, which is a maintenance cost you should budget for. The unit test harness automatically picks up new test files, which is convenient for adding your own tests. Overall, the maintenance burden is moderate: you need to keep the build environment aligned with the pinned premake and the clang toolchain, and you need to manage golden image updates when you upgrade.

Editorial conclusion

Adopt rive-runtime if you are building a custom engine or platform that must consume Rive content and need direct access to the core state machine and renderer. Avoid it if you just want to display .riv files in an existing framework; use the official Apple, Android, Flutter, Unity, Unreal, or web runtimes instead. Before adopting, verify that the target platform has a supported renderer backend (Metal, Vulkan, D3D11, D3D12, OpenGL/WebGL) and that the build prerequisites, especially the pinned premake5 and Git for Windows setup, match your CI environment. Also check the golden test workflow, because that is the primary quality gate and rebaselining requires careful review.

Official sources

1. Official README
2. Project repository