feat(scripting): RiveFile.artboard and globals view models from scripts (#15972) * feat(scripting): RiveFile.artboard, a decoded file's artboard a script owns A script that decodes a file with context.decodeFile could only bind its artboards (bindableArtboard), and a bound artboard gets its own main view model instance but none of its file's global view models. RiveFile.artboard (name?) instead returns an Artboard the script owns, advances, draws and forwards input to, set up the way a host sets up the artboard of a file it loads: - a top level instance from the file (artboardNamed / artboardDefault, so the file's watermark too), its default state machine, bound to the file's default instance of the artboard's view model (data() returns it) and, through StateMachineInstance::bind's completion, a default instance of each of the file's global view models. An artboard without a state machine binds the same on the artboard. - its data context has no parent: the script's own data and globals never reach it, and no two roots share an instance. - nothing advances it at creation, so a size the script sets first is the size it first lays out at. - it advances through the host's per-frame entry point (advanceAndApply(float)), as a root does, so its own scripts' async work is polled. - it pins its file, so the RiveFile can be released. - instance() on it makes another root from the file, not a copy of its live state; a view model instance passed in binds only when it belongs to that file, else the root gets a default one. The shared setup is decodedRoot / decodedRootLike in decoded_file.cpp. The wasm lane adds rive_file_v1.artboard (bindings.py, regenerated projections), minting a rive_artboard_v1 handle; AnimaScript's RiveFile gains artboard(name?). Not in this change: the Luau lane's RiveFile:artboard, script access to the root's global instances, hosted assets for decoded files, and the fetch size limit. * fix(scripting): a decoded game plays embedded, without a splash of its own A RiveFile.artboard root came from artboardNamed, so a watermarked guest froze behind its pre-roll inside the script's frame. A script's artboard is embedded content: decodedRoot and decodedRootLike (instance()) now instance through File::embeddedArtboard, which skips the watermark as bindables do. The same bytes played standalone, and the top level host, keep the splash. A root without a state machine keeps ticking while its scripts' async work is pending. Docs: instance() on a decoded artboard binds only its own file's instances. Regenerates the site REPL bundle for the std change. * test(scripting): a decoded game moves by frame two; DecodedRoot isn't assignable The rive-cli test now asserts the game and its copy advance a keyed Ticker by the frame after their first, which the pre-roll's time-zero hold blocks; the draw-path checks alone passed on the watermarked roots too. Member-wise move assignment would free the artboard before the old machine that touches it, and nothing assigns one, so it's deleted and pinned by static_assert. Trims test comments and corrects the decoded root's advance comment. * fix(scripting): a global view model read in init retries once bound A script's init runs when its artboard is instanced, before a host binds a data context. context.viewModel() and rootViewModel() answer that by asking for init to run again once a context arrives; globalViewModel() answered nil for good, in both lanes. A decoded root (RiveFile.artboard) always binds after it is instanced, so a guest script that cached a global in init never got it. globalViewModel now asks for the retry while nothing is bound, and only then: under a bound context, a name the file has no global for stays nil and init keeps its result. A host that never binds a data context leaves such a script waiting, as viewModel() already does. * feat(scripting): RiveFile:artboard in Luau The Luau twin of AnimaScript's RiveFile.artboard: a decoded file's artboard the script owns, advances, draws and forwards input to, set up by decodedRoot as in the wasm lane. ScriptReffedArtboard gains a constructor over a DecodedRoot that pins the file in every build. Its advance takes the root's per-frame entry point, and instance() makes another root from the file rather than a copy, binding a view model instance only when it is one of that file's. The typings return Artboard<ViewModel?>?, so data reads as optional. The rive-cli test plays the decoded game in both lanes and expects the same draws. * fix(scripting): RiveFile.artboard leaks nothing, matches whole names, decodes less Review fixes: - Luau made a decoded root before its userdata, so a failed allocation, which longjmps past C++ destructors, leaked the artboard, machine, view model and file. file:artboard() and instance() now make the root inside the ScriptedArtboard constructor, after the allocation. - Names reached the lookups as C strings, so "Game\0Other" found Game. decodedRoot, decodedBindable and hostBindableArtboard take the name's length, in both lanes, so artboard() and bindableArtboard() match the whole name. - decodedRootLike compared File::artboard(i), which decodes each deferred body before the match. It compares headers with handsOut, as ArtboardComponentList does. Decoded files don't defer bodies today, so this only showed under RIVE_LAZY_DECODING. * fix(scripting): a Luau animation keeps its artboard; a bare decoded root gets a context Review fixes: - A Luau Animation held only its LinearAnimationInstance, so a script that kept one after dropping its artboard played into a freed artboard, and for a decoded root into its freed file's definitions. ScriptedAnimation now keeps the ScriptReffedArtboard, as the wasm lane's HostAnimation keeps its HostArtboard, and is made inside its userdata. - A decoded root with no machine, view model or globals was left without a data context, so a guest script asking for a global in init waited for one forever. bindRoot gives it an empty context, as binding a machine does. --------- Co-authored-by: Guido Rosso <guido@rive.app> Rive-Mono-Commit: c57f201d4833d49b09e8edb6de39ab7246155e9b

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:
.riv files.Artboard::advance.Renderer interface for hooking up an external vector renderer.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.
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.
xcode-select --install).apt install clang).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.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.
git clone https://github.com/rive-app/rive-runtime.git cd rive-runtime/tests ../build/build_rive.sh release
git clone https://github.com/rive-app/rive-runtime.git cd rive-runtime\tests ..\build\build_rive.ps1 release
(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.
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. |
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.
rive-runtime uses clang-format.
brew install clang-format.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.apt install clang-format).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.
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" } ]