rive-runtime

rive-runtime is the lowest-level C++ runtime for Rive. It is responsible for loading .riv files, advancing state machines and animations, and handling drawing via an abstract Renderer interface.

Key capabilities include:

• Loading artboards and contents from .riv files.
• Querying state machines from artboards.
• Mutating the artboard hierarchy and solving changes via Artboard::advance.
• A high-performance vector renderer with RenderContextImpl backends for Metal, Vulkan, D3D11, D3D12, and OpenGL/WebGL.
• An abstract Renderer interface that allows developers to hook up their own external vector renderer.

The WebGPU port provides WebGPU bindings for Emscripten, including the webgpu.h header provided by emdawnwgpu. You can integrate this into your Emscripten build process using either a local port file or a remote port file via the --use-port flag.

# Using a remote port
--use-port=[your_path]/webgpu-remoteport.py

# Using a local port
--use-port=[your_path]/webgpu-port.py

To use the Rive Renderer, you must first clone the main rive-runtime repository and navigate to the renderer directory.

git clone https://github.com/rive-app/rive-runtime.git
cd rive-runtime/renderer

You can build the renderer in release mode and run the path_fiddle example by passing a .riv file as an argument.

build_rive.sh release
out/release/path_fiddle [/path/to/my.riv]

On macOS, you can run tests under the built-in leaks tool to check for memory leaks. This wraps the test binary with leaks --atExit.

cd tests/unit_tests
./test.sh memory

Note: The memory flag is ignored on Linux and Windows.

Before building, ensure you have the following installed based on your platform:

C++17 Toolchain

• macOS: clang from Xcode Command Line Tools (xcode-select --install).
• Linux: clang from your distribution (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

• git is required. The build script clones a pinned premake5 on the first run.
• Windows Users: Install Git for Windows and select "Use Git and optional Unix tools from the Command Prompt" during setup to ensure sh.exe is on your PATH.

Platform SDKs

• macOS / iOS: Xcode.
• Windows: Windows SDK (for D3D).
• Linux: A Vulkan or OpenGL development environment.
• Vulkan: The Vulkan SDK.

Golden Testing

Primary testing is done via golden testing, which renders known scenes and compares them against reference images. Use the goldens and gms binaries found in out/<config>/ to run these tests.

Unit Testing

Unit tests use the Catch2 framework. To run them, navigate to the tests/unit_tests directory and execute the test script:

cd tests/unit_tests
./test.sh

Unit tests are located in:

• tests/unit_tests/runtime/ (core runtime)
• tests/unit_tests/renderer/ (renderer)

To add a new test, create an xxx_test.cpp file in the appropriate directory; the harness will detect it automatically.

The build process requires the build_rive.sh script, which is located in the ../build directory relative to the renderer folder. Add this directory to your $PATH to make the script accessible.

export PATH="$PATH:$(realpath ../build)"

To build the renderer for WebGL2 using WebAssembly (WASM), use the ninja wasm release flags. Once built, navigate to the output directory and start a local Python HTTP server to view the results.

build_rive.sh ninja wasm release
cd out/wasm_release
python3 -m http.server 5555

The build process is driven by premake5 using helper scripts. You should run these scripts from a directory containing premake5.lua (typically the tests/ directory) to build 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

The WebGPU port optionally provides Wagyu extensions via the webgpu_wagyu.h header. These extensions are specific to Wagyu use cases and are not part of the WebGPU standard. To enable them, pass the wagyu=true option to the --use-port flag using colon-delimited key=value pairs.

--use-port=webgpu-remoteport.py:wagyu=true

The build_rive.sh (macOS/Linux/MinGW) and build_rive.ps1 (Windows) scripts support various build configurations.

Note for Windows: Substitute build_rive.ps1 for build_rive.sh in the commands below.