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

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