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
20 files changed
tree: 1745ff75131b8039824a449842c62f3471979b39
  1. .github/
  2. .vscode/
  3. build/
  4. decoders/
  5. dependencies/
  6. dev/
  7. include/
  8. renderer/
  9. rivinfo/
  10. scripting/
  11. src/
  12. tests/
  13. utils/
  14. .dockerignore
  15. .gitattributes
  16. .gitignore
  17. .lua-format
  18. .rive_head
  19. .version
  20. Doxyfile
  21. dummy.cpp
  22. LICENSE
  23. premake5_v2.lua
  24. README.md
  25. runtime.natvis
README.md

Build Status Discord badge Twitter handle

rive-runtime

Rive hero image

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.
ArtifactDescription
librive.a / rive.libCore runtime library.
librive_pls_renderer.a / rive_pls_renderer.libGPU renderer.
player / player.exeSample app — loads and renders a .riv file.
out/<config>/goldens, out/<config>/gms, out/<config>/benchTest 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"
    }
]