Rive Runtime runtime-v0.1.165
feat(focus): ui pass 1 (#13029) 72963a4d12 * core updates * wip * icons * rebased * rive remote and initial value fix * forgot the riv... * feat(editor): stage focus overlay indicating focus during playback Add a corner-bracket overlay on the design stage that shows where focus is while a state machine plays, without needing to wire focus state through view model properties. - Blue brackets around a directly focused element in the active artboard - Grey brackets around a nested artboard/component when focus is contained within it (matched via shared focus-node identity) - d-pad next/previous now wakes the stage so the bracket updates immediately instead of only on hover * feat(focus): unify focus listener actions, add Clear focus, and focus transition conditions Editor + core changes for focus authoring in state machines: Listener actions - Merge the separate "Focus Target" and "Focus Traversal" listener behaviours into a single "Focus" action with a leading mode combo (target / traverse / clear). Combos size to their widest option. - Add a new FocusActionClear core type (Dart + C++ runtime + rml) that clears the artboard focus at runtime. Viewport - Move the "Focus Indicator" option above "Show Final Playback" via a decoupled ViewportOption.displayOrder (enum declaration order stays fixed for the persisted bitmask). Transition conditions - Add a "Focus" left-hand condition option (in the artboard section, behind the focusManagement flag): `focus == / != <focusable component>`, with a right-hand dropdown listing components that have a FocusData child. - New TransitionFocusCondition core type (extends TransitionViewModelCondition), reusing a component comparator to store the target. Self-contained evaluation in Dart and C++ (queries FocusManager::hasPrimaryFocus); added a const focusManager() accessor on StateMachineInstance. Registered in rive_core, runtime, and rml core registries. Note: focus_overlay.dart carries a small pre-existing change (gating the overlay on the focusBrackets viewport option) included with this branch's focus work. * review: address Copilot feedback on focus condition - TransitionFocusCondition (Dart): resolve the target component comparator from either the right OR left slot, matching the C++ runtime. A .riv re-imported into the editor assigns the single exported comparator to the left slot, which previously made target/validateCondition/evaluate/uniqueId treat the condition as invalid and always evaluate false. - state_machine_manager: focus condition create/select helpers now use the slot-agnostic targetComparator so editing an imported focus condition works. - StageViewport: assert ViewportOption.displayOrder contains every option so a future enum addition can't silently drop a toggle from the menus. * fix(editor): remove unused imports failing flutter analyze CI runs `flutter analyze --no-fatal-infos --fatal-warnings`, which promoted two unused_import warnings in focus_data_inspector_builder.dart (component.dart and core_text_field.dart) to fatal errors. Neither symbol is referenced; removed them so the editor analyze step passes. * test(editor): allowlist condition_row.dart in theme rename audit The new `_FocusConditionFlow` paints `colors.warning` (0xFFF6C566) on its node connectors in the invalid state, mirroring `_DataPropertyFlow` — a legitimate +1 warning-hex site vs mainline, not a rename miswire. Add condition_row.dart to the audit allowlist with a justification (baseline regeneration only applies to changes already on mainline). * test(editor): allowlist backboard_inspector_builder.dart in theme rename audit The focus feature removed the legacy _FocusButton / _DPad / _DPadButton widgets from the backboard inspector (superseded by per-component focus authoring). Those widgets held all of the file's RiveColors sites (border, trackEmphasis, textSecondary x2 each), so the branch paints 0 vs mainline's 6 — an intentional removal, not a rename. Add it to the audit allowlist with a justification. * chore(rive_core): regenerate core from defs (focus types) * fix(core): reassign focus type keys to avoid collision with master Master's data-bind font PR (#13031) added ViewModelPropertyAssetFont (1034) and ViewModelInstanceAssetFont (1035), which now collide with the focus types introduced here. Reassign FocusActionClear -> 1037 and TransitionFocusCondition -> 1038 (next free keys after master's 1036) in the defs and generated base files (Dart + runtime + rml). Registrations reference the typeKey constants, so no other changes are needed. * style(runtime,rml): clang-format focus C++ files * test(runtime): add C++ tests for FocusActionClear and TransitionFocusCondition * test(runtime): avoid ODR-use of TransitionFocusCondition typeKey static * runtime test * feedback Co-authored-by: Alex Gibson <agibson.uk@gmail.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" } ]