scripting: library scope for imported scripts (#13054) d24376c1d6 * scripting: scope-aware module resolution so versioned library scripts coexist * scripting: 64-bit library scope on FileAsset (new uint64 core type) read by ScriptAsset::scope * scripting: unresolved library: require errors instead of rebinding to caller scope * scripting: use lib: qualifier prefix instead of library: * scripting: scoped setScriptSource overload, scope resolution maps, and scope tests * scripting: plumb library scope from editor assets to the workspace via a cancellation-proof setScriptScope work * scripting: recycle setScriptScope work directly, it has no consumer to ring * scripting: infer resolves requires with the caller's scope, divergence from parse-time edges races module rechecks * scripting: library scope flows into the editor VM and host proxies so lib: requires resolve * scripting: scope-aware require autocomplete and derive proxy scope from the library link for older imports * scripting: LibraryFolder core type roots a library's scope, scripts derive it by parentage and the panel synthesizes the internal tree * editor: show the library version suffix on the library folder instead of every script row * editor: deleting any part of an imported library removes the whole library, confirmed and journaled * scripting: colon-free scoped chunknames, tooling parses trace locations as chunkname:line * editor: library folder is the per-library container in custom and source views, holds artboards, uses the library icon * editor: unify the library tree item onto LibraryAsset itself, scope and panel and inspector all hang off the one core object * editor: source view data pass includes libraries, it previously kept only group items * editor: regenerate the preview runtime file when blob bytes arrive after it was generated * core: reseed nextObjectId when chunked sync completes, the connected reseed walks an empty object set * core: corrupt-scrubbed objects keep their ids consumed and log, regenerated content collided with their server copies * core: abandon rejected changesets, a persisted reject replays on every connect and loops forever * code: derived char ids fall back to a fresh reserved range when occupied, files written without per-rune reservation collide on split * editor: definition jump opens the file's library proxy tab, the internalCore instance has no workspace wiring so it rendered unhighlighted * core,editor: strip temporary id allocation diagnostics * docs: cut comments down to why-only one liners * core: drop the sync complete reseed, ready always follows sync so the connected reseed sees every consumed id * runtime: clear the registered module's key from each dependent's missing set, the wrong receiver left dependents pending * tests: drop the draco checkout dependency, a synthetic scoped storm covers the race and scope tests use a generic library * defs: scope keys declare uint64 in both def sets, the editor generator folds uint64 to a Dart int like uint8 * runtime: scope the require cache key so it destructs before luaL_error longjmps, five strings leaked per failed require * code: char id fallback checks only the derived id, range checking tripped on legitimate overlap splits and detached runs * editor tests: stub library 999 details, library assets now surface in the panel so the update tracker checks them * core: abandon on reject moves to its own PR * scripting: lib: requires resolve through per caller import edges, a serialized LibraryAsset is the edge so files carry their own pins * scripting: source storms defer the check flush and the checker pool widens to eight * editor: busy state stacks across compiles and checks so the spinner holds until reports land * fix(libraries): nested edges derive their caller scope from the owning core * editor: warn when a script name shadows a reserved module pattern * editor: scripts covered by the library confirmation skip their own delete prompt * editor: badge reserved script names in the asset tree like invalid view model names * editor: reserved script name badge tips immediately like the data tree * editor: reserved name badge moves to the icon overlay, the icon slot ignores pointers so its tip never hovered * core_generator: derived properties serialize through their overridden getters * fix(editor): script-less files skip the problem report round trip, the busy spinner froze settle-based tests * fix(editor): empty problem clear skips the notify, and the badge halo joins the color baseline * test(editor): first connect report assertion polls, the fixed delay flaked under CI load * test(editor): drop shadowed mock_rive_api import, the analyze gate failed shard 0 on every run Co-authored-by: Luigi Rosso <luigi-rosso@users.noreply.github.com>

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.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" } ]