Rive Hello World

` element immediately after your canvas — or use the browser's accessibility tree inspector. For a full checklist, see [Testing Semantics](/docs/editor/accessibility/semantics#testing-semantics) in the editor documentation. # State Machine Playback Source: https://rive.app/docs/runtimes/web/state-machines Playing a state machine For more information on designing and building state machines in the Rive editor, please refer to [State Machine Overview](/docs/editor/state-machine). A Rive state machine is a set of animation states and the transitions between them. At runtime there is limited ability to observe or modify the state directly. This is by design, as this would limit the ability of a designer in Rive to modify the state machine without creating breaking changes. Instead, state machines are indirectly controlled through transitions conditioned on Data Binding properties. A designer assigns a default state machine for each artboard in the Rive editor. They may create multiple state machines, each representing a different configuration of states and transitions. When rendering a Rive file and artboard, you may choose which state machine to play. If no state machine is specified, the default state machine for that artboard is used. ## Controlling Playback State machines play by "advancing" over time. This is done once per frame by the amount of time between frames. For example, for a graphic running at 60 frames per second, the state machine would be advanced by approximately 16.67 milliseconds (1/60th of a second) each frame. This advancing evaluates keyframes, transitions, data bindings changes, and ultimately the visible artboard elements to create the illusion of motion over time. This runtime provides a way to control whether the state machine is playing. When paused or stopped, the state machine does not advance and the last rendered frame remains visible. When playing from pause, the state machine resumes from where it left off, whereas when playing from stop, it restarts from the entry state. In addition to the paused/stopped state, state machines may also "settle". This is an optimization where the Rive runtime detects that no further changes will occur (for example, if there are no active transitions or animations). While settled the state machine will also stop advancing. This improves performance and energy use by avoiding unnecessary calculations. State machines are unsettled by external actions that change their state, such as user input or data binding changes. You can additionally force a state machine to unsettle by calling play, though it may immediately re-settle if there is no further work to be done. ## Playing State Machines ### Autoplay the State Machine To autoplay a state machine immediately after it loads, simply set `autoplay` to `true`. ```js theme={null} const r = new rive.Rive({ src: 'https://cdn.rive.app/animations/vehicles.riv', canvas: document.getElementById('canvas'), autoplay: true, stateMachines: 'bumpy', onLoad: () => {} }); ``` ### Controlling State Machine Playback You can manually play and pause the State Machine using the `play`, `pause`, and `stop` methods. ```js theme={null} const r = new rive.Rive({ src: 'https://cdn.rive.app/animations/vehicles.riv', canvas: document.getElementById('canvas'), stateMachines: 'bumpy', onLoad: () => {} }); const handlePlay = () => { r.play() } const handlePause = () => { r.pause() } const handleStop = () => { r.stop() } ``` ### reset() To dispose the current artboard / animation / state machine instances and create fresh ones (optionally changing artboard or `stateMachines`), use **`reset()`**. Pass the same kinds of options you use on the constructor. See [Rive Parameters](/docs/runtimes/web/rive-parameters) for the full **`RiveResetParameters`** fields (`artboard`, `stateMachines`, `autoplay`, `autoBind`). ```js theme={null} r.reset({ stateMachines: 'bumpy', autoplay: true, }); ``` # Getting Started Source: https://rive.app/docs/runtimes/web/web-js JavaScript/WASM runtime for Rive. Note that certain Rive features may not be supported yet for a particular runtime, or may require using the Rive Renderer. For more details, refer to the [feature support](/docs/feature-support/) and [choosing a renderer](/docs/runtimes/choose-a-renderer/) pages. ## Overview This guide documents how to get started using the Rive web runtime library. The runtime is open source and available in this [GitHub repository](https://github.com/rive-app/rive-wasm). This library has a high-level JavaScript API (with TypeScript support) and a low-level API to load in Web Assembly (WASM) and control the rendering loop yourself. This runtime allows you to: * Quickly integrate Rive into all web applications (Webflow, WordPress, etc.) * Provides a base API to build other web-based Rive runtime wrappers (React, Svelte, etc.) * Support advanced use cases by controlling the render loop (web-based game engines) ## Getting started Follow the steps below to integrate Rive into your web app. The following instructions describe using the `@rive-app/webgl2` package. Rive provides web-based packages like WebGL2, Canvas, and Lite versions. See [Canvas vs WebGL2](/docs/runtimes/web/canvas-vs-webgl) for guidance on which package is the correct choice for your use case. We recommend always using the [latest version](https://www.npmjs.com/package/@rive-app/webgl2) when possible. The versions listed below and in the examples may differ from the latest. You van find the latest version on [npmjs](https://www.npmjs.com/package/@rive-app/webgl2?activeTab=versions). **(Recommended) Load v2 of the web runtime** Add the following script tag to your web page to load v2 of the web runtime, which will get the latest patches/minor updates on major version 2: ```html theme={null} ``` If you see a newer major version to upgrade to, ensure your code accounts for breaking changes in the migration guide **Load a pinned version of the web runtime** Alternatively, pin to a specific version for more control over what is loaded in your app. As Rive's feature set grows, you'll want to manually update this version to a newer one to ensure best compatibility. ```html theme={null} ``` This will make a global `rive` object available, allowing you to access the Rive API via the `rive` entry point. Follow the next steps below. ```bash npm theme={null} npm install @rive-app/webgl2 ``` ```bash pnpm theme={null} pnpm add @rive-app/webgl2 ``` ```bash yarn theme={null} yarn add @rive-app/webgl2 ``` ```bash bun theme={null} bun add @rive-app/webgl2 ``` ```javascript Importing theme={null} // Import the entire module under the global identifier `rive` import * as rive from "@rive-app/webgl2"; // Alternatively, import only the specific parts you need import { Rive } from "@rive-app/webgl2"; ``` Not using [Rive Text](/docs/editor/text/), [Rive Layouts](/docs/editor/layouts/), [Rive Scripting](/docs/scripting/), or [Rive Audio](/docs/editor/events/audio-events)? Consider using [@rive-app/canvas-lite](/docs/runtimes/web/canvas-vs-webgl#rive-app-webgl2-lite) instead, which is a smaller package variant of our canvas runtime. Add a canvas element to your HTML where you want the Rive graphic to be displayed: ```html theme={null}

``` To create a new instance of a Rive object, provide the following properties: * `src`: A string representing the URL of the hosted `.riv` file (as shown in the example below) or the path to the public asset `.riv` file. For more details, refer to [Rive Parameters](/docs/runtimes/web/rive-parameters) on how to properly use this property. * `artboard` - (Optional) A string representing the artboard you want to display. If not supplied, the default artboard from the `.riv` file is selected. * `stateMachines` - A string representing the name of the state machine you wish to play. This must be supplied, or the Rive instance may only play the first linear animation it finds. In the next major version, the default behavior will be to play the default state machine of the artboard. * `canvas` - The canvas element where the animation will be rendered. * `autoplay` - A boolean indicating whether the animation should play automatically. * `autoBind` - A boolean indicating whether to automatically data-bind the default `ViewModelInstance` if one is found. We recommend setting this to `true`. ```javascript theme={null} ``` The `resizeDrawingSurfaceToCanvas` method ensures that the Rive animation is correctly scaled to fit the dimensions of the specified canvas element. By default, the canvas rendering surface might not match the exact size of the `

### Complete example Bringing it all together, here's how to load a Rive graphic in a single HTML file. ```html theme={null} Rive Hello World

``` ### Loading Rive files [See this example](https://codesandbox.io/p/sandbox/rive-quick-start-js-xmwcm6?file=%2Fsrc%2Findex.ts) for the different ways to load in a .riv file, the options are: 1. **Hosted URL**: Use a string representing the URL where the `.riv` file is hosted. Set this as the `src` attribute when creating a new Rive instance. 2. **Static Assets in the bundle**: Provide a string with the path to a publicly accessible `.riv` file within your web project. Handle `.riv` files just like any other static asset (e.g., images or fonts) in your project. 3. **Fetching a file**: Instead of using the `src` attribute, use the `buffer` attribute to load an `ArrayBuffer` when fetching a file. This is useful when reusing the same `.riv` file across multiple Rive instances, allowing you to load it only once. 4. **Reusing a Loaded File**: Use the `rivFile` parameter to reuse a previously loaded Rive runtime file object, avoiding the need to fetch it again via the `src` URL or reload it from the `buffer`. This can significantly improve performance by eliminating redundant network requests and loading times, especially when creating multiple Rive instances from the same source. Unlike the `src` and `buffer` parameters, which require parsing under the hood to create a runtime file object, the `riveFile` parameter uses an already parsed object, including any loaded assets. See [Caching a Rive File](/docs/runtimes/web/caching-a-rive-file). For more details, refer to the [Rive Parameters](/docs/runtimes/web/rive-parameters) section on the `src` property. ## Clean up Rive When working with a Rive instance, it's important to properly clean it up when it's no longer needed. This is especially necessary in scenarios where: * The UI containing Rive animations is no longer needed (e.g., when a modal with Rive graphics is closed). * The animation or state machine has completed and will not be shown or run again. Under the hood, Rive creates various low-level objects (such as artboard instances, animation instances, and state machine instances) in C++, which need to be manually deleted to prevent memory leaks. If not cleaned up, these objects can consume unnecessary resources, potentially impacting your application's performance. Fortunately, the high-level JavaScript API simplifies this process. You don't need to track every object created during the Rive instance lifecycle. Instead, you can clean up all associated objects with a single method call. To clean up a Rive instance and free up resources, simply call the following method on your Rive instance: ```javascript theme={null} const riveInstance = new Rive({...)); ... // When ready to cleanup riveInstance.cleanup(); ``` # Additional Rive web resources More in-depth Rive web documentation and advanced use cases. # Examples * [Basic gallery app](https://github.com/rive-app/rive-wasm/tree/master/js/examples/_frameworks/parcel_example_canvas) * [Tracking mouse cursor](https://codesandbox.io/p/sandbox/tracking-mouse-cursor-n38gdd?file=%2Fsrc%2Findex.ts) * [Connecting to page scroll](https://codesandbox.io/p/sandbox/rive-page-scroll-h4msqw?file=%2Fsrc%2Findex.ts%3A27%2C45) * [Playing state machine only when scrolled into the user's viewport](https://codesandbox.io/p/sandbox/rive-wait-for-scroll-into-view-y9wg8d?file=%2Fsrc%2Findex.ts) # Animation Source: https://rive.app/docs/scripting/api-reference/artboards/animation ## Fields ### `duration` The duration of the animation. ```lua highlight={3} theme={null} function advance(self: AnimationExample, seconds: number): boolean if self.anim print(self.anim.duration) end return true end ``` ## Methods ### `advance`

```lua theme={null} advance(seconds: number) -> boolean ```

Advances the animation by the given time in seconds. Returns true if the animation hasn't reached its end. If the animation is set to loop or ping pong, it will always return true ```lua highlight={23} theme={null} type AnimationExample = { -- Artboard input, assigned in the Rive editor by the designer character: Input>, -- The live instance and its animation artboardInstance: Artboard?, anim: Animation?, } function init(self: AnimationExample, context: Context): boolean self.artboardInstance = self.character:instance() if self.artboardInstance then self.anim = self.artboardInstance:animation('Idle') end return true end function advance(self: AnimationExample, seconds: number): boolean if self.anim and self.artboardInstance then -- Advance the animation to apply keyframe values to the artboard self.anim:advance(seconds * 2) -- Advance the artboard with 0 to propagate changes without double-counting time self.artboardInstance:advance(0) end return true end function draw(self: AnimationExample, renderer: Renderer) if self.artboardInstance then renderer:save() self.artboardInstance:draw(renderer) renderer:restore() end end return function(): Node return { character = late(), artboardInstance = nil, anim = nil, init = init, advance = advance, draw = draw, } end ``` ### `setTime`

```lua theme={null} setTime(time: number) -> () ```

set the animation time in seconds ```lua highlight={4} theme={null} function advance(self: AnimationExample, seconds: number): boolean if self.anim and self.artboardInstance then -- Set the animation to a specific time in seconds self.anim:setTime(0.3) -- Advance the artboard with 0 to propagate changes without double-counting time self.artboardInstance:advance(0) end return true end ``` ### `setTimeFrames`

```lua theme={null} setTimeFrames(frames: number) -> () ```

set the animation time in frames ```lua highlight={4} theme={null} function advance(self: AnimationExample, seconds: number): boolean if self.anim and self.artboardInstance then -- Set the animation to a specific frame self.anim:setTimeFrames(3) -- Advance the artboard with 0 to propagate changes without double-counting time self.artboardInstance:advance(0) end return true end ``` ### `setTimePercentage`

```lua theme={null} setTimePercentage(percentage: number) -> () ```

set the animation time as a percentage of the duration ```lua highlight={4} theme={null} function advance(self: AnimationExample, seconds: number): boolean if self.anim and self.artboardInstance then -- Set the animation to a specific percentage of the duration. self.anim:setTimePercentage(.5) -- Advance the artboard with 0 to propagate changes without double-counting time self.artboardInstance:advance(0) end return true end ``` # Artboard Source: https://rive.app/docs/scripting/api-reference/artboards/artboard Represents a Rive artboard instance, providing drawing, advancing, interaction handling, and access to named nodes and data. ## Fields ### `frameOrigin` If true, the artboard’s origin is treated as the frame origin. ```lua highlight={6} theme={null} function init(self: RenderInstance, context: Context): boolean local vm = Data.Character.new() self.instance = self.character:instance(vm) if self.instance then self.instance.frameOrigin = true end return true end ``` ### `data` The typed data associated with the artboard. ```lua highlight={9,10,11,12} theme={null} function init(self: RenderInstance, context: Context): boolean local vm = Data.Character.new() self.instance = self.character:instance(vm) if self.instance then self.instance.frameOrigin = true local data = self.instance.data if data then print(data.nickname) end end return true end ``` ### `width` The width of the artboard. ```lua theme={null} self.instance = self.character:instance(vm) if self.instance then print(self.instance.width) end end ``` ### `height` The height of the artboard. ```lua theme={null} self.instance = self.character:instance(vm) if self.instance then print(self.instance.height) end end ``` ## Methods ### `draw`

```lua theme={null} draw(renderer: Renderer) -> () ```

Draws the artboard using the provided renderer. ```lua highlight={20} theme={null} type RenderInstances = { character: Input>, instance: Artboard?, } function init(self: RenderInstances, context: Context): boolean local vm = Data.Character.new() self.instance = self.character:instance(vm) return true end function draw(self: RenderInstances, renderer: Renderer) local instance = self.instance if instance then renderer:save() instance:draw(renderer) renderer:restore() end end return function(): Node return { character = late(), instance = nil, init = init, draw = draw, } end ``` ### `advance`

```lua theme={null} advance(seconds: number) -> boolean ```

Advances the artboard by the given time in seconds. Returns true if the artboard should continue receiving advance calls. ```lua highlight={17} theme={null} type RenderInstances = { character: Input>, instance: Artboard?, } function init(self: RenderInstances, context: Context): boolean local vm = Data.Character.new() self.instance = self.character:instance(vm) return true end function advance(self: RenderInstances, seconds: number): boolean if self.instance then return self.instance:advance(seconds) end return true end return function(): Node return { character = late(), instance = nil, init = init, advance = advance, } end ``` ### `instance`

```lua theme={null} instance(viewModel: ViewModel?) -> Artboard ```

Creates a new instance of the artboard with independent state. ```lua highlight={8} theme={null} type ViewModelExample = { character: Input>, instance: Artboard?, } function init(self: ViewModelExample, context: Context): boolean local vm = Data.Character.new() self.instance = self.character:instance(vm) return true end return function(): Node return { character = late(), instance = nil, init = init, } end ``` ### `animation`

```lua theme={null} animation(name: string) -> Animation? ```

Creates an animation instance linked to the artboard instance ### `bounds`

```lua theme={null} bounds() -> (Vector, Vector) ```

Returns the bounding box of the artboard as two [Vector](/docs/scripting/api-reference/vector/vector) values: the minimum point and the maximum point. ```lua theme={null} local minPt, maxPt = self.instance:bounds() print("Bounds width", maxPt.x - minPt.x) print("Bounds height", maxPt.y - minPt.y) ``` ### `node`

```lua theme={null} node(name: string) -> NodeData? ```

Returns the node with the given name, or nil if no such node exists. ```lua highlight={2} theme={null} if self.instance then local node = self.instance:node('Root') if node then local m = Mat2D.withTranslation(100, 100) node:decompose(m) end end ``` ### `pointerDown`

```lua theme={null} pointerDown(event: PointerEvent) -> number ```

Pointer event down handler. Returns a hit-test result (0 = no hit). Only returns a non-zero value if a hit-testable object inside the nested artboard is hit. ```lua highlight={3} theme={null} function handlePointerDown(self: PointerExample, event: PointerEvent) if self.instance then local hit = self.instance:pointerDown(event) if hit ~= 0 then print(event.id) print(event.position) end end end ``` ### `pointerUp`

```lua theme={null} pointerUp(event: PointerEvent) -> number ```

Pointer event up handler. Returns a hit-test result (0 = no hit). Only returns a non-zero value if a hit-testable object inside the nested artboard is hit. ```lua highlight={3} theme={null} function handlePointerUp(self: PointerExample, event: PointerEvent) if self.instance then local hit = self.instance:pointerUp(event) if hit ~= 0 then print(event.id) print(event.position) end end end ``` ### `pointerMove`

```lua theme={null} pointerMove(event: PointerEvent) -> number ```

Pointer event move handler. Returns a hit-test result (0 = no hit). Only returns a non-zero value if a hit-testable object inside the nested artboard is hit. ```lua highlight={3} theme={null} function handlePointerMove(self: PointerExample, event: PointerEvent) if self.instance then local hit = self.instance:pointerMove(event) if hit ~= 0 then print(event.id) print(event.position) end end end ``` ### `pointerExit`

```lua theme={null} pointerExit(event: PointerEvent) -> number ```

Pointer event exit handler. Returns a hit-test result (0 = no hit). Only returns a non-zero value if a hit-testable object inside the nested artboard is hit. ```lua highlight={3} theme={null} function handlePointerExit(self: PointerExample, event: PointerEvent) if self.instance then local hit = self.instance:pointerExit(event) if hit ~= 0 then print(event.id) print(event.position) end end end ``` ### `addToPath`

```lua theme={null} addToPath(path: Path, transform: Mat2D?) -> () ```

Adds the artboard’s geometry to the given path, optionally transformed by the provided matrix. For a complete working example, see the [Add to Path](https://rive.app/community/files/27188-51290-add-to-path-scripting-demo?utm_source=docs\&utm_medium=scripting_api\&utm_campaign=docs_to_marketplace_links) demo. ```lua highlight={18} theme={null} function draw(self: AddToPathExample, renderer: Renderer) local instance = self.instance if not instance then return end -- Draw the artboard normally first. renderer:save() instance:draw(renderer) renderer:restore() -- Reset the path each frame, then rebuild it from the artboard's geometry. self.outlinePath:reset() -- Add the artboard's geometry into the path with an optional transform. -- Here we apply a slight offset via Mat2D to show the transform parameter. local transform = Mat2D.withTranslation(8, 8) instance:addToPath(self.outlinePath, transform) -- Draw the extracted path with a custom stroke paint as an outline / shadow effect. renderer:drawPath(self.outlinePath, self.outlinePaint) end ``` ### `gamepadConnected`

```lua theme={null} gamepadConnected(event: GamepadConnected) -> number ```

### `gamepadEvent`

```lua theme={null} gamepadEvent(event: GamepadEvent) -> number ```

### `gamepadDisconnected`

```lua theme={null} gamepadDisconnected(event: GamepadDisconnected) -> number ```

# FocusEvent Source: https://rive.app/docs/scripting/api-reference/artboards/focus-event Represents a focus change event. (Coming soon) ## Fields ### `isFocus` True if the element gained focus, false if it lost focus. # GamepadConnected Source: https://rive.app/docs/scripting/api-reference/artboards/gamepad-connected Full gamepad state when a device is first seen (`gamepadConnected`). Aligned with W3C Standard Gamepad when `mapping` is `'standard'`. (Coming soon) ## Fields ### `deviceId` Embedder-stable device id for this logical gamepad session. ### `buttonMask` Bit *i* set when W3C standard button index *i* is pressed. ### `buttons` Analog value per button (0–1), same order as W3C `buttons[]` / `buttonValues` (1-based). ### `axes` Analog axes (1-based). Standard layout uses at least six entries (sticks and triggers). ### `isStandardMapping` Whether the embedder normalized to the standard layout. ### `mapping` `'standard'` or `'unknown'` (semantic names match only when standard). ### `gamepadMapping` Raw enum value: 0 = standard, 1 = unknown (same as [GamepadMappingKind](/docs/scripting/api-reference/artboards/gamepad-mapping-kind) order). ### `west` Face buttons (standard mapping only; otherwise false). ### `south` ### `north` ### `east` ### `leftShoulder` ### `rightShoulder` ### `back` Select / Start (W3C back / forward). ### `forward` ### `leftStickButton` Stick click buttons. ### `rightStickButton` ### `dpadUp` ### `dpadDown` ### `dpadLeft` ### `dpadRight` ### `start` ### `leftStick` Left and right analog stick deflection (axes 0–3 when standard). ### `rightStick` ### `leftTrigger` Analog shoulder triggers (axes 4–5 when standard). ### `rightTrigger` ### `leftTriggerPressed` Digital trigger buttons (indices 6–7 when standard). ### `rightTriggerPressed` ## Methods ### `buttonPressed`

```lua theme={null} buttonPressed(index: number) -> boolean ```

True if W3C button index `index` is pressed (1-based, matches `buttons` / bitmask). ### `buttonValue`

```lua theme={null} buttonValue(index: number) -> number ```

`GamepadButton.value` for the given 1-based button index. ### `axis`

```lua theme={null} axis(index: number) -> number ```

Axis value for the given 1-based axis index. # GamepadDisconnected Source: https://rive.app/docs/scripting/api-reference/artboards/gamepad-disconnected Device id when a gamepad is removed (`gamepadDisconnected`). (Coming soon) ## Fields ### `deviceId` # GamepadEvent Source: https://rive.app/docs/scripting/api-reference/artboards/gamepad-event One field change on an already-connected gamepad (`gamepadEvent`); includes the full post-update state and optional standard-layout intent. (Coming soon) ## Fields ### `changeKind` W3C change kind: `"button"` or `"axis"`. ### `changeIndex` 1-based W3C button or axis index for this change. ### `changeValue` ### `hasStandardButtonIntent` ### `hasStandardAxisIntent` ### `intentButton` ### `intentAxis` ### `deviceId` Read-only full device state after the change (same fields as \[GamepadConnected]). ### `buttonMask` ### `buttons` ### `axes` ### `isStandardMapping` ### `mapping` ### `gamepadMapping` ### `west` ### `south` ### `north` ### `east` ### `leftShoulder` ### `rightShoulder` ### `back` ### `forward` ### `leftStickButton` ### `rightStickButton` ### `dpadUp` ### `dpadDown` ### `dpadLeft` ### `dpadRight` ### `start` ### `leftStick` ### `rightStick` ### `leftTrigger` ### `rightTrigger` ### `leftTriggerPressed` ### `rightTriggerPressed` ## Methods ### `buttonPressed`

```lua theme={null} buttonPressed(index: number) -> boolean ```

### `buttonValue`

```lua theme={null} buttonValue(index: number) -> number ```

### `axis`

```lua theme={null} axis(index: number) -> number ```

# GamepadMappingKind Source: https://rive.app/docs/scripting/api-reference/artboards/gamepad-mapping-kind # KeyPhase Source: https://rive.app/docs/scripting/api-reference/artboards/key-phase Describes the phase of a keyboard interaction. (Coming soon) Used by [KeyboardEvent](/docs/scripting/api-reference/artboards/keyboard-event). * 'down' * 'repeat' * 'up' # KeyboardEvent Source: https://rive.app/docs/scripting/api-reference/artboards/keyboard-event Represents a keyboard interaction. (Coming soon) ## Fields ### `key` The key code of the pressed key. ### `shift` True if the Shift modifier is active. ### `control` True if the Control modifier is active. ### `alt` True if the Alt modifier is active. ### `meta` True if the Meta (Command/Windows) modifier is active. ### `phase` The current phase ([KeyPhase](/docs/scripting/api-reference/artboards/key-phase)) of the interaction. # ListenerContext Source: https://rive.app/docs/scripting/api-reference/artboards/listener-context Provides access to the context that triggered a listener action. (Coming soon) A [ListenerContext](/docs/scripting/api-reference/artboards/listener-context) can represent different event types (pointer, keyboard, text input, focus, view model changes, or reported events). Use the `is...` methods to check the type, and the corresponding `as...` methods to retrieve the event data. ## Methods ### `isPointerEvent`

```lua theme={null} isPointerEvent() -> boolean ```

Returns true if the action was triggered by a pointer event. ### `isKeyboardEvent`

```lua theme={null} isKeyboardEvent() -> boolean ```

Returns true if the action was triggered by a keyboard event. ### `isTextInput`

```lua theme={null} isTextInput() -> boolean ```

Returns true if the action was triggered by a text input event. ### `isFocus`

```lua theme={null} isFocus() -> boolean ```

Returns true if the action was triggered by a focus change. ### `isReportedEvent`

```lua theme={null} isReportedEvent() -> boolean ```

Returns true if the action was triggered by a reported Rive event. ### `isViewModelChange`

```lua theme={null} isViewModelChange() -> boolean ```

Returns true if the action was triggered by a view model change. ### `isGamepadConnected`

```lua theme={null} isGamepadConnected() -> boolean ```

### `isGamepadEvent`

```lua theme={null} isGamepadEvent() -> boolean ```

### `isGamepadDisconnected`

```lua theme={null} isGamepadDisconnected() -> boolean ```

### `isNone`

```lua theme={null} isNone() -> boolean ```

Returns true if the action was triggered by an unknown or unsupported event type. ### `asPointerEvent`

```lua theme={null} asPointerEvent() -> PointerEvent? ```

Returns the pointer event if applicable, otherwise nil. ### `asKeyboardEvent`

```lua theme={null} asKeyboardEvent() -> KeyboardEvent? ```

Returns the keyboard event if applicable, otherwise nil. ### `asTextInput`

```lua theme={null} asTextInput() -> TextInput? ```

Returns the text input event if applicable, otherwise nil. ### `asFocus`

```lua theme={null} asFocus() -> FocusEvent? ```

Returns the focus event if applicable, otherwise nil. ### `asReportedEvent`

```lua theme={null} asReportedEvent() -> ReportedEvent? ```

Returns the reported event if applicable, otherwise nil. ### `asViewModelChange`

```lua theme={null} asViewModelChange() -> ViewModelChange? ```

Returns the view model change if applicable, otherwise nil. ### `asGamepadConnected`

```lua theme={null} asGamepadConnected() -> GamepadConnected? ```

### `asGamepadEvent`

```lua theme={null} asGamepadEvent() -> GamepadEvent? ```

### `asGamepadDisconnected`

```lua theme={null} asGamepadDisconnected() -> GamepadDisconnected? ```

### `asNone`

```lua theme={null} asNone() -> NoneEvent? ```

Returns a none event if applicable, otherwise nil. # NodeData Source: https://rive.app/docs/scripting/api-reference/artboards/node-data Represents a node in the hierarchy, providing transform properties and access to parent and child nodes. ## Fields ### `children` The node’s children. ```lua highlight={5} theme={null} if self.instance then local node = self.instance:node('Hips') if node then local hipsFirstChild = node.children[1] print(hipsFirstChild) local m = Mat2D.withTranslation(100, 100) if hipsFirstChild then hipsFirstChild:decompose(m) end end end ``` ### `parent` The parent of the node, or nil if it has none. ```lua highlight={4} theme={null} if self.instance then local node = self.instance:node('Hips') if node then local hipsParent = node.parent local m = Mat2D.withTranslation(100, 100) if hipsParent then hipsParent:decompose(m) end end end ``` ## Methods ### `decompose`

```lua theme={null} decompose(worldTransform: Mat2D) -> () ```

Updates the node’s position, rotation, and scale from the given world transform. ```lua highlight={5} theme={null} if self.instance then local node = self.instance:node('Root') if node then local m = Mat2D.withTranslation(100, 100) node:decompose(m) end end ``` # NodeReadData Source: https://rive.app/docs/scripting/api-reference/artboards/node-read-data Represents a node in the hierarchy, providing transform properties and access to parent and child nodes. ## Fields ### `position` The local position of the node. ```lua highlight={4} theme={null} if self.instance then local node = self.instance:node('Hips') if node then node.position = Vector.xy(199, 299) end end ``` ### `rotation` The local rotation of the node in radians. ```lua highlight={4} theme={null} if self.instance then local node = self.instance:node('Hips') if node then node.rotation = math.rad(45) end end ``` ### `scale` The local scale of the node. ```lua highlight={4} theme={null} if self.instance then local node = self.instance:node('Hips') if node then node.scale = Vector.xy(1.4, 2) end end ``` ### `worldTransform` The read-only world transform of the node. ```lua highlight={4,5,6,7} theme={null} if self.instance then local node = self.instance:node('Hips') if node then local wt = node.worldTransform print("world xx:", wt.xx, "xy:", wt.xy) print("world yx:", wt.yx, "yy:", wt.yy) print("world tx:", wt.tx, "ty:", wt.ty) end end ``` ### `x` The x-coordinate of the local position. ```lua highlight={4} theme={null} if self.instance then local node = self.instance:node('Hips') if node then node.x = 100 end end ``` ### `y` The y-coordinate of the local position. ```lua highlight={4} theme={null} if self.instance then local node = self.instance:node('Hips') if node then node.y = 200 end end ``` ### `scaleX` The x component of the local scale. ```lua highlight={4} theme={null} if self.instance then local node = self.instance:node('Hips') if node then node.scaleX = 2 end end ``` ### `scaleY` The y component of the local scale. ```lua highlight={4} theme={null} if self.instance then local node = self.instance:node('Hips') if node then node.scaleY = 2 end end ``` ### `paint` If node is a Path, paint trait is available with paint data (Coming soon) ## Methods ### `asPath`

```lua theme={null} asPath() -> PathData? ```

If node is a Path, returns the node as [PathData](/docs/scripting/api-reference/path/path-data). ```lua highlight={5} theme={null} function pointerDown(self: PaintInstance, event: PointerEvent) if self.instance then local myPath = self.instance:node('MyPath') if myPath then local path = myPath:asPath() if path then local cmd: PathCommand = path[1] print(cmd.type) -- moveTo end end end end ``` ### `asPaint`

```lua theme={null} asPaint() -> Paint? ```

If node is a ShapePaint (Fill or Stroke), returns node as [Paint](/docs/scripting/api-reference/paint/paint) (Coming soon) # NoneEvent Source: https://rive.app/docs/scripting/api-reference/artboards/none-event Represents an unknown or unsupported event. (Coming soon) # PointerEvent Source: https://rive.app/docs/scripting/api-reference/artboards/pointer-event Represents a pointer interaction event containing position and pointer id. ## Fields ### `position` The position of the pointer in local coordinates. ```lua highlight={10,11} theme={null} function handlePointerDown(self: RenderInstance, event: PointerEvent) if self.instance then local localPos = event.position - Vector.xy(self.x, self.y) local localEvent = PointerEvent.new(event.id, localPos) local hit = self.instance:pointerDown(localEvent) if hit ~= 0 then print( string.format( 'Local hit at (%.1f, %.1f)', localEvent.position.x, localEvent.position.y ) ) end end end ``` ### `id` The unique identifier for the pointer. ```lua highlight={7} theme={null} function handlePointerDown(self: RenderInstance, event: PointerEvent) if self.instance then local localPos = event.position - Vector.xy(self.x, self.y) local localEvent = PointerEvent.new(event.id, localPos) local hit = self.instance:pointerDown(localEvent) if hit ~= 0 then print(localEvent.id) end end end ``` ### `type` The type of event (pointerDown, pointerUp, click, pointerEnter, pointerMove, etc). ## Constructors ### `new`

```lua theme={null} new(id: number, position: Vector) -> PointerEvent ```

Creates a new [PointerEvent](/docs/scripting/api-reference/artboards/pointer-event) with the given id and position. ```lua highlight={4} theme={null} function handlePointerDown(self: RenderInstance, event: PointerEvent) if self.instance then local localPos = event.position - Vector.xy(self.x, self.y) local localEvent = PointerEvent.new(event.id, localPos) local hit = self.instance:pointerDown(localEvent) if hit ~= 0 then print( string.format( 'Local hit at (%.1f, %.1f)', localEvent.position.x, localEvent.position.y ) ) end end end ``` ## Methods ### `hit`

```lua theme={null} hit(isTranslucent: boolean?) -> () ```

Marks the event as handled. If isTranslucent is true, the event may continue to propagate through translucent hit targets. ```lua highlight={6} theme={null} function handlePointerDown(self: PointerExample, event: PointerEvent) if self.instance then local hit = self.instance:pointerDown(event) if hit ~= 0 then -- Mark as handled but still allow translucent targets behind to receive it. event:hit(true) end end end ``` # PointerType Source: https://rive.app/docs/scripting/api-reference/artboards/pointer-type The type of event. (Coming soon) * pointerEnter * pointerExit * pointerDown * pointerUp * pointerMove * click * pointerDrag * unknown Used in [PointerEvent](/docs/scripting/api-reference/artboards/pointer-event). # ReportedEvent Source: https://rive.app/docs/scripting/api-reference/artboards/reported-event Represents a reported Rive event. (Coming soon) # TextInput Source: https://rive.app/docs/scripting/api-reference/artboards/text-input Represents a text input event. (Coming soon) ## Fields ### `text` The input text. # ViewModel Source: https://rive.app/docs/scripting/api-reference/artboards/view-model Represents a view model used for data binding. A [ViewModel](/docs/scripting/api-reference/interfaces/view-model) provides structured data that can be read and modified at runtime, allowing Rive files to react to application state. ```lua theme={null} type ViewModelExample = { character: Input>, instance: Artboard?, } function init(self: ViewModelExample, context: Context): boolean local vm = Data.Character.new() self.instance = self.character:instance(vm) return true end return function(): Node return { character = late(), instance = nil, init = init, } end ``` # ViewModelChange Source: https://rive.app/docs/scripting/api-reference/artboards/view-model-change Represents a view model change event. (Coming soon) # Color Source: https://rive.app/docs/scripting/api-reference/color/color ## Constructors ### `lerp`

```lua theme={null} lerp(from: Color, to: Color, t: number) -> Color ```

Linearly interpolates between two colors using the parameter t, where t = 0 returns 'from' and t = 1 returns 'to'. ```lua highlight={7} theme={null} local black = Color.rgb(0, 0, 0) local white = Color.rgb(255, 255, 255) local t = 0.5 -- Linearly interpolate halfway between black and white local gray = Color.lerp(black, white, t) print(gray) -- Returns a gray color between black and white ``` ### `rgb`

```lua theme={null} rgb(r: number, g: number, b: number) -> Color ```

Returns a color constructed from red, green, and blue channels. Alpha defaults to 255 (fully opaque). Channel values are clamped to \[0, 255]. ```lua theme={null} -- Red self.color = Color.rgb(255, 0, 0) ``` ### `rgba`

```lua theme={null} rgba(r: number, g: number, b: number, a: number) -> Color ```

Returns a color constructed from red, green, blue, and alpha channels. Channel values are clamped to \[0, 255]. ```lua theme={null} -- Red at 50% opacity self.color = Color.rgba(255, 0, 0, 128) ``` ## Static Functions ### `red`

```lua theme={null} red(color: Color, value: number?) -> number | Color ```

Returns the red channel of the color. If a value is provided, returns a new color with that channel updated. ```lua highlight={2,6} theme={null} local myColor = Color.rgba(128, 55, 12, 128) local redChannel = Color.red(myColor) print(redChannel) -- 128 local newColor = Color.red(myColor, 200) print(Color.red(newColor)) -- 200 ``` ### `green`

```lua theme={null} green(color: Color, value: number?) -> number | Color ```

Returns the green channel of the color. If a value is provided, returns a new color with that channel updated. ```lua highlight={2,6} theme={null} local myColor = Color.rgba(128, 55, 12, 128) local greenChannel = Color.green(myColor) print(greenChannel) -- 55 local newColor = Color.green(myColor, 200) print(Color.green(newColor)) -- 200 ``` ### `blue`

```lua theme={null} blue(color: Color, value: number?) -> number | Color ```

Returns the blue channel of the color. If a value is provided, returns a new color with that channel updated. ```lua highlight={2,6} theme={null} local myColor = Color.rgba(128, 55, 12, 128) local blueChannel = Color.blue(myColor) print(blueChannel) -- 12 local newColor = Color.blue(myColor, 200) print(Color.blue(newColor)) -- 200 ``` ### `alpha`

```lua theme={null} alpha(color: Color, value: number?) -> number | Color ```

Returns the alpha channel of the color, or returns a new color with the alpha channel set to the specified value. Values are clamped to \[0, 255]. ```lua highlight={2,6} theme={null} local myColor = Color.rgba(128, 55, 12, 128) local alphaChannel = Color.alpha(myColor) print(alphaChannel) -- 128 local newColor = Color.alpha(myColor, 200) print(Color.alpha(newColor)) -- 200 ``` ### `opacity`

```lua theme={null} opacity(color: Color, value: number?) -> number | Color ```

Returns the opacity of the color as a normalized value in the range \[0.0, 1.0], or returns a new color with its alpha set from the specified opacity. ```lua highlight={4,9} theme={null} local myColor = Color.rgba(255, 0, 0, 128) -- Get the opacity of a color local myOpacity = Color.opacity(myColor) print(myOpacity) -- 0.5 -- Get a new color with the specified opacity local newColor = Color.opacity(myColor, 1.0) print(Color.opacity(newColor)) -- 1.0 ``` ### `toFloat`

```lua theme={null} toFloat(color: Color) -> {number} ```

Convert a Color (ARGB packed integer) to an `{r, g, b, a}` table with values in 0–1 range. Use with `clearColor` in render passes. ```lua theme={null} local cc = Color.toFloat(Color.rgba(255, 0, 0, 128)) -- cc = {1.0, 0.0, 0.0, 0.502} ``` # DataValue Source: https://rive.app/docs/scripting/api-reference/data-value/data-value Base type for values that can be stored in inputs. Provides functions for checking the underlying value type. ## Static Functions ### `number`

```lua theme={null} number() -> DataValueNumber ```

Creates a [DataValueNumber](/docs/scripting/api-reference/data-value/data-value-number) that stores a number. ```lua theme={null} local data = DataValue.number() data.value = 42 print(data.value) -- 42 ``` ### `string`

```lua theme={null} string() -> DataValueString ```

Creates a [DataValueString](/docs/scripting/api-reference/data-value/data-value-string) that stores a string. ```lua theme={null} local data = DataValue.string() data.value = 'Rive for life!' print(data.value) -- Rive for life! ``` ### `boolean`

```lua theme={null} boolean() -> DataValueBoolean ```

Creates a [DataValueBoolean](/docs/scripting/api-reference/data-value/data-value-boolean) that stores a boolean. ```lua theme={null} local data = DataValue.boolean() data.value = false print(data.value) -- false ``` ### `color`

```lua theme={null} color() -> DataValueColor ```

Creates a [DataValueColor](/docs/scripting/api-reference/data-value/data-value-color) that stores a [Color](/docs/scripting/api-reference/color/color). ```lua theme={null} local data = DataValue.color() data.value = Color.rgba(128, 55, 12, 128) print(Color.red(data.value)) -- 255 ``` ## Methods ### `isNumber`

```lua theme={null} isNumber() -> boolean ```

Returns true if the value is a number. ```lua theme={null} local dv: DataValueNumber = DataValue.number() print(dv.isNumber) -- true ``` ### `isString`

```lua theme={null} isString() -> boolean ```

Returns true if the value is a string. ```lua theme={null} local dv: DataValueNumber = DataValue.number() print(dv.isString) -- false ``` ### `isBoolean`

```lua theme={null} isBoolean() -> boolean ```

Returns true if the value is a boolean. ```lua theme={null} local dv: DataValueNumber = DataValue.number() print(dv.isBoolean) -- false ``` ### `isColor`

```lua theme={null} isColor() -> boolean ```

Returns true if the value is a color. ```lua theme={null} local dv: DataValueNumber = DataValue.number() print(dv.isColor) -- false ``` # DataValueBoolean Source: https://rive.app/docs/scripting/api-reference/data-value/data-value-boolean [DataValue](/docs/scripting/api-reference/data-value/data-value) that stores a boolean value. ## Fields ### `value` The stored boolean value. ```lua theme={null} local dv: DataValueBoolean = DataValue.boolean() dv.value = false ``` # DataValueColor Source: https://rive.app/docs/scripting/api-reference/data-value/data-value-color [DataValue](/docs/scripting/api-reference/data-value/data-value) that stores a color value encoded as a number, with red, green, blue, and alpha components. ## Fields ### `value` The full color value encoded as a number. ```lua theme={null} local dv: DataValueColor = DataValue.color() dv.value = Color.rgba(255, 0, 0, 155) ``` ### `red` Color components in the range \[0, 255]. ```lua highlight={4,5} theme={null} local data = DataValue.color() data.value = Color.rgba(128, 55, 12, 1) print(data.red) -- 128 data.red = 233 ``` ### `green` Color components in the range \[0, 255]. ```lua highlight={4,5} theme={null} local data = DataValue.color() data.value = Color.rgba(128, 55, 12, 1) print(data.green) -- 55 data.green = 233 ``` ### `blue` Color components in the range \[0, 255]. ```lua highlight={4,5} theme={null} local data = DataValue.color() data.value = Color.rgba(128, 55, 12, 1) print(data.blue) -- 12 data.blue = 233 ``` ### `alpha` Alpha component in the range \[0, 255]. ```lua highlight={4,5} theme={null} local data = DataValue.color() data.value = Color.rgba(128, 55, 12, 1) print(data.alpha) -- 1 data.alpha = 255 ``` # DataValueNumber Source: https://rive.app/docs/scripting/api-reference/data-value/data-value-number [DataValue](/docs/scripting/api-reference/data-value/data-value) that stores a number value. ## Fields ### `value` The stored numeric value. ```lua theme={null} local dv: DataValueNumber = DataValue.number() dv.value = 200 ``` # DataValueString Source: https://rive.app/docs/scripting/api-reference/data-value/data-value-string [DataValue](/docs/scripting/api-reference/data-value/data-value) that stores a string value. ## Fields ### `value` The stored string value. ```lua theme={null} local dv: DataValueString = DataValue.string() dv.value = "I heart Rive." ``` # Listener Source: https://rive.app/docs/scripting/api-reference/data-value/listener Represents a listener callback that can observe changes on an object. See [Property addListener](/docs/scripting/api-reference/data-value/property#addlistener) and [PropertyTrigger addListener](/docs/scripting/api-reference/data-value/property-trigger#addlistener). # Property Source: https://rive.app/docs/scripting/api-reference/data-value/property Represents a mutable property that stores a value and supports change listeners. ## Fields ### `value` The current value of the property. You can both read and assign to this field. ```lua highlight={4,5} theme={null} local health = vm:getNumber("health") if health then print(health.value) -- read health.value = 100 -- write end ``` ### `addListener` Registers a listener that is called whenever the property's value changes. This function has two signatures: * `addListener(callback)` — Simple form, just pass the callback function. * `addListener(anchor, callback)` — Pass an anchor object and a callback. The anchor is stored alongside the listener and passed to the callback when invoked. This is useful for preventing garbage collection of objects you need to keep alive while the listener is active. **Important:** If you obtain a ViewModel or property using a local variable (e.g., `local vm = context:viewModel()`) and add listeners without storing the ViewModel elsewhere, it may be garbage collected after the function returns. To prevent this, either: * Store the ViewModel on `self` (e.g., `self.vm = context:viewModel()`) * Pass the ViewModel as the anchor parameter to `addListener` ```lua highlight={8,10} theme={null} local health = vm:getNumber("health") if health then local function onHealthChanged(prop) print("New health:", prop.value) end health:addListener(onHealthChanged) health.value = 50 -- Triggers listener end ``` Using the anchor parameter to keep the ViewModel alive: ```lua highlight={5} theme={null} local vm = context:viewModel() local health = vm:getNumber("health") if health then health:addListener(vm, function(anchor) -- 'anchor' is the vm we passed, kept alive by the listener print("Health changed!") end) end ``` ### `removeListener` Removes a previously registered listener. This function has two signatures: * `removeListener(callback)` — Pass the callback function to remove. * `removeListener(anchor, callback)` — Pass an anchor and the callback. The anchor parameter is accepted for API symmetry with `addListener`, but only the callback is used for matching. ```lua highlight={6} theme={null} local health = vm:getNumber("health") if health then local function onHealthChanged(prop) print("New health:", prop.value) health:removeListener(onHealthChanged) end health:addListener(onHealthChanged) health.value = 50 -- Triggers listener end ``` # PropertyTrigger Source: https://rive.app/docs/scripting/api-reference/data-value/property-trigger Represents a trigger property that can fire events and notify listeners. Unlike other [Property](/docs/scripting/api-reference/data-value/property) types, a trigger does not store a persistent value. It emits an event when fire() is called. ## Fields ### `addListener` Registers a listener that is invoked when the trigger fires. This function has two signatures: * `addListener(callback)` — Simple form, just pass the callback function. * `addListener(anchor, callback)` — Pass an anchor object and a callback. The anchor is stored alongside the listener and passed to the callback when invoked. This is useful for preventing garbage collection of objects you need to keep alive while the listener is active. **Important:** If you obtain a ViewModel or property using a local variable (e.g., `local vm = context:viewModel()`) and add listeners without storing the ViewModel elsewhere, it may be garbage collected after the function returns. To prevent this, either: * Store the ViewModel on `self` (e.g., `self.vm = context:viewModel()`) * Pass the ViewModel as the anchor parameter to `addListener` ```lua highlight={5} theme={null} local vmi = context:viewModel() if vmi then local cannon = vmi:getTrigger('cannon') if cannon then cannon:addListener(function() print("cannon fired!") end) cannon:fire() end end ``` Using the anchor parameter to keep the ViewModel alive: ```lua highlight={5} theme={null} local vm = context:viewModel() if vm then local cannon = vm:getTrigger('cannon') if cannon then cannon:addListener(vm, function(anchor) -- 'anchor' is the vm we passed, kept alive by the listener print("cannon fired!") end) end end ``` ### `removeListener` Removes a previously registered listener. Always remove listeners when they are no longer needed to avoid leaks. This function has two signatures: * `removeListener(callback)` — Pass the callback function to remove. * `removeListener(anchor, callback)` — Pass an anchor and the callback. The anchor parameter is accepted for API symmetry with `addListener`, but only the callback is used for matching. ```lua highlight={17} theme={null} function init(self: MyNode, context: Context): boolean local vmi = context:viewModel() if vmi then local cannon = vmi:getTrigger('cannon') if cannon then self.cannon = cannon self.onCannonFired = onCannonFired cannon:addListener(onCannonFired) end end return true end function removeCannonListener(self: MyNode) if self.cannon then self.cannon:removeListener(self.onCannonFired) end end ``` ## Methods ### `fire`

```lua theme={null} fire() -> () ```

Fires the trigger and notifies all registered listeners. ```lua highlight={9} theme={null} local vmi = context:viewModel() if vmi then local cannon = vmi:getTrigger('cannon') if cannon then cannon:addListener(function() print("cannon fired!") end) cannon:fire() end end ``` # BindGroupDesc Source: https://rive.app/docs/scripting/api-reference/gpu/bind-group-desc Descriptor for creating a GPUBindGroup. The layout's groupIndex determines which `@group(N)` slot this BindGroup binds to. ## Fields ### `layout` ### `ubos` ### `textures` ### `samplers` # BindGroupLayoutDesc Source: https://rive.app/docs/scripting/api-reference/gpu/bind-group-layout-desc Descriptor for creating a GPUBindGroupLayout. Always derived from a shader — the binding map walks shader → kind / visibility / texture metadata / native slots so callers don't have to know any of them. ## Fields ### `shader` Source shader. Layouts cannot be built without one. ### `groupIndex` WGSL `@group(N)` this layout describes. Valid range \[0, 4). ### `dynamicUBOs` WGSL @binding values whose UBO entries should set hasDynamicOffset. ### `label` # BlendFactor Source: https://rive.app/docs/scripting/api-reference/gpu/blend-factor Blend factor for src/dst color and alpha (WebGPU canonical strings). # BlendOp Source: https://rive.app/docs/scripting/api-reference/gpu/blend-op Blend equation operator. # BlendState Source: https://rive.app/docs/scripting/api-reference/gpu/blend-state Blend equation for a single color target. ## Fields ### `srcColor` ### `dstColor` ### `colorOp` ### `srcAlpha` ### `dstAlpha` ### `alphaOp` # BufferUsage Source: https://rive.app/docs/scripting/api-reference/gpu/buffer-usage How a GPU buffer will be used. Pass to `GPUBuffer.new`. # BufferUsageArg Source: https://rive.app/docs/scripting/api-reference/gpu/buffer-usage-arg A buffer usage, or an array of usages. The array form is reserved for future multi-usage flags; today exactly one usage is supported. # Canvas Source: https://rive.app/docs/scripting/api-reference/gpu/canvas A Rive 2-D renderer canvas. Use `.image` with `renderer:drawImage()`. Call `beginFrame()` to get a Renderer, issue draw calls, then `endFrame()`. ## Fields ### `image` Backing image for `renderer:drawImage()`. ### `width` Width in pixels. ### `height` Height in pixels. ## Methods ### `resize`

```lua theme={null} resize(width: number, height: number) -> () ```

Resize the canvas. Must not be called between beginFrame() and endFrame(). ### `beginFrame`

```lua theme={null} beginFrame(desc: {clearColor: Color?}?) -> Renderer ```

Begin a Rive frame. Returns a Renderer valid until endFrame(). clearColor is an ARGB integer (e.g. 0xFF000000 = opaque black; default transparent). ### `endFrame`

```lua theme={null} endFrame() -> () ```

Flush draw calls to the backing texture and release the Renderer. # ColorAttachment Source: https://rive.app/docs/scripting/api-reference/gpu/color-attachment Color attachment descriptor for canvas:beginRenderPass. ## Fields ### `view` Optional render target view. Defaults to the receiving canvas's own colorView() when omitted. Provide an explicit view for cases where the target differs — most commonly MSAA, where `view` is the multisampled GPUTexture:view() and `resolveTarget` is the canvas's 1× colorView(). ### `resolveTarget` 1× resolve target for MSAA (formats must match `view`). ### `loadOp` ### `storeOp` Required; 'discard' after MSAA resolve, 'store' otherwise. ### `clearColor` # ColorTarget Source: https://rive.app/docs/scripting/api-reference/gpu/color-target Color target format and optional blend state. ## Fields ### `format` ### `blend` # CompareFunction Source: https://rive.app/docs/scripting/api-reference/gpu/compare-function Depth comparison function for pipeline depth-stencil state and shadow samplers. # CullMode Source: https://rive.app/docs/scripting/api-reference/gpu/cull-mode Triangle face culling mode. # DepthStencilAttachment Source: https://rive.app/docs/scripting/api-reference/gpu/depth-stencil-attachment Depth/stencil attachment descriptor for canvas:beginRenderPass. ## Fields ### `view` Required. Use GPUTexture:view(). ### `depthLoadOp` ### `depthStoreOp` Required; 'discard' for transient depth, 'store' to read it later. ### `depthClearValue` # DepthStencilState Source: https://rive.app/docs/scripting/api-reference/gpu/depth-stencil-state Depth/stencil fixed-function state. Omit from pipeline to disable depth testing. ## Fields ### `format` ### `compare` ### `write` Write depth on pass (default false). ### `depthBias` ### `depthBiasSlopeScale` # Filter Source: https://rive.app/docs/scripting/api-reference/gpu/filter Texture filtering mode. # GPUBindGroup Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-bind-group Pre-baked resource bindings reusable across many draw calls. Avoids creating new bind groups every draw — critical for 3D scene performance. Holds strong references to all bound resources (Buffer, TextureView, Sampler), keeping them alive for the BindGroup's lifetime. ## Constructors ### `new`

```lua theme={null} new(desc: BindGroupDesc) -> GPUBindGroup ```

# GPUBindGroupLayout Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-bind-group-layout Public BindGroupLayout — describes the contract a BindGroup conforms to and a Pipeline references for one of its `@group(N)` slots. You typically don't construct one directly. Two paths: 1. Auto (default) — omit `bindGroupLayouts` on `GPUPipeline.new` and retrieve via `pipeline:getBindGroupLayout(N)` for `GPUBindGroup.new`. Mirrors WebGPU's `layout: 'auto'`. 2. Explicit — call `GPUBindGroupLayout.new` and pass the layout to N pipelines via `bindGroupLayouts = { sharedLayout }`. ONE BindGroup then binds across all those pipelines (e.g. a per-frame camera/lights group reused by many materials), avoiding per- pipeline BindGroup duplication and reducing descriptor traffic. ## Constructors ### `new`

```lua theme={null} new(desc: BindGroupLayoutDesc) -> GPUBindGroupLayout ```

# GPUBuffer Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-buffer A GPU buffer for vertex, index, or uniform data. ## Fields ### `size` Size in bytes. ## Constructors ### `new`

```lua theme={null} new(desc: GPUBufferDesc) -> GPUBuffer ```

## Methods ### `write`

```lua theme={null} write(data: buffer, offset: number?, srcOffset: number?, byteLength: number?) -> () ```

Copy CPU data into the buffer. @param data Source bytes. @param offset Byte offset into the GPU buffer (default 0). @param srcOffset Byte offset into `data` to copy from (default 0). @param byteLength Bytes to copy (default: the rest of `data` from `srcOffset`). Lets a script upload a prefix of an oversized staging buffer without slicing it. # GPUBufferDesc Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-buffer-desc Descriptor for `GPUBuffer.new`. ## Fields ### `size` Size in bytes. ### `usage` How the buffer will be used. ### `data` Optional initial contents. Required when `immutable` is true; its length must equal `size`. ### `immutable` When true the buffer is GPU-only and cannot be written after creation. ### `label` Optional debug name. # GPUCanvas Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-canvas A GPU canvas — a 1× presentation target, same role as a WebGPU surface texture. Use `.image` with `renderer:drawImage()` to composite the result. Render to it via `canvas:beginRenderPass({ color = {{ loadOp = 'clear', storeOp = 'store', ... }} })` — the color attachment's `view` defaults to this canvas's own colorView when omitted. MSAA requires a user-allocated `GPUTexture.new({ sampleCount = N, renderTarget = true })` as the explicit color view, with the canvas's `colorView()` as `resolveTarget`. ## Fields ### `image` Backing image for `renderer:drawImage()`. ### `width` Width in pixels. ### `height` Height in pixels. ### `format` Pixel format of the canvas backing texture, always 'rgba8unorm'. A deferred canvas reports this before its texture is allocated. MSAA resolve requires source and target to have identical formats — always derive GPUTexture and pipeline formats from this value: ```lua theme={null} local fmt = canvas.format GPUPipeline.new({ colorTargets = {{ format = fmt }}, sampleCount = 4 }) ``` ## Methods ### `resize`

```lua theme={null} resize(width: number, height: number) -> () ```

Resize the canvas. Recreates the 1× backing texture. Any user-allocated MSAA / depth textures must be recreated by the script to match the new dimensions. ### `colorView`

```lua theme={null} colorView() -> GPUTextureView ```

View of the canvas backing texture. Use as a color attachment, an MSAA resolve target, or a sampler input in a subsequent pass. ### `beginRenderPass`

```lua theme={null} beginRenderPass(desc: RenderPassDesc) -> GPURenderPass ```

Open a GPU render pass targeting this canvas. The descriptor must include at least one color attachment or a depthStencil attachment. Color attachment views default to this canvas's colorView when omitted; provide them explicitly when rendering to a different target (e.g. MSAA). The pass's sampleCount is derived from the attachments (WebGPU rule: all attachments share one sampleCount). Must be called during draw. Issue draw calls on the returned pass, then call `:finish()`. # GPUColor Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-color RGBA clear color in 0–1 range (e.g. for opaque black). Supports HDR values beyond 1.0 for float render targets. Use `Color.toFloat()` to convert from a packed ARGB Color. # GPUFeatures Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-features Optional GPU capabilities. Returned by `context:features()`. ## Fields ### `bc` BC (S3TC/DXT) compressed texture formats supported. ### `etc2` ETC2 compressed texture formats supported (common on mobile). ### `astc` ASTC compressed texture formats supported. ### `maxTextureSize2D` Maximum 2-D texture width or height in texels. ### `maxTextureSizeCube` Maximum cube-map face size in texels. ### `maxTextureSize3D` Maximum 3-D texture depth / layer count. ### `anisotropicFiltering` Anisotropic texture filtering supported. ### `texture3D` 3-D textures supported. ### `textureArrays` Texture arrays supported. ### `colorBufferFloat` 32-bit float color render targets supported (rgba32float etc). ### `colorBufferHalfFloat` 16-bit float color render targets supported (rgba16float etc). Implied by colorBufferFloat, but can be present without it on WebGL. ### `perTargetBlend` Independent blend state per color attachment supported. ### `perTargetWriteMask` Independent write mask per color attachment supported. ### `drawBaseInstance` Non-zero firstInstance in draw calls supported. ### `depthBiasClamp` Depth bias clamping (depthBiasClamp) supported in pipeline state. ### `maxColorAttachments` Maximum number of simultaneous color attachments. ### `maxUniformBufferSize` Maximum uniform buffer binding size in bytes. ### `maxSamplers` Maximum number of samplers per shader stage. ### `maxSamples` Maximum MSAA sample count for color render targets (always a power-of-two: 1, 2, 4, or 8). # GPUPipeline Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-pipeline A compiled GPU render pipeline (shaders + fixed-function state). ## Constructors ### `new`

```lua theme={null} new(desc: {vertex: PipelineStage, fragment: PipelineStage?, vertexLayout:{VertexBufferLayout}, bindGroupLayouts:{GPUBindGroupLayout}?, colorTargets:{ColorTarget}?, depthStencil: DepthStencilState?, cullMode: CullMode?, topology: PrimitiveTopology?, sampleCount: number?,}) -> GPUPipeline ```

## Methods ### `getBindGroupLayout`

```lua theme={null} getBindGroupLayout(groupIndex: number) -> GPUBindGroupLayout ```

Returns the layout the pipeline auto-derived for `@group(N)`. Errors if `bindGroupLayouts` was supplied at construction (reuse the explicit one) or if N is not bound by the shader. Mirrors WebGPU's `pipeline.getBindGroupLayout(index)`. # GPURenderPass Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-render-pass An active render pass. Issue all draw calls before calling finish(). ## Methods ### `setPipeline`

```lua theme={null} setPipeline(pipeline: GPUPipeline) -> () ```

Bind a pipeline for subsequent draw calls. ### `setVertexBuffer`

```lua theme={null} setVertexBuffer(slot: number, buffer: GPUBuffer) -> () ```

Bind a vertex buffer to slot (0-based). ### `setIndexBuffer`

```lua theme={null} setIndexBuffer(buffer: GPUBuffer, format: ('uint16' | 'uint32')?) -> () ```

Bind an index buffer. format defaults to 'uint16'. ### `setBindGroup`

```lua theme={null} setBindGroup(groupIndex: number, bg: GPUBindGroup, dynamicOffsets: {number}?) -> () ```

Bind a pre-created BindGroup to a group slot. dynamicOffsets: one byte offset per dynamic UBO in this group (dynamic UBOs are declared on the pipeline via `BindGroupLayoutEntry.hasDynamicOffset`). Order matches the UBOs' appearance in `BindGroupDesc.ubos`. Typical 3D pattern: shared texture BindGroup at group 1, per-object UBO dynamic offset at group 0. ### `setViewport`

```lua theme={null} setViewport(x: number, y: number, w: number, h: number) -> () ```

Set the render viewport in pixels. Origin is top-left on all backends except GL (bottom-left). ### `setScissorRect`

```lua theme={null} setScissorRect(x: number, y: number, w: number, h: number) -> () ```

Set the scissor rectangle in pixels. ### `setStencilReference`

```lua theme={null} setStencilReference(ref: number) -> () ```

Set the stencil reference value. ### `setBlendColor`

```lua theme={null} setBlendColor(r: number, g: number, b: number, a: number) -> () ```

Set the constant blend color for 'constant' / 'one-minus-constant' factors. ### `draw`

```lua theme={null} draw(vertexCount: number, instanceCount: number?, firstVertex: number?) -> () ```

Non-indexed draw. instanceCount defaults to 1, firstVertex to 0. ### `drawIndexed`

```lua theme={null} drawIndexed(indexCount: number, instanceCount: number?, firstIndex: number?) -> () ```

Indexed draw. instanceCount defaults to 1, firstIndex to 0. ### `finish`

```lua theme={null} finish() -> () ```

Submit the pass. Any further method calls on this object will error. # GPUSampler Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-sampler GPUTextureView is declared in the shared "rive/gpu\_types" builtin (loaded before rive/image) so that a single nominal type is used everywhere — both Image:view() and GPU render-pass APIs. Describes how a texture is sampled in a shader. ## Constructors ### `new`

```lua theme={null} new(desc: {min: Filter?, mag: Filter?, mipmap: Filter?, wrapU: WrapMode?, wrapV: WrapMode?, compare: CompareFunction?, maxAnisotropy: number?,}?) -> GPUSampler ```

# GPUTexture Source: https://rive.app/docs/scripting/api-reference/gpu/gpu-texture A GPU texture (2-D, cube, 3-D, or array). ## Fields ### `width` Width of mip 0 in texels. ### `height` Height of mip 0 in texels. ### `format` Pixel format. ## Constructors ### `new`

```lua theme={null} new(desc: {width: number, height: number, format: TextureFormat?, type: TextureType?, renderTarget: boolean?, mipmaps: number?, layers: number?, sampleCount: number?, label: string?,}) -> GPUTexture ```

## Methods ### `view`

```lua theme={null} view(desc: {dimension: TextureType?, aspect: TextureAspect?, baseMipLevel: number?, mipCount: number?, baseLayer: number?, layerCount: number?,}?) -> GPUTextureView ```

Create a view into a sub-range of this texture. All fields optional; omit desc entirely for a full-texture view. Views are immutable. Create them once at init next to the texture and reuse them every frame. Calling view() in a per-frame draw callback creates and destroys a native GPU object each frame. ### `upload`

```lua theme={null} upload(desc: {data: buffer, mipLevel: number?, layer: number?, width: number?, height: number?,}) -> () ```

Upload pixel data to a specific mip / layer. # LoadOp Source: https://rive.app/docs/scripting/api-reference/gpu/load-op What to do with an attachment at the start of a render pass. 'clear' fills with clearColor/depthClearValue; 'load' preserves existing contents (expensive on tile GPUs). # PipelineStage Source: https://rive.app/docs/scripting/api-reference/gpu/pipeline-stage A pipeline stage: a Shader, or WebGPU-style `{ module = Shader, entryPoint = name }`. The Shader's `@vertex`/`@fragment` functions are the selectable entry points; omit `entryPoint` to use the first one of that stage (like WebGPU). Vertex and fragment may come from different Shaders. # PrimitiveTopology Source: https://rive.app/docs/scripting/api-reference/gpu/primitive-topology GPU primitive assembly topology. # RenderPassDesc Source: https://rive.app/docs/scripting/api-reference/gpu/render-pass-desc Render pass descriptor for canvas:beginRenderPass. Must include at least one color attachment or a depthStencil attachment. All attachments (color views + depth) must share one sampleCount, derived per WebGPU rules — pass sampleCount is inferred from the views, not declared. ## Fields ### `color` ### `depthStencil` # SamplerEntry Source: https://rive.app/docs/scripting/api-reference/gpu/sampler-entry An entry binding a sampler into a BindGroup. ## Fields ### `slot` ### `sampler` # Shader Source: https://rive.app/docs/scripting/api-reference/gpu/shader An opaque compiled shader module. Get one with `context:shader(name)`, where `name` is the shader asset's name as added in the editor (e.g. "myEffect" — no ".wgsl" extension). Raw WGSL source strings are not accepted at runtime. # StoreOp Source: https://rive.app/docs/scripting/api-reference/gpu/store-op What to do with an attachment at the end of a render pass. Use 'discard' for MSAA color/depth (contents are resolved or unused); 'store' to keep. # TextureAspect Source: https://rive.app/docs/scripting/api-reference/gpu/texture-aspect Which planes of a depth/stencil texture a view exposes. Use 'depth-only' for depth textures sampled as texture\_depth\_2d in WGSL. # TextureEntry Source: https://rive.app/docs/scripting/api-reference/gpu/texture-entry An entry binding a texture view into a BindGroup. ## Fields ### `slot` ### `view` # TextureType Source: https://rive.app/docs/scripting/api-reference/gpu/texture-type Texture dimensionality (WebGPU canonical strings). # UBOEntry Source: https://rive.app/docs/scripting/api-reference/gpu/ubo-entry An entry binding a uniform buffer into a BindGroup. Dynamic-offset UBOs are declared on each layout entry via `BindGroupLayoutEntry.hasDynamicOffset`, matching WebGPU/Vulkan's layout-level ownership model. ## Fields ### `slot` ### `buffer` ### `offset` ### `size` # VertexAttribute Source: https://rive.app/docs/scripting/api-reference/gpu/vertex-attribute Per-vertex attribute within a vertex buffer layout. `offset` is the byte offset of this attribute within the vertex (default 0). For interleaved layouts with multiple attributes you must set offset explicitly, e.g. offset = 0 for position (float3 = 12 bytes), offset = 12 for normal, etc. ## Fields ### `format` ### `slot` ### `offset` # VertexBufferLayout Source: https://rive.app/docs/scripting/api-reference/gpu/vertex-buffer-layout Describes how one vertex buffer feeds attributes to the vertex shader. ## Fields ### `stride` Byte stride between vertices. ### `stepMode` Advance per vertex or per instance (default 'vertex'). ### `attributes` Vertex attributes sourced from this buffer. # VertexFormat Source: https://rive.app/docs/scripting/api-reference/gpu/vertex-format Per-vertex attribute format (WebGPU canonical strings). # WrapMode Source: https://rive.app/docs/scripting/api-reference/gpu/wrap-mode Texture address / wrap mode. # ColorFormat Source: https://rive.app/docs/scripting/api-reference/gpu_types/color-format Color pixel formats for render targets and sampling (WebGPU canonical strings). # CompressedFormat Source: https://rive.app/docs/scripting/api-reference/gpu_types/compressed-format Block-compressed texture formats (GPU-dependent; check `context:features()`). # DepthFormat Source: https://rive.app/docs/scripting/api-reference/gpu_types/depth-format Depth and depth/stencil formats for depth buffers. # GPUTextureView Source: https://rive.app/docs/scripting/api-reference/gpu_types/gpu-texture-view A view into a GPUTexture or canvas backing store. Used as attachment and sampler handles in render passes. ## Fields ### `format` Pixel format of the underlying texture. Check this when pairing an MSAA view with a resolveTarget — formats must match. # TextureFormat Source: https://rive.app/docs/scripting/api-reference/gpu_types/texture-format Any pixel format. Use [ColorFormat](/docs/scripting/api-reference/gpu_types/color-format) or [DepthFormat](/docs/scripting/api-reference/gpu_types/depth-format) where the context is narrower. # Gradient Source: https://rive.app/docs/scripting/api-reference/gradient/gradient Represents a gradient used for filling or stroking a shape. A gradient is defined by a set of color stops ([GradientStop](/docs/scripting/api-reference/gradient/gradient-stop)) and either a linear or radial configuration. ## Constructors ### `linear`

```lua theme={null} linear(from: Vector, to: Vector, stops: {GradientStop}) -> Gradient ```

Creates a linear gradient that transitions between the specified color stops along the line from 'from' to 'to'. ```lua theme={null} local g = Gradient.linear(Vector.xy(0, 0), Vector.xy(100, 0), { { position = 0, color = Color.rgb(255, 0, 0) }, { position = 1, color = Color.rgb(0, 0, 255) }, }) ``` ### `radial`

```lua theme={null} radial(from: Vector, radius: number, stops: {GradientStop}) -> Gradient ```

Creates a radial gradient centered at 'from', extending outward to the given radius, using the specified color stops. ```lua theme={null} local g = Gradient.radial(Vector.xy(50, 50), 40, { { position = 0, color = Color.rgb(255, 0, 0) }, { position = 1, color = Color.rgb(0, 0, 255) }, }) ``` # GradientStop Source: https://rive.app/docs/scripting/api-reference/gradient/gradient-stop A color stop in a [Gradient](/docs/scripting/api-reference/gradient/gradient), defined by its position in the range \[0, 1] and the color at that position. ## Fields ### `position` Position of the stop along the gradient, where 0 is the start and 1 is the end. ```lua highlight={3,7} theme={null} local g = Gradient.linear(Vector.xy(0, 0), Vector.xy(100, 0), { { position = 0, color = Color.rgb(255, 0, 0) }, { position = 1, color = Color.rgb(0, 0, 255) }, }) ``` ### `color` [Color](/docs/scripting/api-reference/color/color) at the specified position. ```lua highlight={4,8} theme={null} local g = Gradient.linear(Vector.xy(0, 0), Vector.xy(100, 0), { { position = 0, color = Color.rgb(255, 0, 0) }, { position = 1, color = Color.rgb(0, 0, 255) }, }) ``` # Font Source: https://rive.app/docs/scripting/api-reference/image/font Represents an image asset that can be drawn by the [Renderer](/docs/scripting/api-reference/renderer/renderer). ```lua highlight={2,7,15} theme={null} type DrawImage = { myImage: Image?, sampler: ImageSampler?, } function init(self: DrawImage, context: Context): boolean self.myImage = context:image('myImage') self.sampler = ImageSampler('clamp', 'clamp', 'bilinear') return true end function draw(self: DrawImage, renderer: Renderer) if self.myImage and self.sampler then renderer:drawImage(self.myImage, self.sampler, 'srcOver', 1) end end return function(): Node return { myImage = nil, sampler = nil, init = init, draw = draw, } end ``` An immutable font resource. Obtained from a host and assignable to view model font properties. # Image Source: https://rive.app/docs/scripting/api-reference/image/image ## Fields ### `width` Width of the image. ```lua highlight={4} theme={null} self.myImage = context:image('myImage') if self.myImage then print("myImage width:", self.myImage.width) end ``` ### `height` Height of the image. ```lua highlight={4} theme={null} self.myImage = context:image('myImage') if self.myImage then print("myImage height:", self.myImage.height ) end ``` ## Methods ### `view`

```lua theme={null} view() -> GPUTextureView ```

Returns a GPUTextureView for sampling this image in WGSL shaders. The view wraps the underlying GPU texture directly — no copy or decode. Requires a GPU context (only available when the file uses GPU canvases). # ImageFilter Source: https://rive.app/docs/scripting/api-reference/image/image-filter Defines how image sampling is performed when scaling or transforming the image. * `bilinear` * `nearest` See [ImageSampler](/docs/scripting/api-reference/image/image-sampler) for usage. ```lua highlight={6} theme={null} function init(self: DrawImage, context: Context): boolean self.myImage = context:image('myImage') self.sampler = ImageSampler( 'clamp', 'clamp', 'bilinear' ) return true end ``` # ImageSampler Source: https://rive.app/docs/scripting/api-reference/image/image-sampler Represents sampling parameters applied when drawing an image, including wrapping and filtering behaviour. See also [ImageSampler](/docs/scripting/api-reference/image/image-sampler), [ImageWrap](/docs/scripting/api-reference/image/image-wrap), and [ImageFilter](/docs/scripting/api-reference/image/image-filter). Check out [Scripting demos](https://rive.app/docs/scripting/demos) to see a working example. ```lua highlight={3,8,15} theme={null} type DrawImage = { myImage: Image?, sampler: ImageSampler?, } function init(self: DrawImage, context: Context): boolean self.myImage = context:image('myImage') self.sampler = ImageSampler('clamp', 'clamp', 'bilinear') return true end function draw(self: DrawImage, renderer: Renderer) if self.myImage and self.sampler then renderer:drawImage(self.myImage, self.sampler, 'srcOver', 1) end end return function(): Node return { myImage = nil, sampler = nil, init = init, draw = draw, } end ``` # ImageWrap Source: https://rive.app/docs/scripting/api-reference/image/image-wrap Defines how texture coordinates outside the \[0, 1] range are handled. * `clamp` * `repeat` * `mirror` See [ImageSampler](/docs/scripting/api-reference/image/image-sampler) for usage. ```lua highlight={5,7} theme={null} function init(self: DrawImage, context: Context): boolean self.myImage = context:image('myImage') self.sampler = ImageSampler( -- Image wrap X 'clamp', -- Image wrap Y 'clamp', 'bilinear' ) return true end ``` # AudioSound Source: https://rive.app/docs/scripting/api-reference/interfaces/audio-sound A playback instance returned by `Audio:play*`, with controls for transport and volume. ## Fields ### `volume` volume of the sound. ```lua highlight={4} theme={null} function update(self: AudioScript) -- updates the volume for AudioSound playback when the input is changed if self.soundInstance then self.soundInstance.volume = self.volumeNumber / 100 end end ``` ## Methods ### `stop`

```lua theme={null} stop(fadeToStopTime: number?) -> () ```

stop the audio ```lua highlight={3} theme={null} function stopSound(self: AudioScript) if self.soundInstance then self.soundInstance:stop() end end ``` ### `seek`

```lua theme={null} seek(seconds: number) -> () ```

seek the audio to a specific time in seconds. ```lua theme={null} if self.soundInstance then self.soundInstance:seek(self.seekSeconds) end ``` ### `seekFrame`

```lua theme={null} seekFrame(frame: number) -> () ```

seek the audio to a specific time in PCM frames. ```lua theme={null} if self.soundInstance then self.soundInstance:seekFrame(self.seekFrameNumber) end ``` ### `completed`

```lua theme={null} completed() -> boolean ```

Whether the sound has completed playing. ```lua highlight={3} theme={null} function advance(self: AudioScript, seconds: number): boolean if self.soundInstance then self.isCompleted = self.soundInstance:completed() -- whether playback has finished end return true end ``` ### `time`

```lua theme={null} time() -> number ```

Current sound time in seconds. ```lua highlight={3} theme={null} function advance(self: AudioScript, seconds: number): boolean if self.soundInstance then self.currentTime = self.soundInstance:time() -- current playback time in seconds end return true end ``` ### `timeFrame`

```lua theme={null} timeFrame() -> number ```

Current sound time in PCM frames. ```lua highlight={3} theme={null} function advance(self: AudioScript, seconds: number): boolean if self.soundInstance then self.currentTimeFrame = self.soundInstance:timeFrame() -- current playback time in PCM frames end return true end ``` ### `pause`

```lua theme={null} pause() -> () ```

pauses the audio. ```lua highlight={3} theme={null} function pauseSound(self: AudioScript) if self.soundInstance then self.soundInstance:pause() end end ``` ### `resume`

```lua theme={null} resume() -> () ```

resumes the audio from its current position. ```lua highlight={3} theme={null} function resumeSound(self: AudioScript) if self.soundInstance then self.soundInstance:resume() end end ``` ### `play`

```lua theme={null} play() -> () ```

plays the audio. ```lua highlight={3} theme={null} function playSound(self: AudioScript) if self.soundInstance then self.soundInstance:play() end end ``` # AudioSource Source: https://rive.app/docs/scripting/api-reference/interfaces/audio-source An audio asset handle returned by `Context:audio(name)` and used with the global `Audio` API. ## Fields ### `duration` Duration of the sound in seconds. (Coming soon) # Blob Source: https://rive.app/docs/scripting/api-reference/interfaces/blob A blob asset containing raw binary data. ## Fields ### `size` The size of the blob data in bytes. ```lua highlight={9} theme={null} type DrawBlob = { myBlob: Blob?, } function init(self: DrawBlob, context: Context): boolean self.myBlob = context:blob('myBlob') if self.myBlob then print('Blob size:', self.myBlob.size, 'bytes') end return true end return function(): Node return { myBlob = nil, init = init, } end ``` ### `name` The name of the blob asset. ```lua highlight={9} theme={null} type DrawBlob = { myBlob: Blob?, } function init(self: DrawBlob, context: Context): boolean self.myBlob = context:blob('myBlob') if self.myBlob then print('Blob name:', self.myBlob.name) end return true end return function(): Node return { myBlob = nil, init = init, } end ``` ### `data` The raw binary data as a buffer. Read it with the `buffer` library, for example `buffer.readu8(blob.data, 0)`. ```lua highlight={9} theme={null} type DrawBlob = { myBlob: Blob?, } function init(self: DrawBlob, context: Context): boolean self.myBlob = context:blob('myBlob') if self.myBlob then print('First byte:', buffer.readu8(self.myBlob.data, 0)) end return true end return function(): Node return { myBlob = nil, init = init, } end ``` # Context Source: https://rive.app/docs/scripting/api-reference/interfaces/context Context is an object provided to scripted nodes during initialization (via the `init` function). It serves as a bridge between your script and the Rive runtime, giving you access to: * Update scheduling — Request that your node be updated on the next frame. * Data (ViewModels) — Access the ViewModel data context bound to the node or the root artboard. * Assets — Retrieve named assets (images, blobs, and audio) that have been added to the Rive file. ## Methods ### `markNeedsUpdate`

```lua theme={null} markNeedsUpdate() -> () ```

Marks the object as needing an update on the next frame. Call this when something has changed (e.g., from a listener callback) and you need the runtime to re-invoke your node's update function. Note: Calls to `markNeedsUpdate` from inside `update()` are ignored. Use it from `init()`, `advance()`, listener callbacks, or event handlers instead. ```lua highlight={11} theme={null} function init(self: MyNode, context: Context): boolean self.context = context -- Access a ViewModel property and listen for changes local vm = context:viewModel() if vm then local name = vm:getString("name") if name then name:addListener(function() -- Re-trigger update when the data changes if self.context then self.context:markNeedsUpdate() end end) end end return true end ``` ### `viewModel`

```lua theme={null} viewModel() -> ViewModel? ```

Returns the [ViewModel](/docs/scripting/api-reference/interfaces/view-model) bound to the node's immediate data context. This is the most common way to read data-bound properties from a script. ```lua highlight={2} theme={null} function init(self: MyNode, context: Context): boolean local vmi = context:viewModel() if vmi then local cannon = vmi:getTrigger('cannon') end return true end ``` ### `rootViewModel`

```lua theme={null} rootViewModel() -> ViewModel? ```

Returns the [ViewModel](/docs/scripting/api-reference/interfaces/view-model) bound to the root artboard's data context. Useful when you need to access top-level data from a deeply nested node. ```lua highlight={2} theme={null} function init(self: MyNode, context: Context): boolean local vmi = context:rootViewModel() if vmi then local cannon = vmi:getTrigger('cannon') end return true end ``` ### `globalViewModel`

```lua theme={null} globalViewModel(name: string) -> ViewModel? ```

Returns the global [ViewModel](/docs/scripting/api-reference/interfaces/view-model) with the given name, or nil if there is no global view model by that name or none is currently bound. Global view models are shared, singleton-like view models addressed by name rather than through the node's own data context. ```lua highlight={2} theme={null} function init(self: MyNode, context: Context): boolean local settings = context:globalViewModel('AppSettings') if settings then local volume = settings:getNumber('volume') end return true end ``` ### `globalViewModelNames`

```lua theme={null} globalViewModelNames() -> {string} ```

Returns a list of the names of all global view models defined in the file. Pass any of these names to `globalViewModel` to fetch the corresponding view model. ```lua highlight={2} theme={null} function init(self: MyNode, context: Context): boolean for _, name in ipairs(context:globalViewModelNames()) do print(name) end return true end ``` ### `dataContext`

```lua theme={null} dataContext() -> DataContext? ```

Returns the data context provided to this node. ```lua highlight={2} theme={null} function init(self: MyNode, context: Context): boolean local dc = context:dataContext() if dc then local parentDC = dc:parent() local vm = dc:viewModel() end return true end ``` ### `image`

```lua theme={null} image(name: string) -> Image? ```

Returns an image asset by name, or nil if not found. The returned [Image](/docs/scripting/api-reference/image/image) can be drawn via `drawImage`. See also [ImageSampler](/docs/scripting/api-reference/image/image-sampler). Check out [Scripting demos](https://rive.app/docs/scripting/demos) to see a working example. ```lua highlight={7,15} theme={null} type DrawImage = { myImage: Image?, sampler: ImageSampler?, } function init(self: DrawImage, context: Context): boolean self.myImage = context:image('myImage') self.sampler = ImageSampler('clamp', 'clamp', 'bilinear') return true end function draw(self: DrawImage, renderer: Renderer) if self.myImage and self.sampler then renderer:drawImage(self.myImage, self.sampler, 'srcOver', 1) end end return function(): Node return { myImage = nil, sampler = nil, init = init, draw = draw, } end ``` ### `blob`

```lua theme={null} blob(name: string) -> Blob? ```

Returns a [Blob](/docs/scripting/api-reference/interfaces/blob) (raw binary data) asset by name, or nil if not found. Useful for loading custom data files embedded in the Rive file. ```lua highlight={6} theme={null} type DrawBlob = { myBlob: Blob?, } function init(self: DrawBlob, context: Context): boolean self.myBlob = context:blob('myBlob') if self.myBlob then print('Blob name:', self.myBlob.name) print('Blob size:', self.myBlob.size, 'bytes') print('First byte:', buffer.readu8(self.myBlob.data, 0)) end return true end return function(): Node return { myBlob = nil, init = init, } end ``` ### `audio`

```lua theme={null} audio(name: string) -> AudioSource? ```

Returns an [AudioSource](/docs/scripting/api-reference/interfaces/audio-source) asset by name. The returned source can be played using the global `Audio` API. ```lua highlight={4,8} theme={null} type AudioExample = { play: Input, source: AudioSource?, } function init(self: AudioExample, context: Context): boolean self.source = context:audio("myAudio") return true end function playSound(self: AudioExample) if self.source then Audio.play(self.source) end end return function(): Node return { play = playSound, source = nil, init = init, } end ``` ### `canvas`

```lua theme={null} canvas(desc: {width: number, height: number, clearColor: Color?,}?) -> Canvas ```

Create a 2D canvas for Rive Renderer drawing. Use beginFrame/endFrame during draw to render. The descriptor is optional. Omitting it (or passing width/height of 0\) creates a deferred canvas with no backing texture — useful in layout scripts that don't know their size at init. Call `canvas:resize(w, h)` once the real size is known. While deferred, `canvas.image` is nil and `width`/`height` report 0; calling `beginFrame()` raises an error pointing to `resize()`. Check `canvas.width > 0` to gate work. ### `gpuCanvas`

```lua theme={null} gpuCanvas(desc: {width: number, height: number,}?) -> GPUCanvas ```

Create a GPU canvas — a 1× presentation target. Render to it via `canvas:beginRenderPass(...)`. For MSAA, allocate the multisampled color and depth textures yourself with `GPUTexture.new({ sampleCount = N, renderTarget = true })` and pass them in the descriptor. The descriptor is optional. Omitting it (or passing width/height of 0\) creates a deferred canvas with no backing texture — useful in layout scripts that don't know their size at init. Call `canvas:resize(w, h)` once the real size is known. While deferred, `width`/`height` report 0 and calling `colorView()` raises an error pointing to `resize()`. Check `canvas.width > 0` to gate work. ### `features`

```lua theme={null} features() -> GPUFeatures ```

Query GPU capabilities. Returns a table of supported features and limits for the current backend. ### `shader`

```lua theme={null} shader(name: string) -> Shader? ```

Get a compiled shader by asset name (the name as added in the editor, with no ".wgsl" extension). Returns a Shader ready for use in GPUPipeline.new(), or nil if the named shader is not found. ### `decodeImage`

```lua theme={null} decodeImage(data: buffer) -> Promise ```

Decode compressed image data (PNG, JPEG, WebP) into premultiplied RGBA8 pixels. Returns a Promise that resolves with a DecodedImage table. Use with await() inside async(), or chain with :andThen(). # Converter Source: https://rive.app/docs/scripting/api-reference/interfaces/converter A scripted converter used for transforming values between ViewModel data bindings and Rive properties. Type parameters: T: The converter type I: The input type, must be a DataValue type (DataValueNumber, DataValueString, DataValueBoolean, DataValueColor, etc) O: The output type, must be a DataValue type (DataValueNumber, DataValueString, DataValueBoolean, DataValueColor, etc) For more information, see [Converter Scripts](/docs/scripting/protocols/converter-scripts). ## Methods ### `init`

```lua theme={null} init(self: T, context: Context) -> boolean ```

Called once when the converter is created. Returns true if initialization succeeds. ```lua theme={null} -- Called once when the script initializes. function init(self: MyConverter, context: Context): boolean -- Return false to stop the script. return true end ``` ### `convert`

```lua theme={null} convert(self: T, input: I) -> O ```

Converts the input value (a view model property) to an output value. The input parameter must be a DataValue type. ```lua theme={null} -- Converts the value when binding from source to target. function convert(self: MyConverter, input: DataInputs): DataOutput local dv: DataValueNumber = DataValue.number() if input:isNumber() then -- Example: Add 1 to the incoming number dv.value = (input :: DataValueNumber).value + 1 end return dv end ``` ### `reverseConvert`

```lua theme={null} reverseConvert(self: T, input: O) -> I ```

Converts the output value back to an input value (a view model property). The input parameter must be a DataValue type. ```lua theme={null} function reverseConvert( self: MyConverter, input: DataOutput ): DataInputs local dv: DataValueNumber = DataValue.number() if input:isNumber() then -- Example: Subract 1 from the target number dv.value = (input :: DataValueNumber).value - 1 end return dv end ``` ### `advance`

```lua theme={null} advance(self: T, seconds: number) -> boolean ```

Optional per-frame update. Returns true if the converter should continue receiving advance calls. ```lua theme={null} function advance(self: MyConverter, seconds: number): boolean return false end ``` # DataContext Source: https://rive.app/docs/scripting/api-reference/interfaces/data-context Provides access to hierarchical data and its associated ViewModel. ## Methods ### `parent`

```lua theme={null} parent() -> DataContext? ```

Returns the parent DataContext, if one exists. ```lua highlight={4} theme={null} function init(self: MyNode, context: Context): boolean local dc = context:dataContext() if dc then local parentDC = dc:parent() local vm = dc:viewModel() end return true end ``` ### `viewModel`

```lua theme={null} viewModel() -> ViewModel? ```

Returns the ViewModel associated with this context. ```lua highlight={5} theme={null} function init(self: MyNode, context: Context): boolean local dc = context:dataContext() if dc then local parentDC = dc:parent() local vm = dc:viewModel() end return true end ``` # DecodedImage Source: https://rive.app/docs/scripting/api-reference/interfaces/decoded-image Raw decoded image pixels returned by context:decodeImage(). ## Fields ### `data` Premultiplied RGBA8 pixel data (width \* height \* 4 bytes). ### `width` Width in pixels. ### `height` Height in pixels. # EnumValues Source: https://rive.app/docs/scripting/api-reference/interfaces/enum-values ## Methods ### `__len`

```lua theme={null} __len() -> number ```

Get the number of enum values. ```lua highlight={7} theme={null} local vmi = context:viewModel() if vmi then local textAlignment = vmi:getEnum('textAlignment') if textAlignment then local values = textAlignment:values() print('count: ', #values) end end ``` # Input Source: https://rive.app/docs/scripting/api-reference/interfaces/input Represents a typed input value. ```lua highlight={3,4,5,6} theme={null} -- Define the script's data and inputs. type MyNode = { speed: Input, title: Input, enabled: Input, onReset: Input, } -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { speed = 1, title = 'Rive so coooool!', enabled = false, onReset = function() end, } end ``` # Interpolator Source: https://rive.app/docs/scripting/api-reference/interfaces/interpolator An interpolator ## Methods ### `init`

```lua theme={null} init(self: T, context: Context) -> boolean ```

### `transform`

```lua theme={null} transform(self: T, value: number) -> number ```

### `transformValue`

```lua theme={null} transformValue(self: T, from: number, to: number, value: number) -> number ```

# Layout Source: https://rive.app/docs/scripting/api-reference/interfaces/layout A scripted Layout which can function just like a [Node](/docs/scripting/api-reference/interfaces/node) but also has the ability to fit into a layout box provided via resize. It can also be intrinsically sized allowing hosting layouts to attempt to fit to its size by using the measure function to report desired dimensions. For more information, see [Layout Scripts](/docs/scripting/protocols/layout-scripts). ## Methods ### `measure`

```lua theme={null} measure(self: T) -> Vector ```

When provided this Layout can be intrinsically sized/request to be a specific size. This is not guaranteed as the layout may have min/max dimensions. Resize will be called with the granted size after being measured. ```lua theme={null} -- Measure the computed size of the layout on resize function measure(self: MyLayout): Vector return Vector.xy(100, 100) end ``` ### `resize`

```lua theme={null} resize(self: T, size: Vector) -> () ```

Guaranteed to be called to set initial size and also called whenever the size changes. ```lua theme={null} -- Called when the layout resizes based on the content -- This only applies to Layouts with a fit type of Hug function resize(self: MyLayout, size: Vector) print('Resize:', size) end ``` # ListenerAction Source: https://rive.app/docs/scripting/api-reference/interfaces/listener-action An action performed when an associated [State Machine Listener](/docs/editor/state-machine/listeners) is triggered. For more information, see [Listener Action Scripts](/docs/scripting/protocols/listener-action-scripts). ## Methods ### `init`

```lua theme={null} init(self: T, context: Context) -> boolean ```

Called once when the listener is created or attached. ```lua highlight={4,5,6,12} theme={null} type MyListenerAction = {} -- Called once when the script initializes. function init(self: MyListenerAction, context: Context): boolean return true end function perform(self: MyListenerAction, pointerEvent: PointerEvent) end return function(): ListenerAction return { init = init, perform = perform, } end ``` ### `perform`

```lua theme={null} perform(self: T, pointerEvent: PointerEvent) -> () ```

Called when the associated [State Machine Listener](/docs/editor/state-machine/listeners) is triggered. This method includes a [PointerEvent](/docs/scripting/api-reference/artboards/pointer-event) parameter containing details about the triggering interaction. **Deprecated.** Prefer `performAction` with [ListenerContext](/docs/scripting/api-reference/artboards/listener-context); this overload may be removed. ```lua highlight={9,10,11,17} theme={null} type MyListenerAction = {} function init(self: MyListenerAction, context: Context): boolean return true end -- Add your transition logic here. function perform(self: MyListenerAction, pointerEvent: PointerEvent) -- perform action here end -- Return a factory function that Rive uses to build the Listener Action instance. return function(): ListenerAction return { init = init, perform = perform, } end ``` ### `performAction`

```lua theme={null} performAction(self: T, listenerContext: ListenerContext) -> () ```

Called when the associated [State Machine Listener](/docs/editor/state-machine/listeners) is triggered. This method includes a [ListenerContext](/docs/scripting/api-reference/artboards/listener-context) parameter containing details about the triggering interaction. ```lua highlight={9,10,11,17} theme={null} type MyListenerAction = {} function init(self: MyListenerAction, context: Context): boolean return true end -- Add your transition logic here. -- `evaluate` is fired every frame while the transition is active. -- Returning false prevents a transition, true allows a transition. function performAction(self: MyListenerAction, listenerContext: ListenerContext) return true end -- Return a factory function that Rive uses to build the Listener Action instance. return function(): ListenerAction return { init = init, performAction = performAction, } end ``` # Node Source: https://rive.app/docs/scripting/api-reference/interfaces/node Node scripts can be used to render shapes, images, text, artboards, and more. A scripted node can be attached to any Node and is rendered in the local transform space of the hosting Node. For more information, see [Node Scripts](/docs/scripting/protocols/node-scripts). ## Methods ### `init`

```lua theme={null} init(self: T, context: Context) -> boolean ```

Called once when the node is created. Returns true if initialization succeeds. For a more complete example using `init`, see [Instantiating Components](/docs/scripting/protocols/node-scripts#instantiating-components). ```lua highlight={5,6,7,12} theme={null} -- Define the script's data and inputs. type MyNode = {} -- Called once when the script initializes. function init(self: MyNode, context: Context): boolean return true end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { init = init } end ``` ### `advance`

```lua theme={null} advance(self: T, seconds: number) -> boolean ```

Optional per-frame update. Returns true if the node should continue receiving advance calls. For a more complete example using `advance`, see [Fixed-step Advanced](/docs/scripting/protocols/node-scripts#fixed-step-advance). ```lua highlight={6,7,8,13} theme={null} -- Define the script's data and inputs. type MyNode = {} -- Called every frame to advance the simulation. -- 'seconds' is the elapsed time since the previous frame. function advance(self: MyNode, seconds: number): boolean return false end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { advance = advance, } end ``` ### `update`

```lua theme={null} update(self: T) -> () ```

Called when an input value changes. ```lua highlight={5,6,7,12} theme={null} -- Define the script's data and inputs. type MyNode = {} -- Called when any input value changes. function update(self: MyNode) print('An script input value has changed.') end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { update = update, } end ``` ### `draw`

```lua theme={null} draw(self: T, renderer: Renderer) -> () ```

Called to render the node using the provided [Renderer](/docs/scripting/api-reference/renderer/renderer). For a more complete example using draw, see [Instantiating Components](/docs/scripting/protocols/node-scripts#instantiating-components). ```lua highlight={5,10} theme={null} -- Define the script's data and inputs. type MyNode = {} -- Called every frame (after advance) to render the content. function draw(self: MyNode, renderer: Renderer) end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { draw = draw, } end ``` GPU canvas work (canvas:beginFrame, gpuCanvas:beginRenderPass) also happens here, in any order; replay schedules canvas dependencies. The former drawCanvas callback was removed: move its body into draw. ### `pointerDown`

```lua theme={null} pointerDown(self: T, event: PointerEvent) -> () ```

Pointer event down handler. ```lua theme={null} function handlePointerDown(self: MyGame, event: PointerEvent) print('Pointer Position: ', event.position.x, event.position.y) event:hit() end return function(): Node return { init = init, advance = advance, draw = draw, pointerDown = handlePointerDown, } end ``` ### `pointerMove`

```lua theme={null} pointerMove(self: T, event: PointerEvent) -> () ```

Pointer event move handler. ```lua theme={null} function handlePointerMove(self: MyGame, event: PointerEvent) print('Pointer Position: ', event.position.x, event.position.y) event:hit() end return function(): Node return { init = init, advance = advance, draw = draw, pointerMove = handlePointerMove, } end ``` ### `pointerUp`

```lua theme={null} pointerUp(self: T, event: PointerEvent) -> () ```

Pointer event up handler. ```lua theme={null} function handlePointerUp(self: MyGame, event: PointerEvent) print('Pointer Position: ', event.position.x, event.position.y) event:hit() end return function(): Node return { init = init, advance = advance, draw = draw, pointerUp = handlePointerUp, } end ``` ### `pointerExit`

```lua theme={null} pointerExit(self: T, event: PointerEvent) -> () ```

Pointer event exit handler. ```lua theme={null} function handlePointerExit(self: MyGame, event: PointerEvent) print('Pointer Position: ', event.position.x, event.position.y) event:hit() end return function(): Node return { init = init, advance = advance, draw = draw, pointerExit = handlePointerExit, } end ``` ### `gamepadConnected`

```lua theme={null} gamepadConnected(self: T, event: GamepadConnected) -> () ```

### `gamepadEvent`

```lua theme={null} gamepadEvent(self: T, event: GamepadEvent) -> () ```

### `gamepadDisconnected`

```lua theme={null} gamepadDisconnected(self: T, event: GamepadDisconnected) -> () ```

# Output Source: https://rive.app/docs/scripting/api-reference/interfaces/output Represents a typed output value. (Coming soon) # PathEffect Source: https://rive.app/docs/scripting/api-reference/interfaces/path-effect A scripted effect applied to a path For effects that can change over time, even when the path does not change, markNeedsAdvance() should be called on its context in the advance function For more information, see [Path Effect Scripts](scripting/protocols/path-effect-scripts). ## Methods ### `init`

```lua theme={null} init(self: T, context: Context) -> boolean ```

Called once when the effect is created or attached. Return `true` to keep the effect active, or `false` to disable it. ```lua theme={null} -- Called once when the script initializes. function init(self: MyPathEffect, context: Context): boolean -- Return false to stop the script. return true end ``` ### `update`

```lua theme={null} update(self: T, path: PathData, node: NodeReadData) -> PathData ```

Called any time an input changes. You receive the original [PathData](/docs/scripting/api-reference/path/path-data) and must return the path that should be used for rendering. ```lua theme={null} function update(self: MyPathEffect, inPath: PathData): PathData local path = Path.new() return path end ``` ### `advance`

```lua theme={null} advance(self: T, seconds: number) -> boolean ```

Called every frame to advance the effect over time. `seconds` is the time delta since the last frame. Return `true` to keep the effect active, or `false` to disable it. ```lua theme={null} function advance(self: MyPathEffect, seconds: number): boolean return false end ``` # PropertyEnum Source: https://rive.app/docs/scripting/api-reference/interfaces/property-enum PropertyEnum is a [Property](/docs/scripting/api-reference/data-value/property) with additional enum-specific APIs. ## Methods ### `values`

```lua theme={null} values() -> EnumValues ```

Returns the available enum values ```lua highlight={6} theme={null} local vmi = context:viewModel() if vmi then local textAlignment = vmi:getEnum('textAlignment') if textAlignment then local values = textAlignment:values() end end ``` # PropertyList Source: https://rive.app/docs/scripting/api-reference/interfaces/property-list [PropertyList](/docs/scripting/api-reference/interfaces/property-list) is a mutable list of [ViewModel](/docs/scripting/api-reference/interfaces/view-model) items. Use it to manage repeating data collections from scripts (for example, menu items, inventory entries, or dynamic UI rows). A [PropertyList](/docs/scripting/api-reference/interfaces/property-list) supports: * Reading item count via `length` * 1-based indexed access (`list[1]`, `list[2]`, ...) * Mutations (`push`, `insert`, `swap`, `pop`, `shift`, `clear`) * Change notifications via `addListener` and `removeListener` For a complete working example, see the [Scripting Lists](https://rive.app/community/files/27098-51051-scripting-lists/?utm_source=docs\&utm_medium=scripting_api\&utm_campaign=docs_to_marketplace_links) demo. ## Fields ### `length` The current number of items in the list. ```lua highlight={3} theme={null} function handleSwap(self: MenuListController) if self.menu and self.menu.length >= 2 then self.menu:swap(1, 2) end end ``` ### `addListener` Adds a listener that is called when the list changes. ```lua highlight={6} theme={null} function init(self: MenuListController, context: Context): boolean local vmi = context:rootViewModel() :: Data.Main if vmi then self.menu = vmi.menu self.listChanged = listChanged self.menu:addListener(self.listChanged) else print('[MenuListController] Warning: Could not find Main ViewModel.') end return true end ``` ### `removeListener` Removes a previously added list-change listener. ```lua highlight={3} theme={null} function handleRemoveListener(self: MenuListController) if self.menu and self.listChanged then self.menu:removeListener(self.listChanged) end end ``` ## Methods ### `push`

```lua theme={null} push(vm: ViewModel) -> () ```

Get the list item by index. ```lua highlight={3} theme={null} function setItemLabel(menu: PropertyList, index: number, label: string) if index >= 1 and index <= menu.length then local item = menu[index] :: Data.Button local itemLabel = item:getString('label') if itemLabel then itemLabel.value = label end end end ``` Adds a view model to the end of the list. ```lua highlight={9} theme={null} function addButton(menu: PropertyList, label: string) local buttonVm = Data.Button.new() local buttonLabel = buttonVm:getString('label') if buttonLabel then buttonLabel.value = label end menu:push(buttonVm) end ``` ### `insert`

```lua theme={null} insert(vm: ViewModel, index: number) -> () ```

Inserts a view model at the given index. ```lua highlight={10} theme={null} function insertAt(menu: PropertyList, label: string, index: number) local buttonVm = Data.Button.new() local buttonLabel = buttonVm:getString('label') if buttonLabel then buttonLabel.value = label end local insertIndex = math.max(1, math.min(index, menu.length + 1)) menu:insert(buttonVm, insertIndex) end ``` ### `swap`

```lua theme={null} swap(index1: number, index2: number) -> () ```

Swaps the positions of the view models at `index1` and `index2`. ```lua highlight={5} theme={null} function swapItems(menu: PropertyList, index1: number, index2: number) local highestIndex = math.max(index1, index2) if menu and menu.length >= highestIndex then menu:swap(index1, index2) end end ``` ### `pop`

```lua theme={null} pop() -> ViewModel? ```

Removes and returns the last view model in the list. ```lua highlight={3} theme={null} function handlePop(self: MenuListController) if self.menu then self.menu:pop() end end ``` ### `shift`

```lua theme={null} shift() -> ViewModel? ```

Removes and returns the first view model in the list. ```lua highlight={2} theme={null} function handleShift(self: MenuListController) if self.menu then self.menu:shift() end end ``` ### `clear`

```lua theme={null} clear() -> () ```

Removes all view models from the list. ```lua highlight={3} theme={null} function handleClearItems(self: MenuListController) if self.menu then self.menu:clear() end end ``` ### `remove`

```lua theme={null} remove(viewModel: ViewModel) -> () ```

Removes a view model from the list. ### `removeAllOf`

```lua theme={null} removeAllOf(viewModel: ViewModel) -> () ```

Removes every list entry that references the given view model instance. ### `removeAt`

```lua theme={null} removeAt(index: number) -> () ```

Removes the view model at the given 1-based index from the list. # PropertyViewModel Source: https://rive.app/docs/scripting/api-reference/interfaces/property-view-model Represents a property that holds a [ViewModel](/docs/scripting/api-reference/interfaces/view-model) value. ## Fields ### `value` The current view model value. ```lua highlight={6} theme={null} function init(self: VMNameNode, context: Context): boolean local vm = context:viewModel() if vm then local nestedVMProp = vm:getViewModel("nestedVM") if nestedVMProp then local nestedVM = nestedVMProp.value local age = nestedVM:getNumber("age") if age then print("nestedVM age:", age.value) else print("'age' property not found on nestedVM.") end else print("'nestedVM' property not found on ViewModel.") end else print("No ViewModel found on context.") end return true end ``` # TransitionCondition Source: https://rive.app/docs/scripting/api-reference/interfaces/transition-condition A condition to evaluate for a transition between state machine states to be taken. For more information, see [Transition Condition Scripts](/docs/scripting/protocols/transition-condition-scripts). ## Methods ### `init`

```lua theme={null} init(self: T, context: Context) -> boolean ```

Called once when the transition condition is created or attached. ```lua highlight={4,5,6,14} theme={null} type MyTransitionCondition = {} -- Called once when the script initializes. function init(self: MyTransitionCondition, context: Context): boolean return true end function evaluate(self: MyTransitionCondition): boolean return false end return function(): TransitionCondition return { init = init, evaluate = evaluate, } end ``` ### `evaluate`

```lua theme={null} evaluate(self: T) -> boolean ```

Called every frame while the transition is active. ```lua highlight={4,5,6,14} theme={null} type MyTransitionCondition = {} function init(self: MyTransitionCondition, context: Context): boolean return true end -- Add your transition logic here. -- `evaluate` is fired every frame while the transition is active. -- Returning false prevents a transition, true allows a transition. function evaluate(self: MyTransitionCondition): boolean return false end return function(): TransitionCondition return { init = init, evaluate = evaluate, } end ``` # Trigger Source: https://rive.app/docs/scripting/api-reference/interfaces/trigger A function that triggers an action when invoked. ```lua highlight={3} theme={null} -- Define the script's data and inputs. type MyNode = { onReset: Input, } -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { onReset = function() end, } end ``` # ViewModel Source: https://rive.app/docs/scripting/api-reference/interfaces/view-model A [ViewModel](/docs/scripting/api-reference/interfaces/view-model) provides access to named properties used for data binding between your application and a Rive file. ## Fields ### `name` The name of the view model. (Coming soon) ## Methods ### `getNumber`

```lua theme={null} getNumber(name: string) -> Property? ```

Returns the numeric property with the given name, or nil if not found. ```lua theme={null} local vmi = context:viewModel() if vmi then local score = vmi:getNumber('score') if score then print(score.value) end end ``` ### `getTrigger`

```lua theme={null} getTrigger(name: string) -> PropertyTrigger? ```

Looks up a trigger property by name. Returns a [PropertyTrigger](/docs/scripting/api-reference/data-value/property-trigger). ```lua theme={null} local vmi = context:viewModel() if vmi then local myTrigger = vmi:getTrigger('myTrigger') if myTrigger then myTrigger:fire() end end ``` ### `getString`

```lua theme={null} getString(name: string) -> Property? ```

Looks up a string property by name. Returns a [DataValueString](/docs/scripting/api-reference/data-value/data-value-string). ```lua theme={null} local vmi = context:viewModel() if vmi then local heading = vmi:getString('heading') if heading then print(heading.value) end end ``` ### `getBoolean`

```lua theme={null} getBoolean(name: string) -> Property? ```

Looks up a boolean property by name. Returns a [DataValueBoolean](/docs/scripting/api-reference/data-value/data-value-boolean). ```lua theme={null} local vmi = context:viewModel() if vmi then local darkMode = vmi:getBoolean('darkMode') if darkMode then print(darkMode.value) end end ``` ### `getColor`

```lua theme={null} getColor(name: string) -> Property? ```

Looks up a color property by name. Returns a [DataValueColor](/docs/scripting/api-reference/data-value/data-value-color). ```lua theme={null} local vmi = context:viewModel() if vmi then local primaryColor = vmi:getColor('primaryColor') if primaryColor then primaryColor.value = Color.rgba(255, 0, 0, 155) end end ``` ### `getList`

```lua theme={null} getList(name: string) -> PropertyList? ```

Looks up a List property by name. Returns a [PropertyList](/docs/scripting/api-reference/interfaces/property-list). ```lua theme={null} local vmi = context:viewModel() if vmi then local enemies = vmi:getList('enemies') if enemies then enemies:pop() end end ``` ### `getViewModel`

```lua theme={null} getViewModel(name: string) -> PropertyViewModel? ```

Looks up a view model property by name. Returns a [PropertyViewModel](/docs/scripting/api-reference/interfaces/property-view-model). ```lua highlight={3} theme={null} local vmi = context:viewModel() if vmi then local nestedVM = vmi:getViewModel('MyVM') end ``` ### `getEnum`

```lua theme={null} getEnum(name: string) -> PropertyEnum? ```

Looks up an enum by name. Returns a [PropertyEnum](/docs/scripting/api-reference/interfaces/property-enum). ```lua highlight={3} theme={null} local vmi = context:viewModel() if vmi then local textAlignment = vmi:getEnum('textAlignment') end ``` ### `instance`

```lua theme={null} instance(instanceName: string?) -> ViewModel ```

Creates a new instance of the ViewModel. Pass instanceName to specify an existing instance from the file to use as template ```lua highlight={4} theme={null} function init(self: VMNameNode, context: Context): boolean local vm = context:viewModel() if vm then local newInstance = vm:instance() local age = newInstance:getNumber('age') if age then age.value = 99 end end return true end ``` ### `getIndex`

```lua theme={null} getIndex() -> number ```

Returns the index. Returns -1 if view model does not have an index available. ### `getImage`

```lua theme={null} getImage(name: string) -> Property? ```

Looks up an image by name. Returns a `Property`. ```lua highlight={3} theme={null} local vmi = context:viewModel() if vmi then local image1 = vmi:getImage('avatar') end ``` ### `getFont`

```lua theme={null} getFont(name: string) -> Property? ```

Looks up a font by name. Returns a `Property`. ```lua highlight={3} theme={null} local vm = context:viewModel() if vm then local fontProperty = vm:getFont('Inter') end ``` ### `getBlob`

```lua theme={null} getBlob(name: string) -> Property? ```

Looks up a blob by name. Returns a `Property`. ```lua highlight={3} theme={null} local vm = context:viewModel() if vm then local blobProperty = vm:getBlob('myBlob') end ``` # DateTypeArg Source: https://rive.app/docs/scripting/api-reference/luau/date-type-arg ## Fields ### `year` ### `month` ### `day` ### `hour` ### `min` ### `sec` ### `isdst` # DateTypeResult Source: https://rive.app/docs/scripting/api-reference/luau/date-type-result ## Fields ### `year` ### `month` ### `wday` ### `yday` ### `day` ### `hour` ### `min` ### `sec` ### `isdst` # vector Source: https://rive.app/docs/scripting/api-reference/luau/vector ## Fields ### `x` ### `y` ### `z` # Mat2D Source: https://rive.app/docs/scripting/api-reference/mat2d/mat2d Represents a 2D transformation matrix with components for scaling, rotation, shear, and translation. ```lua theme={null} -- Construct a matrix manually local m = Mat2D.identity() m.xx = 2 -- scale x m.yy = 3 -- scale y m.tx = 50 -- translate x m.ty = 100 -- translate y local r = m * Vector.xy(10, 20) -- (10,20) → (20,60) → (70,160) print(r.x, r.y) -- 70, 160 ``` ## Fields ### `xx` The xx component of the matrix. ```lua highlight={4} theme={null} local m = Mat2D.identity() -- Double horizontal scale m.xx = 2 local r = m * Vector.xy(10, 5) print(r.x, r.y) -- 20, 5 ``` ### `xy` The xy component of the matrix. ```lua highlight={4} theme={null} local m = Mat2D.identity() -- Add horizontal skew m.xy = 1 local r = m * Vector.xy(10, 5) -- x = 10 + (1 * 5) print(r.x, r.y) -- 15, 5 ``` ### `yx` The yx component of the matrix. ```lua highlight={4} theme={null} local m = Mat2D.identity() -- Add vertical skew m.yx = 1 local r = m * Vector.xy(10, 5) -- y = 5 + (1 * 10) print(r.x, r.y) -- 10, 15 ``` ### `yy` The yy component of the matrix. ```lua highlight={4} theme={null} local m = Mat2D.identity() -- Triple vertical scale m.yy = 3 local r = m * Vector.xy(4, 5) print(r.x, r.y) -- 4, 15 ``` ### `tx` Translation along the x-axis. ```lua highlight={3} theme={null} local m = Mat2D.identity() m.tx = 50 local r = m * Vector.xy(10, 20) print(r.x, r.y) -- 60, 20 ``` ### `ty` Translation along the y-axis. ```lua highlight={3} theme={null} local m = Mat2D.identity() m.ty = 100 local r = m * Vector.xy(10, 20) print(r.x, r.y) -- 10, 120 ``` ### `withTranslation` Creates a translation matrix from the given x and y values or from a [Vector](/docs/scripting/api-reference/vector/vector) position. ```lua highlight={2,6} theme={null} -- From numbers local t1 = Mat2D.withTranslation(50, 100) -- From a Vector local pos = Vector.xy(50, 100) local t2 = Mat2D.withTranslation(pos) ``` ### `withScale` Creates a scale matrix from the given x and y values or from a [Vector](/docs/scripting/api-reference/vector/vector). ```lua highlight={2,5,9} theme={null} -- Uniform scale (y defaults to x if omitted) local s1 = Mat2D.withScale(2) -- Non-uniform scale local s2 = Mat2D.withScale(2, 3) -- From a Vector local scale = Vector.xy(2, 3) local s3 = Mat2D.withScale(scale) ``` ### `withScaleAndTranslation` Creates a scale-and-translation matrix from numeric values or vectors. ```lua highlight={4,14} theme={null} -- Numbers Overloaded -- Scale by (2, 3) then translate by (50, 100) local st = Mat2D.withScaleAndTranslation(2, 3, 50, 100) local p = Vector.xy(10, 20) local r = st * p -- (10,20) -> scaled (20,60) -> translated (70,160) print(r.x, r.y) -- 70, 160 -- Vectors Overloaded local st = Mat2D.withScaleAndTranslation( Vector.xy(2, 3), -- scale Vector.xy(50, 100) -- position / translation ) local r = st * Vector.xy(10, 20) print(r.x, r.y) -- 70, 160 ``` ## Constructors ### `values`

```lua theme={null} values(xx: number, xy: number, yx: number, yy: number, tx: number, ty: number) -> Mat2D ```

Creates a matrix using the specified components. ```lua theme={null} -- xx=1, xy=skewX (horizontal skew), yx=skewY (vertical skew), yy=1, tx=0, ty=0 local newMat = Mat2D.values(1, self.skewY, self.skewX, 1, 0, 0) ``` ### `identity`

```lua theme={null} identity() -> Mat2D ```

Returns the identity matrix. ```lua theme={null} -- xx = 1, xy = 0, yx = 0, yy = 1, tx = 0, ty = 0 local newMat = Mat2D.identity() ``` ### `withRotation`

```lua theme={null} withRotation(radians: number) -> Mat2D ```

Creates a rotation matrix from the given angle in radians. ```lua highlight={1} theme={null} local rot = Mat2D.withRotation(math.rad(90)) local r = rot * Vector.xy(1, 0) print(math.floor(r.x + 0.5), math.floor(r.y + 0.5)) -- 0, 1 ``` ## Static Functions ### `invert`

```lua theme={null} invert(output: Mat2D, input: Mat2D) -> boolean ```

Writes the inverse of 'input' into 'output'. Returns true if the input matrix is invertible. ```lua highlight={4} theme={null} local m = Mat2D.withTranslation(50, 100) local inv = Mat2D.identity() local ok = Mat2D.invert(inv, m) print(ok) -- true local p = Vector.xy(10, 20) local r = inv * (m * p) -- Applying m then inv returns the original point print(r.x, r.y) -- 10, 20 ``` ## Methods ### `invert`

```lua theme={null} invert() -> Mat2D? ```

Provides indexed access to the matrix components. ```lua theme={null} local m = Mat2D.identity() -- Indices map to: xx, xy, yx, yy, tx, ty m[1] = 2 -- xx m[5] = 50 -- tx print(m[1], m.xx) -- 2, 2 print(m[5], m.tx) -- 50, 50 ``` Returns the inverse of the matrix, or nil if the matrix is not invertible. ```lua highlight={2} theme={null} local m = Mat2D.withTranslation(50, 100) local inv = m:invert() if inv then local p = Vector.xy(10, 20) local result = inv * (m * p) print(result.x, result.y) -- 10, 20 end ``` ### `isIdentity`

```lua theme={null} isIdentity() -> boolean ```

Returns true if the matrix is the identity transform. ```lua theme={null} local newMat = Mat2D.identity() print(newMat:isIdentity()) ``` ### `__eq`

```lua theme={null} __eq(rhs: Mat2D) -> boolean ```

Returns true if all components of the two matrices are equal. ```lua highlight={4} theme={null} local a = Mat2D.values(1, 0, 0, 1, 0, 0) local b = Mat2D.identity() print(a == b) -- true ``` ### `__mul`

```lua theme={null} __mul(rhs: Vector) -> Vector ```

Transforms the given [Vector](/docs/scripting/api-reference/vector/vector) by the matrix and returns the result. ```lua highlight={5} theme={null} local translation = Mat2D.values(1, 0, 0, 1, 50, 100) local point = Vector.xy(10, 20) -- Multiply matrix by vector local result = translation * point print(result.x, result.y) -- 60, 120 ``` ### `__mul`

```lua theme={null} __mul(rhs: Mat2D) -> Mat2D ```

Returns the matrix product of this matrix and the given matrix ```lua highlight={5} theme={null} local translation = Mat2D.values(1, 0, 0, 1, 50, 100) local scale = Mat2D.values(2, 0, 0, 2, 0, 0) -- Combine transforms local combined = translation * scale local point = Vector.xy(10, 20) local result = combined * point print(result.x, result.y) -- 70, 140 ``` # Mat4 Source: https://rive.app/docs/scripting/api-reference/mat4/mat4 Represents a 4x4 column-major transformation matrix, suitable for 3D transforms and direct upload to a GPU uniform buffer. ```lua theme={null} -- Construct an MVP matrix local proj = Mat4.perspective(math.rad(60), 16 / 9, 0.1, 100) local view = Mat4.fromTranslation(0, 0, -3) -- camera 3 units back local model = Mat4.fromRotationY(angle) local mvp = proj * view * model -- Upload to a uniform buffer (64 bytes, column-major) mvp:writeToBuffer(uboBytes, 0) ``` ## Fields ### `m11` Element at row R, column C (1-indexed). For example `m.m12` is the entry in row 1, column 2. ```lua theme={null} local m = Mat4.identity() m.m11 = 2 -- scale x m.m22 = 3 -- scale y m.m14 = 50 -- translate x ``` ### `m12` ### `m13` ### `m14` ### `m21` ### `m22` ### `m23` ### `m24` ### `m31` ### `m32` ### `m33` ### `m34` ### `m41` ### `m42` ### `m43` ### `m44` ## Constructors ### `identity`

```lua theme={null} identity() -> Mat4 ```

Returns the 4x4 identity matrix. ### `values`

```lua theme={null} values(c0x: number, c0y: number, c0z: number, c0w: number, c1x: number, c1y: number, c1z: number, c1w: number, c2x: number, c2y: number, c2z: number, c2w: number, c3x: number, c3y: number, c3z: number, c3w: number) -> Mat4 ```

Creates a matrix from 16 components, supplied column-major (column 0 first: c0x, c0y, c0z, c0w, c1x, ...). ### `fromTranslation`

```lua theme={null} fromTranslation(x: number, y: number, z: number) -> Mat4 ```

Creates a translation matrix. ```lua theme={null} local t = Mat4.fromTranslation(10, 20, 30) ``` ### `fromScale`

```lua theme={null} fromScale(x: number, y: number?, z: number?) -> Mat4 ```

Creates a scale matrix. If `y` and `z` are omitted, uniform scaling by `x` is applied to all axes. ```lua theme={null} local s1 = Mat4.fromScale(2) -- uniform 2x local s2 = Mat4.fromScale(1, 2, 1) -- 2x in Y only ``` ### `fromRotationX`

```lua theme={null} fromRotationX(radians: number) -> Mat4 ```

Creates a rotation matrix around the X axis (radians). ### `fromRotationY`

```lua theme={null} fromRotationY(radians: number) -> Mat4 ```

Creates a rotation matrix around the Y axis (radians). ### `fromRotationZ`

```lua theme={null} fromRotationZ(radians: number) -> Mat4 ```

Creates a rotation matrix around the Z axis (radians). ### `perspective`

```lua theme={null} perspective(fovY: number, aspect: number, near: number, far: number) -> Mat4 ```

Creates a right-handed perspective projection matrix that maps z to the \[0, 1] NDC depth range. `fovY` is in radians; `near` and `far` are positive distances. ```lua theme={null} local proj = Mat4.perspective(math.rad(60), 16 / 9, 0.1, 100) ``` ### `perspectiveReverseZ`

```lua theme={null} perspectiveReverseZ(fovY: number, aspect: number, near: number) -> Mat4 ```

Right-handed perspective with reverse-Z (near -> 1, far -> 0) and an infinite far plane. Combined with a float depth buffer this gives a near-uniform 1/z depth distribution across the entire frustum — the best precision an arbitrary scene can achieve. The depth buffer must be cleared to 0 (not 1) and the depth test flipped to GREATER. ```lua theme={null} local proj = Mat4.perspectiveReverseZ(math.rad(60), 16 / 9, 0.1) ``` ### `lookAt`

```lua theme={null} lookAt(eye: Vector, center: Vector, up: Vector) -> Mat4 ```

Creates a right-handed view matrix looking from `eye` toward `center` (GLM convention). `up` need not be normalized. ```lua theme={null} local view = Mat4.lookAt(Vector.xyz(0, 2, 5), Vector.origin(), Vector.xyz(0, 1, 0)) ``` ### `ortho`

```lua theme={null} ortho(left: number, right: number, bottom: number, top: number, near: number, far: number) -> Mat4 ```

Creates a right-handed orthographic projection matrix that maps z to the \[0, 1] NDC depth range (matching `Mat4.perspective`), e.g. for shadow-map cascades or 2D overlays. ```lua theme={null} local proj = Mat4.ortho(-10, 10, -10, 10, 0.1, 100) ``` ### `multiply`

```lua theme={null} multiply(output: Mat4, a: Mat4, b: Mat4) -> Mat4 ```

Writes `a * b` into `output`, reusing its storage. Returns `output`. Use this in tight loops to avoid allocating a new [Mat4](/docs/scripting/api-reference/mat4/mat4) per multiplication. `output` may alias `a` or `b`. ```lua theme={null} local out = Mat4.identity() for i = 1, 1000 do Mat4.multiply(out, view, model) end ``` ### `multiplyAffine`

```lua theme={null} multiplyAffine(output: Mat4, a: Mat4, b: Mat4) -> Mat4 ```

Like `Mat4.multiply`, but assumes both inputs are affine (bottom row \[0, 0, 0, 1] — any composition of translation/scale/rotation matrices qualifies). Skips the bottom-row work for \~25% fewer FLOPs per multiplication. The result is always affine. Caller must ensure both inputs are affine; passing a non-affine input gives an incorrect result. ```lua highlight={3} theme={null} local world = Mat4.identity() for _, bone in ipairs(bones) do Mat4.multiplyAffine(world, parent, bone.local) end ``` ## Static Functions ### `invert`

```lua theme={null} invert(output: Mat4, input: Mat4) -> boolean ```

Writes the inverse of `input` into `output`, returning true on success or false if `input` is singular. ```lua theme={null} local inv = Mat4.identity() local ok = Mat4.invert(inv, m) ``` ### `invertAffine`

```lua theme={null} invertAffine(output: Mat4, input: Mat4) -> boolean ```

Writes the affine inverse of `input` into `output`. See `Mat4:invertAffine` for the contract; faster than `Mat4.invert`. ## Methods ### `invert`

```lua theme={null} invert() -> Mat4? ```

Linear column-major access. Indices 1..4 are column 0, 5..8 are column 1, 9..12 are column 2, 13..16 are column 3 (translation). ```lua theme={null} local m = Mat4.identity() m[13] = 50 -- translate x m[14] = 100 -- translate y m[15] = 25 -- translate z ``` Returns the inverse of the matrix, or `nil` if the matrix is singular. ```lua highlight={2} theme={null} local m = Mat4.fromTranslation(50, 100, 25) local inv = m:invert() ``` ### `transpose`

```lua theme={null} transpose() -> Mat4 ```

Returns the transpose of the matrix. ```lua highlight={2} theme={null} local m = Mat4.fromRotationY(math.rad(45)) local t = m:transpose() ``` ### `transformPoint`

```lua theme={null} transformPoint(x: number, y: number, z: number) -> Vector ```

Transforms the given 3D point by the matrix (treating w = 1) and returns the result as a [Vector](/docs/scripting/api-reference/vector/vector). If the homogeneous w of the result is non-unit (e.g. after a perspective matrix), the returned point is divided through. ```lua highlight={3} theme={null} local m = Mat4.fromTranslation(10, 20, 30) local p = m:transformPoint(1, 2, 3) print(p.x, p.y, p.z) -- 11, 22, 33 ``` ### `transformVec4`

```lua theme={null} transformVec4(x: number, y: number, z: number, w: number) -> (number, number, number, number) ```

Transforms the given homogeneous 4D vector by the matrix and returns the four components as multiple values, without perspective divide. Use this when the caller needs to inspect or carry the homogeneous `w` (e.g. clip-space coordinates). ```lua highlight={2} theme={null} local mvp = proj * view * model local x, y, z, w = mvp:transformVec4(px, py, pz, 1) ``` ### `writeToBuffer`

```lua theme={null} writeToBuffer(buf: buffer, byteOffset: number) -> () ```

Writes the matrix as 64 bytes (column-major, 16 float32 entries) into the given buffer at `byteOffset`. The buffer must have at least 64 bytes available from the offset. ```lua highlight={3} theme={null} local mvp = Mat4.identity() local ubo = buffer.create(64) mvp:writeToBuffer(ubo, 0) ``` ### `__eq`

```lua theme={null} __eq(rhs: Mat4) -> boolean ```

Returns true if all 16 components of the two matrices are equal. ### `__mul`

```lua theme={null} __mul(rhs: Mat4) -> Mat4 ```

Returns the matrix product of two matrices. Useful for composing transforms, e.g. `proj * view * model`. Allocates a new [Mat4](/docs/scripting/api-reference/mat4/mat4); in tight loops prefer `Mat4.multiply(out, a, b)` to reuse storage. ### `invertAffine`

```lua theme={null} invertAffine() -> Mat4? ```

Closed-form inverse for affine matrices (bottom row \[0, 0, 0, 1] — any composition of `fromTranslation`/`fromScale`/`fromRotationX/Y/Z` qualifies). Returns nil if the linear part is singular. Faster than `:invert()` and avoids the full 4x4 cofactor work. ```lua highlight={2} theme={null} local m = Mat4.fromTranslation(3, -4, 5) * Mat4.fromRotationY(0.4) local inv = m:invertAffine() ``` # BlendMode Source: https://rive.app/docs/scripting/api-reference/paint/blend-mode Defines how the paint’s color or gradient is composited with the content behind it. * `srcOver` * `screen` * `overlay` * `darken` * `lighten` * `colorDodge` * `colorBurn` * `hardLight` * `softLight` * `difference` * `exclusion` * `multiply` * `hue` * `saturation` * `color` * `luminosity` ```lua highlight={4} theme={null} -- Create a new paint with a color and multiply blend mode self.paint = Paint.with({ color = Color.rgb(255, 100, 50), blendMode = 'multiply', style = 'fill', }) ``` # Paint Source: https://rive.app/docs/scripting/api-reference/paint/paint Describes how shapes are drawn, including fill or stroke style, thickness, color, gradient, and blending behavior. ## Fields ### `style` Painting style of type [PaintStyle](/docs/scripting/api-reference/paint/paint-style). ```lua highlight={3} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), style = 'stroke', }) ``` ### `join` Stroke join behavior for corners. See [StrokeJoin](/docs/scripting/api-reference/paint/stroke-join). ```lua highlight={3} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), cap = 'round', style = 'stroke', }) ``` ### `cap` Stroke cap used for line endings. See [StrokeCap](/docs/scripting/api-reference/paint/stroke-cap). ```lua highlight={3} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), join = 'round', style = 'stroke', }) ``` ### `thickness` Thickness of the stroked path. ```lua highlight={3} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), thickness = 4, style = 'stroke', }) ``` ### `blendMode` Blending mode used when compositing. See [BlendMode](/docs/scripting/api-reference/paint/blend-mode). ```lua highlight={4} theme={null} -- Create a new paint with a color and multiply blend mode self.paint = Paint.with({ color = Color.rgb(255, 100, 50), blendMode = 'multiply', style = 'fill', }) ``` ### `feather` Feathering amount. ```lua highlight={3} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), feather = 4, style = 'stroke', }) ``` ### `gradient` [Gradient](/docs/scripting/api-reference/gradient/gradient) applied to fill (if present). ```lua highlight={8} theme={null} local g = Gradient.linear(Vector.xy(0, 0), Vector.xy(10, 0), { { position = 0, color = Color.rgb(255, 0, 0) }, { position = 1, color = Color.rgb(0, 0, 255) }, }) self.paint = Paint.with({ color = Color.rgb(255, 100, 50), gradient = g, style = 'fill', }) ``` ### `color` Color. See [Color](/docs/scripting/api-reference/color/color). ```lua highlight={2} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), style = 'fill', }) ``` ## Constructors ### `new`

```lua theme={null} new() -> Paint ```

Creates a new [Paint](/docs/scripting/api-reference/paint/paint) object with default settings. ```lua theme={null} local paint = Paint.new() paint.style = 'fill' paint.color = Color.rgb(255, 200, 80) ``` ### `with`

```lua theme={null} with(values: PaintDefinition) -> Paint ```

Creates a new Paint initialized from the provided [PaintDefinition](/docs/scripting/api-reference/paint/paint-definition). ```lua theme={null} local strokePaint = Paint.with({ style = 'stroke', thickness = 3, color = Color.hex('#FF0066'), join = 'round', cap = 'round', }) ``` ## Methods ### `copy`

```lua theme={null} copy(values: PaintDefinition?) -> Paint ```

Returns a new Paint that copies this one, optionally overriding selected properties with values from the provided [PaintDefinition](/docs/scripting/api-reference/paint/paint-definition). Returns a new [Paint](/docs/scripting/api-reference/paint/paint) instance. ```lua highlight={6,7,8,9} theme={null} local base = Paint.with({ style = 'fill', color = Color.rgb(255, 0, 0), }) local outline = base:copy({ style = 'stroke', thickness = 4, }) ``` # PaintDefinition Source: https://rive.app/docs/scripting/api-reference/paint/paint-definition A partial set of paint properties used to initialize or update a Paint instance. All fields are optional. ## Fields ### `style` The painting style (stroke or fill). ```lua theme={null} local paint = Paint.new() paint.style = 'fill' ``` ### `join` Stroke join behavior for corners. ```lua theme={null} local paint = Paint.new() paint.join = 'round' ``` ### `cap` Stroke cap used for line endings. ```lua theme={null} local paint = Paint.new() paint.cap = 'round' ``` ### `thickness` Thickness of the stroked path. ```lua theme={null} local paint = Paint.new() paint.thickness = 4, ``` ### `blendMode` Blending mode used when compositing. ```lua theme={null} local paint = Paint.new() paint.blendMode = 'multiply', ``` ### `feather` Feathering amount. ```lua theme={null} local paint = Paint.new() paint.feather = 3, ``` ### `gradient` [Gradient](/docs/scripting/api-reference/gradient/gradient) fill applied to the paint. If explicitly set to `false`, removes any existing gradient. ```lua highlight={7} theme={null} local g = Gradient.linear(Vector.xy(0, 0), Vector.xy(10, 0), { { position = 0, color = Color.rgb(255, 0, 0) }, { position = 1, color = Color.rgb(0, 0, 255) }, }) local paint = Paint.new() paint.gradient = g ``` ### `color` Color. See [Color](/docs/scripting/api-reference/color/color). # PaintStyle Source: https://rive.app/docs/scripting/api-reference/paint/paint-style Specifies how the shape should be painted. * `stroke` * `fill` ```lua highlight={3} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), style = 'stroke', }) ``` # StrokeCap Source: https://rive.app/docs/scripting/api-reference/paint/stroke-cap Defines the shape used at the ends of open stroke segments. * `butt` – squared, no extension. * `round` – semicircular cap. * `square` – squared, extends past the end point. ```lua highlight={3} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), cap = 'round', style = 'stroke', }) ``` # StrokeJoin Source: https://rive.app/docs/scripting/api-reference/paint/stroke-join Defines how two stroke segments are joined at a corner. * `miter` – sharp corner. * `round` – rounded corner. * `bevel` – flattened corner. ```lua highlight={3} theme={null} self.paint = Paint.with({ color = Color.rgb(255, 100, 50), join = 'round', style = 'stroke', }) ``` # CommandType Source: https://rive.app/docs/scripting/api-reference/path/command-type Describes the type of drawing command stored in a [PathCommand](/docs/scripting/api-reference/path/path-command). For more information on the following command types, see [Path](/docs/scripting/api-reference/path/path). * `none` – Placeholder command with no effect. You should not normally see this. * `moveTo` * `lineTo` * `cubicTo` * `quadTo` * `close` ```lua highlight={5} theme={null} local path = Path.new() path:moveTo(Vector.xy(0, 0)) path:lineTo(Vector.xy(10, 0)) for i, command in ipairs(path) do print(i, command.type) end -- 1 moveTo -- 2 lineTo ``` # ContourMeasure Source: https://rive.app/docs/scripting/api-reference/path/contour-measure A ContourMeasure is a way to measure and manipulate a single contour within a path. A contour is one continuous drawing sequence that starts with a `moveTo` and continues until the next `moveTo` (or the end of the path). ## Fields ### `next` Returns the next [ContourMeasure](/docs/scripting/api-reference/path/contour-measure) in the path, or nil if this is the last contour. Use this to iterate through all contours in a path after calling path:contours(). ```lua theme={null} local contour = pathData:contours() while contour do print(contour.length) contour = contour.next end ``` # Path Source: https://rive.app/docs/scripting/api-reference/path/path Path is a mutable path object that can be drawn by a Renderer. An unchanged path can be drawn multiple times per frame. However, if you mutate it (via moveTo, lineTo, cubicTo, add, etc.) after drawing, you must wait until the next frame to draw it again. ## Constructors ### `new`

```lua theme={null} new() -> Path ```

```lua highlight={2} theme={null} local path = Path.new() path:moveTo(Vector.xy(0, 0)) ``` ## Methods ### `moveTo`

```lua theme={null} moveTo(to: Vector) -> () ```

Moves the current point to the specified location, starting a new contour. ```lua theme={null} path:moveTo(Vector.xy(0, 0)) ``` ### `lineTo`

```lua theme={null} lineTo(to: Vector) -> () ```

Adds a straight line segment from the current point to the specified point. ```lua theme={null} path:lineTo(Vector.xy(10, 0)) ``` ### `quadTo`

```lua theme={null} quadTo(control: Vector, to: Vector) -> () ```

Adds a quadratic Bézier curve from the current point to the specified point, using the control point to define the curve shape. ```lua theme={null} path:quadTo( Vector.xy(-50, -50), -- control point Vector.xy(0, 0) -- end point ) ``` ### `cubicTo`

```lua theme={null} cubicTo(controlOut: Vector, controlIn: Vector, to: Vector) -> () ```

Adds a cubic Bézier curve from the current point to the specified point, using `controlOut` for the start tangent and `controlIn` for the end tangent. ```lua theme={null} path:cubicTo( Vector.xy(25, -40), -- control point out Vector.xy(75, 40), -- control point in Vector.xy(100, 0) -- end point ) ``` ### `close`

```lua theme={null} close() -> () ```

Closes the current contour by adding a line segment from the current point back to the first point of the contour (the last `moveTo`). ```lua theme={null} -- Draw a rectangle path:moveTo(Vector.xy(-10, -10)) path:lineTo(Vector.xy(10, -10)) path:lineTo(Vector.xy(10, 10)) path:lineTo(Vector.xy(-10, 10)) -- Close the path path:close() ``` ### `__len`

```lua theme={null} __len() -> number ```

Each entry is a [PathCommand](/docs/scripting/api-reference/path/path-command) describing one segment or action in the path. ```lua theme={null} local cmd = path[1] print(cmd.type) ``` Returns the number of commands in the path. ```lua theme={null} local count = #path print(count) ``` ### `reset`

```lua theme={null} reset() -> () ```

Do not mutate or reset a [Path](/docs/scripting/api-reference/path/path) in the same frame after drawing it. If you need to change it, wait until the next frame. Only call `reset` on subsequent frames if you've called `Renderer.drawPath` with it. ```lua theme={null} path:reset() ``` ### `add`

```lua theme={null} add(other: PathData, transform: Mat2D?) -> () ```

Appends the commands from `other` onto this path. If `transform` is provided, the appended commands are transformed as they are added. ```lua theme={null} local dst = Path.new() local src = Path.new() src:moveTo(Vector.xy(0, 0)) src:lineTo(Vector.xy(10, 0)) src:lineTo(Vector.xy(10, 10)) src:close() -- Add `src` into `dst` (optionally with a transform) dst:add(src) ``` ### `contours`

```lua theme={null} contours() -> ContourMeasure? ```

Returns a [ContourMeasure](/docs/scripting/api-reference/path/contour-measure) for the first contour in the path. A contour is a sequence of path segments starting at a `moveTo` and ending before the next `moveTo` (or end of path). Use the `next` property on the returned [ContourMeasure](/docs/scripting/api-reference/path/contour-measure) to iterate through subsequent contours. Returns `nil` if the path has no contours. ```lua theme={null} local contour = path:contours() while contour do print(contour.length) contour = contour.next end ``` ### `measure`

```lua theme={null} measure() -> PathMeasure ```

```lua theme={null} __len() -> number ```

The number of points varies depending on the command type: * `moveTo`: 1 point * `lineTo`: 1 point * `quadTo`: 2 points * `cubicTo`: 3 points * `close`: 0 points ```lua highlight={11} theme={null} local path = Path.new() path:moveTo(Vector.xy(0, 0)) path:cubicTo( Vector.xy(25, -40), Vector.xy(75, 40), Vector.xy(100, 0) ) local command = path[2] print(command.type) -- cubicTo print(#command) -- 3 ``` Returns the number of points stored on this command. ```lua theme={null} local count = #command ``` # PathData Source: https://rive.app/docs/scripting/api-reference/path/path-data PathData is an indexed collection of [PathCommand](/docs/scripting/api-reference/path/path-command) objects. Both Path and PathData behave like arrays of commands and support iteration via ipairs. ## Methods ### `__len`

```lua theme={null} __len() -> number ```

Each entry is a [PathCommand](/docs/scripting/api-reference/path/path-command) describing one segment or action in the path. ```lua theme={null} for i, command in ipairs(pathData) do print(i, command.type) end ``` Returns the number of commands in the path. ```lua theme={null} local count = #pathData print(count) ``` ### `contours`

```lua theme={null} contours() -> ContourMeasure? ```

Returns a [ContourMeasure](/docs/scripting/api-reference/path/contour-measure) for the first contour in the path. A contour is a sequence of path segments starting at a `moveTo` and ending before the next `moveTo` (or end of path). Use the `next` property on the returned [ContourMeasure](/docs/scripting/api-reference/path/contour-measure) to iterate through subsequent contours. Returns `nil` if the path has no contours. ```lua theme={null} local contour = pathData:contours() while contour do print(contour.length) contour = contour.next end ``` ### `measure`

```lua theme={null} measure() -> PathMeasure ```

Returns a [PathMeasure](/docs/scripting/api-reference/path/path-measure) that measures the entire path across all contours. This provides the total length and allows operations on the path as a whole. ```lua theme={null} local measure = pathData:measure() print(measure.length) ``` # PathMeasure Source: https://rive.app/docs/scripting/api-reference/path/path-measure ## Fields ### `length` The total length of the path across all contours. ```lua highlight={11} theme={null} local function buildPath(path: Path) path:reset() path:moveTo(Vector.xy(-150, 0)) path:cubicTo(Vector.xy(-80, -120), Vector.xy(80, 120), Vector.xy(150, 0)) path:close() end function init(self: PathMeasureDemo, _context: Context): boolean buildPath(self.path) local measure = self.path:measure() print('length:', measure.length) return true end ``` ### `isClosed` Returns true only if the path has exactly one contour and that contour is closed. Paths with multiple contours always return false, even if all contours are closed. ```lua highlight={11} theme={null} local function buildPath(path: Path) path:reset() path:moveTo(Vector.xy(-150, 0)) path:cubicTo(Vector.xy(-80, -120), Vector.xy(80, 120), Vector.xy(150, 0)) end function init(self: PathMeasureDemo, _context: Context): boolean buildPath(self.path) local measure = self.path:measure() print('isClosed:', measure.isClosed) return true end ``` ## Methods ### `positionAndTangent`

```lua theme={null} positionAndTangent(distance: number) -> (Vector, Vector) ```

Returns the position and tangent vector at the given distance along the path. The distance is clamped to the valid range \[0, length]. Returns two [Vector](/docs/scripting/api-reference/vector/vector) values: the position and the normalized tangent vector. ```lua highlight={10} theme={null} function draw(self: PathMeasureDemo, renderer: Renderer) -- Draw the base path renderer:drawPath(self.path, pathPaint) local measure = self.path:measure() local len = measure.length -- positionAndTangent: place a dot that travels along the path local distance = (self.elapsed * 0.3 % 1.0) * len local pos, _tan = measure:positionAndTangent(distance) self.traveler:reset() drawDot(self.traveler, pos.x, pos.y, 8) renderer:drawPath(self.traveler, travelerPaint) end ``` ### `warp`

```lua theme={null} warp(source: Vector) -> Vector ```

Warps a point onto the path. The x-coordinate of the source point is interpreted as a distance along the path, and the y-coordinate is used as an offset along the tangent direction. Returns the warped position as a [Vector](/docs/scripting/api-reference/vector/vector). ```lua highlight={17} theme={null} function draw(self: PathMeasureDemo, renderer: Renderer) -- Draw the base path renderer:drawPath(self.path, pathPaint) local measure = self.path:measure() local len = measure.length -- warp: map a grid of points onto the path using distance (x) and -- perpendicular offset (y), then draw a dot at each warped position self.warpPath:reset() local cols, rows = 16, 3 local gap = 20 for col = 0, cols do for row = -rows, rows do local srcX = (col / cols) * len local srcY = row * gap local warped = measure:warp(Vector.xy(srcX, srcY)) drawDot(self.warpPath, warped.x, warped.y, 3) end end renderer:drawPath(self.warpPath, warpPaint) end ``` ### `extract`

```lua theme={null} extract(startDistance: number, endDistance: number, destination: Path, startWithMove: boolean?) -> () ```

Extracts a sub-section of the path from startDistance to endDistance and appends it to the destination path. Distances are clamped to the valid range \[0, length]. If startWithMove is true (the default), the extracted segment begins with a moveTo operation. If false, it continues from the previous point in the destination path. ```lua highlight={14,17,18} theme={null} function draw(self: PathMeasureDemo, renderer: Renderer) -- Draw the base path renderer:drawPath(self.path, pathPaint) local measure = self.path:measure() local len = measure.length -- extract: animate a highlight window traveling along the path local windowSize = len * 0.4 local startD = (self.elapsed * 0.3 % 1.0) * len local endD = startD + windowSize self.extractedPath:reset() if endD <= len then measure:extract(startD, endD, self.extractedPath) else -- wrap around the end of the path measure:extract(startD, len, self.extractedPath) measure:extract(0, endD - len, self.extractedPath, false) end renderer:drawPath(self.extractedPath, extractPaint) end ``` # Promise Source: https://rive.app/docs/scripting/api-reference/promise/promise A value that will be available in the future. Use `andThen` to register callbacks, or `await` inside `async` to suspend until the value is ready. Supports cancellation: call `cancel()` to abort pending work and propagate cancellation to chained promises. ## Fields ### `andThen` Register a callback for when the promise fulfills. The handler may return a value that becomes the next promise's result. ## Constructors ### `new`

```lua theme={null} new(executor: (resolve:(value: T) ->(), reject:(error: any) ->(), onCancel:(hook:() ->()) ->()) ->()) -> Promise ```

Create a new promise with an executor function. The executor receives resolve, reject, and onCancel callbacks. ### `resolve`

```lua theme={null} resolve(value: T?) -> Promise ```

Create an already-resolved promise. Resolves with nil if no value given. ### `reject`

```lua theme={null} reject(error: any?) -> Promise ```

Create an already-rejected promise. Error can be any Lua value. Uses a default reason if no argument is provided. ### `all`

```lua theme={null} all(promises: {Promise}) -> Promise<{T}> ```

Wait for all promises to resolve; rejects if any rejects. On rejection, remaining promises are cancelled. ## Methods ### `catch`

```lua theme={null} catch(onRejected: (error: any) -> any) -> any ```

Register a callback for when the promise rejects. Errors can be any Lua value (string, table, number, etc.). ### `finally`

```lua theme={null} finally(onFinally: () ->()) -> Promise ```

```lua theme={null} cancel() -> Promise ```

Cancel this promise. Fires the onCancel hook (if registered), propagates cancellation down to chained promises, and propagates up to the parent if all its consumers are cancelled. No-op if the promise is already settled. ### `onCancel`

```lua theme={null} onCancel(hook: () ->()) -> Promise ```

Register a cancellation hook that fires when cancel() is called. Used to clean up in-flight work (e.g. abort a network request). ### `getStatus`

```lua theme={null} getStatus() -> string ```

Returns the current state: "Pending", "Fulfilled", "Rejected", or "Cancelled". # Renderer Source: https://rive.app/docs/scripting/api-reference/renderer/renderer Provides functions for drawing paths and images, managing clipping, and applying transforms during rendering. ## Methods ### `drawPath`

```lua theme={null} drawPath(path: Path, paint: Paint) -> () ```

Draws the given [Path](/docs/scripting/api-reference/path/path) using the specified [Paint](/docs/scripting/api-reference/paint/paint). For a more detailed explanation and working examples, see [Drawing with Node Scripts](/docs/scripting/protocols/node-scripts#drawing). ```lua theme={null} function draw(self: Rectangle, renderer: Renderer) renderer:drawPath(self.path, self.paint) end ``` ### `drawImage`

```lua theme={null} drawImage(image: Image, sampler: ImageSampler, blendMode: BlendMode, opacity: number) -> () ```

Draws an [Image](/docs/scripting/api-reference/image/image) using the [ImageSampler](/docs/scripting/api-reference/image/image-sampler), [BlendMode](/docs/scripting/api-reference/paint/blend-mode), and opacity. Check out [Scripting demos](https://rive.app/docs/scripting/demos) to see a working example. ```lua highlight={15} theme={null} type DrawImage = { myImage: Image?, sampler: ImageSampler?, } function init(self: DrawImage, context: Context): boolean self.myImage = context:image('myImage') self.sampler = ImageSampler('clamp', 'clamp', 'bilinear') return true end function draw(self: DrawImage, renderer: Renderer) if self.myImage and self.sampler then renderer:drawImage(self.myImage, self.sampler, 'srcOver', 1) end end return function(): Node return { myImage = nil, sampler = nil, init = init, draw = draw, } end ``` ### `drawImageMesh`

```lua theme={null} drawImageMesh(image: Image, sampler: ImageSampler, vertices: VertexBuffer, uvs: VertexBuffer, triangles: TriangleBuffer, blendMode: BlendMode, opacity: number) -> () ```

Draws an image using mesh data defined by vertices, texture coordinates, and triangle indices. Check out [Scripting demos](https://rive.app/docs/scripting/demos) to see a working example. ```lua theme={null} function draw(self: DrawImageMesh, renderer: Renderer) if self.myImage and self.sampler and self.vertices and self.uvs and self.triangles then renderer:drawImageMesh( self.myImage, self.sampler, self.vertices, self.uvs, self.triangles, 'srcOver', 1 ) end end ``` ### `clipPath`

```lua theme={null} clipPath(path: Path) -> () ```

Restricts subsequent drawing to the area defined by the given [Path](/docs/scripting/api-reference/path/path). Clipping remains in effect until the next restore call. Check out [Scripting demos](https://rive.app/docs/scripting/demos) to see a working example. ```lua highlight={10} theme={null} function draw(self: DrawImageClipped, renderer: Renderer) if self.myImage and self.sampler then local w: number = self.myImage.width local h: number = self.myImage.height local rx: number = (w / 2) * self.clipRadiusX local ry: number = (h / 2) * self.clipRadiusY buildOvalPath(self.clipPath, w / 2, h / 2, rx, ry) renderer:save() renderer:clipPath(self.clipPath) renderer:drawImage(self.myImage, self.sampler, 'srcOver', 1) renderer:restore() end end ``` ### `save`

```lua theme={null} save() -> () ```

Saves the current rendering state, including transforms and clipping. ```lua highlight={4} theme={null} function draw(self: MyGame, renderer: Renderer) -- draw each enemy for _, enemy in self.enemies do renderer:save() enemy.artboard:draw(renderer) renderer:restore() end end ``` ### `restore`

```lua theme={null} restore() -> () ```

Restores the most recently saved rendering state. ```lua highlight={6} theme={null} function draw(self: MyGame, renderer: Renderer) -- draw each enemy for _, enemy in self.enemies do renderer:save() enemy.artboard:draw(renderer) renderer:restore() end end ``` ### `transform`

```lua theme={null} transform(transform: Mat2D) -> () ```

Applies a transform to the current rendering state. Transforms are applied cumulatively until restored. ```lua highlight={7} theme={null} function draw(self: TransformedImage, renderer: Renderer) if self.myImage and self.sampler then local m = Mat2D.withScale(2, 3) -- Adjust matrix terms directly for additional skew/stretch control. m.xx = 5 renderer:save() renderer:transform(m) renderer:drawImage(self.myImage, self.sampler, 'srcOver', 1) renderer:restore() end end ``` # Vector Source: https://rive.app/docs/scripting/api-reference/vector/vector Represents a vector with three components. Vectors created with `Vector.xy` have z = 0. All magnitude and interpolation operations (`length`, `dot`, `distance`, `normalized`, `lerp`, ...) use all three components; with z = 0 they behave exactly as 2D math. ## Fields ### `x` The x component of the vector (read-only). ```lua theme={null} local v = Vector.xy(10, -5) local xValue = v.x -- 10 ``` ### `y` The y component of the vector (read-only). ```lua theme={null} local v = Vector.xy(10, -5) local yValue = v.y -- -5 ``` ### `z` The z component of the vector (read-only). Zero for vectors created with `Vector.xy`; populated by 3D APIs that return a [Vector](/docs/scripting/api-reference/vector/vector). ```lua theme={null} local v = m:transformPoint(1, 2, 3) local zValue = v.z ``` ## Constructors ### `xy`

```lua theme={null} xy(x: number, y: number) -> Vector ```

Creates a vector with the specified x and y components. ```lua theme={null} local v = Vector.xy(5, -2) -- 5 -2 ``` ### `xyz`

```lua theme={null} xyz(x: number, y: number, z: number) -> Vector ```

Creates a vector with the specified x, y and z components. ```lua theme={null} local v = Vector.xyz(1, 2, 3) ``` ### `origin`

```lua theme={null} origin() -> Vector ```

Returns the zero vector (0, 0). ```lua theme={null} local origin = Vector.origin() -- 0 0 ``` ### `cross3`

```lua theme={null} cross3(a: Vector, b: Vector) -> Vector ```

Returns the 3D cross product of two vectors. ```lua theme={null} local z = Vector.cross3(Vector.xyz(1,0,0), Vector.xyz(0,1,0)) -- 0 0 1 ``` ### `scaleAndAdd`

```lua theme={null} scaleAndAdd(a: Vector, b: Vector, scale: number) -> Vector ```

Returns a + b \* scale. ```lua theme={null} local r = Vector.scaleAndAdd(Vector.xy(1,2), Vector.xy(3,4), 2) -- 7 10 ``` ### `scaleAndSub`

```lua theme={null} scaleAndSub(a: Vector, b: Vector, scale: number) -> Vector ```

Returns a - b \* scale. ```lua theme={null} local r = Vector.scaleAndSub(Vector.xy(7,10), Vector.xy(3,4), 2) -- 1 2 ``` ### `lerp`

```lua theme={null} lerp(from: Vector, to: Vector, t: number) -> Vector ```

Returns the linear interpolation between the to and from vector, using t where 0 returns the vector and 1 returns the other. ```lua theme={null} local p = Vector.lerp(Vector.xy(0,0), Vector.xy(8,0), 0.25) -- 2 0 ``` ### `normalized`

```lua theme={null} normalized(v: Vector) -> Vector ```

Returns a normalized copy of the given vector. ```lua theme={null} local n = Vector.normalized(Vector.xy(10, 0)) -- Vector.xy(1, 0) ``` ## Static Functions ### `distance`

```lua theme={null} distance(a: Vector, b: Vector) -> number ```

Returns the distance between the two vectors. ```lua theme={null} local d = Vector.distance(Vector.xy(3, 4), Vector.xy(0, 0)) -- 5 ``` ### `distanceSquared`

```lua theme={null} distanceSquared(a: Vector, b: Vector) -> number ```

Returns the squared distance between the two vectors. ```lua theme={null} local d2 = Vector.distanceSquared(Vector.xy(3,4), Vector.xy(0,0)) -- 25 ``` ### `dot`

```lua theme={null} dot(a: Vector, b: Vector) -> number ```

Returns the dot product of the two vectors. ```lua theme={null} local dp = Vector.dot(Vector.xy(1,2), Vector.xy(3,4)) -- 11 (1*3 + 2*4) ``` ### `cross`

```lua theme={null} cross(a: Vector, b: Vector) -> number ```

Returns the cross product of two vectors (z-component of the 3D cross product). ```lua theme={null} local c = Vector.cross(Vector.xy(1, 0), Vector.xy(0, 1)) -- 1 ``` ### `length`

```lua theme={null} length(v: Vector) -> number ```

Returns the length of the given vector. ```lua theme={null} local len = Vector.length(Vector.xy(3, 4)) -- 5 ``` ### `lengthSquared`

```lua theme={null} lengthSquared(v: Vector) -> number ```

Returns the squared length of the given vector. ```lua theme={null} local len2 = Vector.lengthSquared(Vector.xy(3, 4)) -- 25 ``` ## Methods ### `length`

```lua theme={null} length() -> number ```

**Deprecated** - Use `Vector.length` instead. Returns the length of the vector. ### `lengthSquared`

```lua theme={null} lengthSquared() -> number ```

**Deprecated** - Use `Vector.lengthSquared` instead. Returns the squared length of the vector. ```lua theme={null} local v = Vector.xy(3, 4) local len2 = v:lengthSquared() -- 25 ``` ### `normalized`

```lua theme={null} normalized() -> Vector ```

**Deprecated** - Use `Vector.normalized` instead. Returns a normalized copy of the vector. If the length is zero, the result is the zero vector. ```lua theme={null} local v = Vector.xy(10, 0) local n = v:normalized() -- 1 0 ``` ### `__eq`

```lua theme={null} __eq(rhs: Vector) -> boolean ```

Returns true if the two vectors have equal components. ```lua theme={null} local a = Vector.xy(1, 2) local b = Vector.xy(1, 2) local c = Vector.xy(2, 1) print(a == b) -- true print(a == c) -- false ``` ### `__unm`

```lua theme={null} __unm() -> Vector ```

Returns the negated vector. ```lua theme={null} local v = Vector.xy(2, -3) local neg = -v -- -2 3 ``` ### `__add`

```lua theme={null} __add(rhs: Vector) -> Vector ```

Returns the sum of two vectors. ```lua theme={null} local a = Vector.xy(2, 3) local b = Vector.xy(-1, 5) local c = a + b -- 1 8 ``` ### `__sub`

```lua theme={null} __sub(rhs: Vector) -> Vector ```

Returns the difference between two vectors. ```lua theme={null} local a = Vector.xy(2, 3) local b = Vector.xy(-1, 5) local c = a - b -- 3 -2 ``` ### `__mul`

```lua theme={null} __mul(rhs: number) -> Vector ```

Returns the vector scaled by the given number. ```lua theme={null} local v = Vector.xy(3, -2) local doubled = v * 2 -- 6 -4 ``` ### `__div`

```lua theme={null} __div(rhs: number) -> Vector ```

Returns the vector divided by the given number. ```lua theme={null} local v = Vector.xy(6, -4) local half = v / 2 -- 3 -2 ``` ### `distance`

```lua theme={null} distance(other: Vector) -> number ```

**Deprecated** - Use `Vector.distance` instead. Returns the distance to the other vector. ```lua theme={null} local a = Vector.xy(0, 0) local b = Vector.xy(3, 4) print(a:distance(b)) -- 5 ``` ### `distanceSquared`

```lua theme={null} distanceSquared(other: Vector) -> number ```

**Deprecated** - Use `Vector.distanceSquared` instead. Returns the squared distance to the other vector. ```lua theme={null} local a = Vector.xy(0, 0) local b = Vector.xy(3, 4) print(a:distanceSquared(b)) -- 25 ``` ### `dot`

```lua theme={null} dot(other: Vector) -> number ```

**Deprecated** - Use `Vector.dot` instead. Returns the dot product of the vector and the other vector. ```lua theme={null} local a = Vector.xy(1, 2) local b = Vector.xy(3, 4) print(a:dot(b)) -- 11 (1*3 + 2*4) ``` ### `lerp`

```lua theme={null} lerp(other: Vector, t: number) -> Vector ```

**Deprecated** - Use `Vector.lerp` instead. Returns the linear interpolation between the vector and the other vector, using t where 0 returns the vector and 1 returns the other. ```lua theme={null} local a = Vector.xy(0, 0) local b = Vector.xy(10, 0) local p = a:lerp(b, 0.5) -- 5 0 ``` ### `writeToBuffer`

```lua theme={null} writeToBuffer(buf: buffer, byteOffset: number) -> () ```

Writes x, y, z as 12 bytes (three float32) into the buffer at `byteOffset`. ```lua theme={null} local buf = buffer.create(12) Vector.xyz(1, 2, 3):writeToBuffer(buf, 0) ``` ### `writeVec4`

```lua theme={null} writeVec4(buf: buffer, byteOffset: number, w: number) -> () ```

Writes x, y, z, w as 16 bytes (four float32) into the buffer at `byteOffset`, matching a vec4 uniform-buffer slot. ```lua theme={null} local ubo = buffer.create(16) lightDir:writeVec4(ubo, 0, 0) -- w = 0 for a direction ``` # Configuration Source: https://rive.app/docs/scripting/configuration Customize the Rive code editor with themes, typography, and execution settings. You can customize the appearance and behavior of the Rive code editor by editing its configuration file. Your settings will be reflected in all code editor views for your user account. ## Opening the Configuration Press **⌘ + ,** on macOS or **Ctrl + ,** on Windows to open the editor configuration. ## Editing the Config The configuration file returns a Lua table. Start with the default configuration and override any settings you want to change. ### Example Configuration ```lua theme={null} -- Import the default configuration local config = require('config/default') config.theme = require('theme/shades-of-purple-super-dark') config.code.fontSize = 14 config.code.lineHeight = 20 config.code.selectionCornerRadius = 5 config.code.executionTimeoutMs = 2000 return config ``` ## Available Options | Option | Description | | ----------------------------------- | --------------------------------------------------- | | `config.theme` | The editor theme. | | `config.code.fontSize` | Font size used in the code editor. | | `config.code.lineHeight` | Height of each line of code. | | `config.code.selectionCornerRadius` | Corner radius of the selection highlight. | | `config.code.executionTimeoutMs` | Maximum time a script can run before being stopped. | To browse available themes, type: `config.theme = require('theme/')` The editor will show the full list through autocomplete. autocomplete editor themes

# Creating Scripts Source: https://rive.app/docs/scripting/creating-scripts There are two ways to create a new script, from the Assets Panel and with the Scripting tool. ### Creating a Script from the Assets Panel 1. In the Assets Panel, click the `+` button. 2. Choose **Script** and select the [Protocol](/docs/scripting/protocols/overview) (type of script) you'd like to create. Create Script from Assets Panel

### Creating a Script with the Scripts Tool 1. Select the dropdown icon next to the Script button in the Toolbar 2. Select the [Protocol](/docs/scripting/protocols/overview) (type of script) you'd like to create. Create Script from Assets Panel

New scripts are saved as Assets and can be found in the Assets Panel. Use **PascalCase** for script names and update the script’s type name accordingly. Example: If the script is named `MyConverter`, the main type should also be named `MyConverter`. ## Adding Scripts to Your Scene To run [Node](/docs/scripting/protocols/node-scripts) and [Layout](/docs/scripting/protocols/layout-scripts) scripts, they need to be added to the scene. 1. Right-click the artboard you'd like to add your script to and select your script from the menu 2. Position the script object, keeping in mind that the script's position will determine where it's rendered 3. Select the group to set inputs (See [Script Inputs](/docs/scripting/script-inputs)) Create Script from Assets Panel

**Troubleshooting: If you don't see your script in the list:** 1. Make sure your script is in the Assets Panel. 2. Check the [Problems Panel](/docs/scripting/debugging/debug-panel#problems) for issues. 3. Make sure your script returns a function that returns a table with at least an `init` and `draw` function. # Data Binding Source: https://rive.app/docs/scripting/data-binding Scripting allows you to read, modify, and subscribe to changes in View Model properties, as well as create new View Model instances at runtime. For a conceptual overview of View Models and how they drive your graphic, see [View Models & Data Binding](/docs/editor/data-binding/overview). ## Accessing View Models There are two ways that a script can gain access to a View Model and its properties: * Accessing View Models through [Context](#context) * [View Models as an inputs](#view-models-as-inputs) If you only need to read, not set view model properties, you can data bind view model property values to script inputs. For more information see [Data Binding Inputs](/docs/scripting/script-inputs#data-binding-inputs). ### Context The `init` lifecycle function includes a `context` parameter that gives you access to your view models. This allows you to read values (strings, enums, lists, etc.), set values, fire triggers, listen for triggers, and subscribe to value changes. In addition to view models, [Context](/docs/scripting/api-reference/interfaces/context) gives you access to named assets and update scheduling. ```lua theme={null} type GetContexts = {} function init(self: GetContexts, context: Context): boolean -- Get the view model from the node's immediate context. local mainVmi = context:viewModel() --- Get the root view model local rootVmi = context:rootViewModel() --- Get a global view model local globalVmi = context:globalViewModel('MyGlobalVM') -- Get the view model from the parent node. local dc = context:dataContext() if dc then local parentDC = dc:parent() if parentDC then local parentVmi = parentDC:viewModel() end end return true end return function(): Node return { init = init, } end ``` ### View Models as Inputs You can create an [Input](/docs/scripting/script-inputs) that accepts a view model instance, which gives the script access to its properties. This is in addition to your main view model. In this example, we call it `MenuVM` and give it a `string` property called `title`. A main view model and a view model called MenuVM with a string property called title.

A main view model and a view model called MenuVM with a string property called title.

To be able to reference the instance of `MenuVM` in your script, we need to create a `myMenu` property of type `MenuVM` in the main view model. Create a new view model property by clicking + on the main view model, selecting View Models, then MainVM

Create a new view model property by clicking + on the main view model, selecting View Models, then MainVM

In your script add a new input of type `Data.MenuVM`. ```lua {3,8,17} theme={null} -- Define the script's data and inputs. type ScriptInputs = { myMenu: Input, } -- Called once when the script initializes. function init(self: ScriptInputs, context: Context): boolean print(self.myMenu.title.value) return true end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { init = init, myMenu = late(), } end ``` Select the script in your hierarchy and in the Property Group panel of the Inspector, set the `myMenu` input to `menu`. ## Reading and Setting Properties The following methods allow you to reference view model properties: * [getNumber](/docs/scripting/api-reference/interfaces/view-model#getnumber) * [getTrigger](/docs/scripting/api-reference/interfaces/view-model#gettrigger) * [getString](/docs/scripting/api-reference/interfaces/view-model#getstring) * [getBoolean](/docs/scripting/api-reference/interfaces/view-model#getboolean) * [getColor](/docs/scripting/api-reference/interfaces/view-model#getcolor) * [getList](/docs/scripting/api-reference/interfaces/view-model#getlist) * [getViewModel](/docs/scripting/api-reference/interfaces/view-model#getviewmodel) * [getEnum](/docs/scripting/api-reference/interfaces/view-model#getenum) * [getImage](/docs/scripting/api-reference/interfaces/view-model#getimage) * [getFont](/docs/scripting/api-reference/interfaces/view-model#getfont) * [getBlob](/docs/scripting/api-reference/interfaces/view-model#getblob) ```lua {5,8,11,15,18} theme={null} local vmi = context:viewModel() if vmi then -- Get a reference to the score property from the view model local score = vmi:getNumber('score') if score then -- Read the score print(score.value) -- Set the score score.value = 100 end -- Get a reference to the myTrigger property from the view model local myTrigger = vmi:getTrigger('myTrigger') if myTrigger then -- Fire the trigger mytrigger:fire() end end ``` ## Listening for Property Changes ### Add a Listener Use `addListener` to listen for triggers or changes to view model properties. ```lua {19,22,23,24} theme={null} -- Define the script's data and inputs. type ScriptInputs = { menu: Input, } function onTitleChange() print('changed') end function onTitleChangeWithParam(self: ScriptInputs) print('changed', self.menu.title.value) end -- Called once when the script initializes. function init(self: ScriptInputs, context: Context): boolean local title = self.menu.title -- When title changes, call onTitleChange title:addListener(onTitleChange) -- When title changes, call onTitleChangeWithParam with an argument of self title:addListener(self, onTitleChangeWithParam) return true end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { init = init, score = 0, menu = late(), newArtboard = late(), } end ``` ### Remove a Listener Always remove listeners when they are no longer needed to avoid memory leaks. ```lua highlight={14} theme={null} -- Define the script's data and inputs. type ScriptInputs = { menu: Input, } -- Anchor-form listener callback: receives the same object passed as the -- anchor to addListener (here, the `title` Property itself). function onTitleChangeWithParam(title: Property) print('title changed:', title.value) -- Unsubscribe using the matching anchor-form overload (self, anchor, callback). -- The simpler (self, callback) overload requires a zero-argument callback, -- which is why using it here caused a type error against this 1-argument function. title:removeListener(title, onTitleChangeWithParam) end -- Called once when the script initializes. function init(self: ScriptInputs, context: Context): boolean local title = self.menu.title -- When title changes, call onTitleChangeWithParam with the anchor (title) as its argument. title:addListener(title, onTitleChangeWithParam) return true end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { init = init, menu = late(), } end ``` ## Creating a View Model Instance ```lua highlight={10} theme={null} -- Define the script's data and inputs. type ScriptInputs = { menu: Input, } -- Called once when the script initializes. function init(self: ScriptInputs, context: Context): boolean -- Create a brand new MenuVM ViewModel instance programmatically -- (instead of relying on the data-bound `menu` input from the editor). local newMenuInstance = Data.MenuVM.new() local newTitle = newMenuInstance:getString('title') if newTitle then newTitle.value = 'Created at runtime' end -- Swap self.menu to use the instance we just created programmatically. self.menu = newMenuInstance local title = self.menu.title print('menu title after programmatic creation:', title.value) return true end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { init = init, menu = late(), } end ``` # Debug Panel Source: https://rive.app/docs/scripting/debugging/debug-panel The Debug Panel lets you inspect script output and detect issues in your code. Viewport

## Toolbar Switch between [Console](#console) and [Problems](#problems) using the tabs to the left of the panel. Use the icons at the right end of the panel to open and close the panel and toggle fullscreen mode. Additional options to copy and clear the console show up when the Console tab is active. ## Console The Console shows all log output and runtime errors from your scripts during playback. You can use the standard [Luau print()](https://create.roblox.com/docs/reference/engine/globals/LuaGlobals#print) function to log information, variable values, and messages. ```lua theme={null} print("Rive is so cool!") print("Elapsed time:", seconds) ``` Debug panel toolbar

## Problems The Problems tab lists problems detected *before* the script runs such as type mismatches, syntax errors, or missing data bindings. The tab badge shows the number of issues found across your scripts. Clicking a problem will jump directly to the affected line of code. You can also hover any underlined code in the editor to see an explanation or suggested fix. Problems panel

# Unit Testing Source: https://rive.app/docs/scripting/debugging/unit-testing Write and run unit tests for your Util Scripts using Test scripts. Test scripts let you write unit tests for your [Util Scripts](/docs/scripting/protocols/util-scripts) and run them directly in the Rive editor. Use them to verify math helpers, string utilities, or any other pure logic your scripts depend on. Beyond validating your code, tests also serve as precise instructions for the [AI Agent](/docs/editor/ai-agent), helping it produce code that behaves exactly as you intend. ## Creating a Test Script [Create a new script](/docs/scripting/creating-scripts) and select **Test** as the type. ### Anatomy of a Test Script A Test script exposes a single `setup(test: Tester)` function. The `Tester` object gives you helpers to define and group tests: * `test.case(name, fn)` – define a single test case. * `test.group(name, fn)` – group related tests. Groups can be nested. * `expect(value)` – create an expectation object to assert on a value. Inside a case, the `expect` function is passed as an argument to your test callback. ### Example ```lua theme={null} -- Load the Util that you want to create tests for local MyUtil = require('MyUtil') function setup(test: Tester) local case = test.case local group = test.group -- Create a single case with multiple tests case('Addition', function(expect) local result = MyUtil.add(2, 3) expect(result).is(5) expect(result).greaterThanOrEqual(5) end) -- Organize your tests with groups group('Math', function() case('Subtraction', function(expect) local result = MyUtil.subtract(2, 3) expect(result).is(-1) end) case('Multiplication', function(expect) local result = MyUtil.multiply(2, 3) expect(result).greaterThanOrEqual(6) end) group('Trigonometry', function() case('Degrees to Radians', function(expect) local result = MyUtil.deg2rad(180) expect(result).is(math.pi) end) end) end) end ``` Tip: Use descriptive names for your groups and cases. They show up in the test results panel and make it easier to see what failed. ### Matchers (expectations) The `expect` helper returns an object with matcher methods you can use in your tests, for example: ```lua theme={null} expect(value).is(expected) expect(value).greaterThan(number) expect(value).greaterThanOrEqual(number) expect(value).lessThan(number) expect(value).lessThanOrEqual(number) ``` For a complete list of matchers and test utilities, see Test API Reference (TODO: link). ### Inverting matchers with never You can invert any matcher by chaining .never before it. This means: the test passes only if the matcher would normally fail. ```lua theme={null} case('never examples', function(expect) -- This passes because 2 + 2 is NOT 3 expect(2 + 2).never.is(3) -- This passes because 4 is NOT >= 6 expect(4).never.greaterThanOrEqual(6) end) ``` ## Running Tests 1. In the Assets panel, right-click your Test script. 2. Select Run Tests. Test results are shown: * Passing and failing cases are listed under the script in the Assets Panel * Passing and failing cases are highlighted in the script editor Problems panel

# Scripting Demos Source: https://rive.app/docs/scripting/demos # Getting Started Source: https://rive.app/docs/scripting/getting-started Code, animation, and interaction all in one Editor. Scripting lets you iterate on code, design, and animation in one collaborative editor. ## Quick Start This video introduces the basics of writing and using scripts in Rive. You’ll learn how to create different types of scripts and how they connect to data bindings and artboards, and how you can create scripts with the [AI Agent](/docs/editor/ai-agent). ## Fundamentals * [Why Luau](https://rive.app/blog/why-scripting-runs-on-luau?utm_source=docs\&utm_medium=content) - Why Scripting runs on Luau * [Creating Scripts](/docs/scripting/creating-scripts) - Creating a new script * [Protocols](/docs/scripting/protocols) - The type of scripts you can create * [Inputs](/docs/scripting/script-inputs) - Connecting scripts to inputs and data * [Debugging](/docs/scripting/debugging/debug-panel) - Debugging your scripts * [AI Agent](/docs/editor/ai-agent) - Using AI to create and modify scripts # Keyboard Shortcuts Source: https://rive.app/docs/scripting/keyboard-shortcuts A comprehensive reference for all keyboard shortcuts in the Rive script editor. ## Basic Editing | Command | macOS | Windows/Linux | | --------------- | ------------------------------------------ | ------------------------------------------------- | | **Undo** | ⌘ + Z | Ctrl + Z | | **Redo** | ⌘ + ⇧ + Z | Ctrl + Shift + Z | | **Copy** | ⌘ + C | Ctrl + C | | **Cut** | ⌘ + X | Ctrl + X | | **Paste** | ⌘ + V | Ctrl + V | | **Save** | ⌘ + S | Ctrl + S | | **Select All** | ⌘ + A | Ctrl + A | | **Indent** | Tab | Tab | | **Outdent** | ⇧ + Tab | Shift + Tab | | **Format File** | F4 | F4 | ## Application | Command | macOS | Windows/Linux | | ----------------------------- | --------- | ------------- | | Open Settings / Configuration | `⌘` + `,` | `Ctrl` + `,` | ## Cursor Movement | Command | macOS | Windows/Linux | | ------------------------------ | ------------------------------------------------------- | ------------------------------------------- | | **Move by Character** | ←/→ | ←/→ | | **Move by Line** | ↑/↓ | ↑/↓ | | **Move by Word** | ⌥ + ←/→ | Alt + ←/→ | | **Move by Subword** | ⌃ + ⌥ + ←/→ | — | | **Move to Line Start/End** | ⌘ + ←/→ | Ctrl + ←/→ | | **Move to Document Start/End** | ⌘ + ↑/↓ | Ctrl + ↑/↓ | ## Selection All cursor movement commands can be combined with ⇧ (Shift) to extend the selection: | Command | macOS | Windows/Linux | | -------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------- | | **Select by Character** | ⇧ + ←/→ | Shift + ←/→ | | **Select by Line** | ⇧ + ↑/↓ | Shift + ↑/↓ | | **Select by Word** | ⇧ + ⌥ + ←/→ | Shift + Alt + ←/→ | | **Select to Line Start/End** | ⇧ + ⌘ + ←/→ | Shift + Ctrl + ←/→ | | **Select to Document Start/End** | ⇧ + ⌘ + ↑/↓ | Shift + Ctrl + ↑/↓ | ## Line Operations | Command | macOS | Windows/Linux | | ----------------------- | ------------------------------------------ | ----------------------------------------------------- | | **Toggle Comment** | ⌘ + / | Ctrl + / | | **Insert Line Below** | ⌘ + ↩ | Ctrl + Enter | | **Insert Line Above** | ⌘ + ⇧ + ↩ | Ctrl + Shift + Enter | | **Move Line(s) Up** | ⌥ + ↑ | Alt + ↑ | | **Move Line(s) Down** | ⌥ + ↓ | Alt + ↓ | | **Duplicate Line Up** | ⇧ + ⌥ + ↑ | Shift + Alt + ↑ | | **Duplicate Line Down** | ⇧ + ⌥ + ↓ | Shift + Alt + ↓ | ## Multi-Cursor Editing | Command | macOS | Windows/Linux | | ----------------------------- | --------------------------- | ------------------------------ | | **Add Cursor** | ⌥ + Click | Alt + Click | | **Select Next Occurrence** | ⌘ + D | Ctrl + D | | **Collapse to Single Cursor** | Esc | Esc | ## Search and Replace | Command | macOS | Windows/Linux | | ----------------- | ------------------------------------------- | -------------------------------------------------- | | **Find** | ⌘ + F | Ctrl + F | | **Find in Files** | ⌘ + ⇧ + F | Ctrl + Shift + F | | **Find Next** | ⌘ + G or ↩ | Ctrl + G or Enter | | **Find Previous** | ⌘ + ⇧ + G | Ctrl + Shift + G | | **Close Search** | Esc | Esc | The search panel includes toggle buttons for: * **Match Case**: Toggle case-sensitive search * **Whole Word**: Toggle whole word matching * **Regex**: Toggle regular expression mode ## Code Navigation | Command | macOS | Windows/Linux | | -------------------- | ------------------------------------------ | ------------------------------------------------- | | **Go to Definition** | ⌘ + Click | Ctrl + Click | | **File Palette** | ⌘ + P | Ctrl + P | | **Command Palette** | ⌘ + ⇧ + P | Ctrl + Shift + P | | **Global Search** | ⌘ + K | Ctrl + K | ## File and Tab Management | Command | macOS | Windows/Linux | | ------------------------ | -------------------------------------------- | --------------------------------------------------- | | **Close Tab** | ⌘ + W | Ctrl + W | | **Previous Tab** | ⌘ + ⇧ + \[ | Ctrl + Shift + \[ | | **Next Tab** | ⌘ + ⇧ + ] | Ctrl + Shift + ] | | **Tab Palette Forward** | ⌃ + Tab | Ctrl + Tab | | **Tab Palette Backward** | ⌃ + ⇧ + Tab | Ctrl + Shift + Tab | ## Autocomplete | Command | macOS | Windows/Linux | | ----------------------- | ------------------------------ | ---------------------------------- | | **Previous Suggestion** | ↑ | ↑ | | **Next Suggestion** | ↓ | ↓ | | **Accept Suggestion** | ↩ or Tab | Enter or Tab | | **Dismiss** | Esc | Esc | ## Mouse Actions | Action | Description | | ------------------------ | ----------------------------------------------- | | Click | Place cursor at click position | | Double-click | Select the word at click position | | Click in gutter | Select entire line | | ⇧ + Click | Extend selection to click position | | ⌥ + Click | Add additional cursor at click position | | ⌘ + Hover | Show definition preview for symbol under cursor | | ⌘ + Click | Go to definition of symbol under cursor | | Click and drag | Select text by dragging | | Click and drag in gutter | Select multiple lines | ## Auto-Closing Pairs The editor automatically inserts closing characters for: | Opening | Closing | Notes | | ------- | ------- | ---------------------------------- | | `{` | `}` | Curly braces | | `[` | `]` | Square brackets | | `(` | `)` | Parentheses | | `"` | `"` | Double quotes (not inside strings) | | `'` | `'` | Single quotes (not inside strings) | | `` ` `` | `` ` `` | Backticks (not inside strings) | ## Surrounding Selection When text is selected, typing an opening character wraps the selection: | Type | Selection becomes | | ------- | ----------------- | | `{` | `{selection}` | | `[` | `[selection]` | | `(` | `(selection)` | | `"` | `"selection"` | | `'` | `'selection'` | | `` ` `` | `` `selection` `` | | `<` | `` | ## Auto-Completion for Luau Blocks When pressing ↩ (Enter) after certain keywords, the editor auto-completes the block structure: | After typing... | Auto-inserts | | --------------- | ------------------------- | | `function` | `end` on new line | | `do` | `end` on new line | | `then` | `end` on new line | | `else` | `end` on new line | | `repeat` | `until false` on new line | ## Smart Indentation * Pressing ↩ (Enter) automatically maintains the current indentation level * After opening keywords (`function`, `do`, `then`, `else`, `repeat`, `{`), the next line is indented * ⌫ (Backspace) in the indent region removes a full tab (2 spaces) at a time * ⌘ + ← (Home) toggles between column 0 and the first non-whitespace character * Indentation uses 2 spaces (soft tabs) * Line comments use `--` (Luau style) ## Diff Mode When viewing AI-generated changes: | Action | Description | | ---------------- | --------------------------------------- | | Hover over chunk | Shows accept/reject buttons | | Accept button | Accept the changes in this chunk | | Reject button | Reject the changes and restore original | | Accept All | Accept all pending changes | | Reject All | Reject all pending changes | # Pointer Events Source: https://rive.app/docs/scripting/pointer-events You can listen for pointer events inside any script that implements `pointerDown`, `pointerMove`, `pointerUp`, or `pointerExit`. These functions can be defined in [Node Scripts](/docs/scripting/protocols/node-scripts) and [Layout Scripts](/docs/scripting/protocols/layout-scripts). ```lua theme={null} -- Pointer event callbacks have parameters of `self` and a `PointerEvent`. function handlePointerDown(self: MyNode, event: PointerEvent) -- Pointer location in local coordinates relative to the script. print(event.position.x, event.position.y) -- the pointer identifier (useful for multi-touch) print(event.id) -- Marks the event as handled and prevents propagation. event:hit() -- event:hit(true) -- handled, but allowed to pass through translucent elements end -- Register your pointer handlers by assigning functions to pointerDown, -- pointerUp, pointerMove, or pointerExit in the script’s returned table. return function(): Node return { init = init, draw = draw, advance = advance, pointerDown = myPointerDownFunction, } end ``` ## Multi-touch Using `event.id`, you can track multiple active pointers. ```lua theme={null} type ActiveId = { position: Vec2D, } export type TrackPointers = { -- Keep track of the position for each of the pointers activePointers: { ActiveId }, } function onPointerDown(self: TrackPointers, event: PointerEvent) -- Save an item in the table for each pointer down self.activePointers[event.id] = { position = event.position, } print('New pointer down: ' .. event.id) print('Position: ' .. event.position.x .. event.position.y) event:hit() end function onPointerMove(self: TrackPointers, event: PointerEvent) if self.activePointers[event.id] then self.activePointers[event.id].position = event.position -- Print all currently active pointer IDs print('Active pointer IDs:') for id, pointer in self.activePointers do print(' id: ', id) print(' x:', pointer.position.x) print(' y:', pointer.position.y) end end event:hit() end function onPointerUp(self: TrackPointers, event: PointerEvent) self.activePointers[event.id] = nil print('Pointer up: ' .. event.id) print('Position: ' .. event.position.x .. event.position.y) event:hit() end return function(): Node return { init = init, advance = advance, draw = draw, pointerDown = onPointerDown, pointerMove = onPointerMove, pointerUp = onPointerUp, activePointers = {}, } end ``` ## Nested Pointer Events Rive only listens for Pointer Events on the main artboard. If you need to listen for Pointer Events in your [instantiated artboards](/docs/scripting/protocols/node-scripts#instanting-components), you must forward them manually. ```lua theme={null} -- Handle pointer events in the main script function handlePointerDown(self: MyScript, event: PointerEvent) -- self.enemy.pointerDown(self.enemy, event) for _, enemy in self.enemies do -- Convert the incoming pointer position into the enemy's local space. -- This example assumes enemy.position is in the same coordinate system. local localEvent = PointerEvent.new( event.id, Vec2D.xy( -- Normalize the pointer position based on the artboard's position event.position.x - enemy.position.x, event.position.y - enemy.position.y ) ) -- Forward the event into the instantiated artboard self.enemy:pointerDown(localEvent) end end ``` # Converter Scripts Source: https://rive.app/docs/scripting/protocols/converter-scripts Create custom converters using Rive scripting Rive includes several built-in converters like **Convert to String** and **Round**. Scripting lets you create your own custom converters when you need behavior that isn’t covered by the built-ins. For background on converters and data binding, see [Data Converters](/docs/editor/data-binding/converters). ## Examples ## Creating a Converter [Create a new script](/docs/scripting/creating-scripts) and select **Converter** as the type. ## Anatomy of a Converter Script ```lua theme={null} type MyConverter = {} -- Called once when the script initializes. function init(self: MyConverter): boolean return true end -- Converts the property value. function convert(self: MyConverter, input: DataInputs): DataOutput local dv: DataValueNumber = DataValue.number() if input:isNumber() then dv.value = (input :: DataValueNumber).value + 1 else dv.value = 0 -- 0 if input is not a number end return dv end -- For 2-way data binding, converts the target value back to the source function reverseConvert(self: MyConverter, input: DataOutput): DataInputs local dv: DataValueNumber = DataValue.number() if input:isNumber() then -- Example: Subtract 1 from the target number dv.value = (input :: DataValueNumber).value - 1 else dv.value = 0 -- 0 if target is not a number end return dv end -- Return a factory function that builds the converter instance. -- Rive calls this when the script is created, passing back a table -- containing its lifecycle functions and any default values. return function(): Converter return { init = init, convert = convert, reverseConvert = reverseConvert, } end ``` ## Creating a Converter using your Script Create a new converter using your new converter script: 1. In the Data panel, click the `+` button. 2. Choose **Converters → Script → MyConverter**. Create converter with a script

## Adding Inputs See [Script Inputs](/docs/scripting/script-inputs). # Layout Scripts Source: https://rive.app/docs/scripting/protocols/layout-scripts Layout Scripts extend the behavior of [Node Scripts](/docs/scripting/protocols/node-scripts), giving you programmatic control over Layout components. They let you measure, size, and react to changes in your Layout’s geometry. They are ideal for building custom layout behaviors such as masonry grids, carousels, spacing logic, and more. ## Examples ## Adding a Layout Script to a Layout 1. Add a new [Layout](/docs/editor/layouts/layouts-overview) to the scene. 2. [Create a new script](/docs/scripting/creating-scripts) and select **Layout** as the type. 3. Add your script as a child of the Layout. ## Lifecycle Layout Scripts add two additional lifecycle functions: * `measure(self): Vec2D` — optional * `resize(self, size: Vec2D)` — required ### Measure Measure lets your script propose an ideal size for the layout. Rive will use this value unless a Fit rule overrides it. Measure only has an effect on layouts with a Fit type of Hug. ```lua theme={null} function measure(self: MyLayout): Vec2D -- Always declare that this layout would like to be 100×100 return Vec2D.xy(100, 100) end ``` ### Resize Resize runs whenever the Layout receives a new size from its parent or from your measure function. This is where you position or update child nodes, recalculate flow, or react to container changes. ```lua theme={null} -- Called whenever the Layout is resized. function resize(self: MyLayout, size: Vec2D) print("New size:") print("x:", size.x) print("y:", size.y) end ``` # Listener Action Scripts Source: https://rive.app/docs/scripting/protocols/listener-action-scripts Run custom logic when a state machine listener fires [Listeners](/docs/editor/state-machine/listeners) fire when a specific event occurs in a State Machine. Listener Action Scripts let you run custom logic in response to those events. Use Listener Action Scripts when you need to perform side effects—such as updating view model values, responding to pointer input, or triggering external behavior—without changing state. ## Creating a Listener Action Script [Create a new script](/docs/scripting/creating-scripts) and select **Listener Action Script** as the type. ## Anatomy of a Listener Action ```lua theme={null} type MyListenerAction = { context: Context, } -- Called once when the script initializes. function init(self: MyListenerAction, context: Context): boolean -- Context gives you access to your main view model and other data. self.context = context return true end -- Called when the Listener fires. -- Use this to perform side effects (no return value). function perform(self: MyListenerAction, pointerEvent: PointerEvent) end -- Return a factory function that Rive uses to build the Listener Action instance. return function(): ListenerAction return { init = init, perform = perform, context = late(), } end ``` ## Adding your Listener Action Add a custom listener action

## Script Inputs Inputs let you add parameters to a listener action without changing script logic—making the same script reusable across different listeners. For more information on adding inputs to your scripts, see [Script Inputs](/docs/scripting/script-inputs). Inputs can control scripts, but scripts can't change the value of inputs. If you need to control a view model property from your script, access the [Main View model through context](/docs/scripting/data-binding#accessing-the-main-view-model) or [View Model Inputs](/docs/scripting/script-inputs#view-model-inputs). ### Setting an Input To set the value of an input, select the Properties icon next to the listener script. listener action script inputs

### Data Binding an Input Right-click your property and select Data Bind to bind your input to a view model property. listener action script inputs

# Node Scripts Source: https://rive.app/docs/scripting/protocols/node-scripts Node scripts can be used to render shapes, images, text, artboards, and more. ## Creating a Node Script 1. [Create a new script](/docs/scripting/creating-scripts) and select **Node** as the type. 2. [Add it to the scene](/docs/scripting/creating-scripts#adding-scripts-to-your-scene). ## Anatomy of a Node Script ```lua theme={null} -- Define the script's data and inputs. type MyNode = {} -- Called once when the script initializes. function init(self: MyNode): boolean return true end -- Called every frame to advance the simulation. -- 'seconds' is the elapsed time since the previous frame. function advance(self: MyNode, seconds: number): boolean return false end -- Called when any input value changes. function update(self: MyNode) end -- Called every frame (after advance) to render the content. function draw(self: MyNode, renderer: Renderer) end -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { init = init, advance = advance, update = update, draw = draw, } end ``` ## Drawing Node scripts allow you to draw shapes and render them in your scene. ```lua theme={null} function rectangle(self: Rectangle) -- Update the path with current width and height self.path:reset() local halfWidth = self.width / 2 local halfHeight = self.height / 2 -- Draw rectangle centered at origin self.path:moveTo(Vector.xy(-halfWidth, -halfHeight)) self.path:lineTo(Vector.xy(halfWidth, -halfHeight)) self.path:lineTo(Vector.xy(halfWidth, halfHeight)) self.path:lineTo(Vector.xy(-halfWidth, halfHeight)) self.path:close() -- Update paint color self.paint.color = self.color end function draw(self: Rectangle, renderer: Renderer) renderer:drawPath(self.path, self.paint) end ``` See the [API Reference](/docs/scripting/api-reference/path) for a complete list of drawing utilities. ## Common Patterns ### Instantiating Components To be able to instantiate components at runtime, you will need to have a basic understanding of [Data Binding](/docs/editor/data-binding/overview), [Components](/docs/editor/fundamentals/components), and [Script Inputs](/docs/scripting/script-inputs). See the following example showing how to set up your components, view models, and scripts: ```lua theme={null} type Enemy = { artboard: Artboard, position: Vector, } export type MyGame = { -- This is the component that we will dynamically add to our scene -- See: /scripting/script-inputs enemy: Input>, enemies: { Enemy }, } function createEnemy(self: MyGame) -- Create an instance of the artboard local enemy = self.enemy:instance() -- Keep track of all enemies in self.enemies local entry: Enemy = { artboard = enemy, position = Vector.xy(0, 0), } table.insert(self.enemies, entry) end function init(self: MyGame) createEnemy(self) return true end function advance(self: MyGame, seconds: number) -- Advance the artboard of each enemy for _, enemy in self.enemies do enemy.artboard:advance(seconds) end return true end function draw(self: MyGame, renderer: Renderer) -- draw each enemy for _, enemy in self.enemies do renderer:save() enemy.artboard:draw(renderer) renderer:restore() end end return function(): Node return { init = init, advance = advance, draw = draw, enemy = late(), enemies = {}, } end ``` ### Fixed-Step Advance Frame rates can vary between devices and scenes. If your script moves or animates objects based directly on the frame time, faster devices will move them farther each second, while slower ones will appear to lag behind. To keep movement and timing consistent, you can advance your simulation in fixed time steps instead of relying on the variable frame rate. This technique is called a fixed-step update or fixed timestep. ```lua theme={null} --- Fixed Timestep Advance --- Keeps movement consistent across different frame rates --- by advancing the simulation in fixed time steps. export type CarGame = { speed: Input, accumulator: number, fixedStep: Input, direction: number, currentX: number, currentY: number, } -- Prevent the script from running too many catch-up steps -- after a long pause or frame drop. local MAX_STEPS = 5 function advance(self: CarGame, seconds: number): boolean -- Add the time since the last frame to the accumulator. self.accumulator += seconds local dt = self.fixedStep local steps = 0 -- Run the simulation in small, fixed steps. -- If the frame took longer than one step, multiple steps may run this frame. while self.accumulator >= dt and steps < MAX_STEPS do -- Move forward by speed * time. -- Using a fixed dt keeps movement stable even if the frame rate changes. self.currentX += self.speed * math.cos(self.direction) * dt self.currentY += self.speed * math.sin(self.direction) * dt -- Subtract one fixed step from the accumulator -- and repeat until we've caught up to real time. self.accumulator -= dt steps += 1 end return true end -- Create a new instance of the CarGame script with default values. -- The simulation runs 60 fixed steps per second. return function(): Node return { speed = 100, accumulator = 0, direction = 0, fixedStep = 1 / 60, currentX = 0, currentY = 0, } end ``` # Protocols Source: https://rive.app/docs/scripting/protocols/overview Protocols are the structured categories of scripts that tell the Editor what you’re trying to make. Rive currently ships with the following protocols, with more to come: * [Node](/docs/scripting/protocols/node-scripts) * [Layout](/docs/scripting/protocols/layout-scripts) * [Converter](/docs/scripting/protocols/converter-scripts) * [Path Effect](/docs/scripting/protocols/path-effect-scripts) - Create custom path effects. * [Transition Conditions](/docs/scripting/protocols/transition-condition-scripts) - Create custom state machine transition conditions. * [Listener Actions](/docs/scripting/protocols/listener-action-scripts) - React to state machine listeners. * [Test](/docs/scripting/protocols/test-scripts) - Unit test your functions. Each protocol represents a different kind of script the Editor can generate: a converter that shapes data, a custom drawing function, a layout helper, a testing harness, a path effect you can attach to strokes, and so on. Selecting a protocol generates a typed scaffold that defines the surface area you’re allowed to operate on. From there, you work with Rive-native concepts — paths, shapes, view models, artboards, state machines, timelines — but always through the lens of the protocol you picked. It keeps scripts specific and prevents “do anything anywhere” chaos. # Path Effect Scripts Source: https://rive.app/docs/scripting/protocols/path-effect-scripts Create custom path effects using Rive scripting Path Effects are Rive scripts that modify and transform path geometry in real-time. They give you programmatic control over the shape and structure of paths in your animations, enabling effects like warping, distortion, animation, and procedural modifications. ## Creating a Path Effect [Create a new script](/docs/scripting/creating-scripts) and select **Path Effect** as the type. ## Examples ## Anatomy of a Path Effect Script ### Methods * *init (optional)* Called once when the path effect is created. Use this to set up initial state. Returns true if initialization succeeds. * *update (required)* The core method where path transformation happens. Receives the original `PathData` and returns a modified version. This is where you manipulate the path's geometry. * *advance (optional)* Called every frame with elapsed time in seconds. Returns true to continue receiving advance calls. Useful for animated effects that change over time. ## Working with `PathData` `PathData` provides access to a path's drawing commands (`moveTo`, `lineTo`, `cubicTo`, `quadTo`, `close`). You can: * Read existing commands using indexing * Get the command count with `#pathData` * Create new paths and add commands * Use measurement tools like `contours()` and `measure()` for advanced operations ```lua theme={null} type MyPathEffect = { context: Context, } function init(self: MyPathEffect, context: Context): boolean self.context = context return true end function update(self: MyPathEffect, inPath: PathData): PathData local path = Path.new() return path end function advance(self: MyPathEffect, seconds: number): boolean return true end -- Return a factory function that Rive uses to build the Path Effect instance. return function(): PathEffect return { init = init, update = update, advance = advance, context = late(), } end ``` If a Path Effect script changes over time, call `markNeedsUpdate()` on the effect context from `advance()`. This tells Rive to recalculate the effect on the next frame, even when the source path itself has not changed. Without this, the effect may appear to freeze because Rive has no signal that the path output is changing. This is especially important for animated path effects inside nested components, where the source path may remain static while the script continues updating its own internal values. ```lua highlight={11} theme={null} local function init(self: WaveyEffect, context: Context): boolean self.context = context self.time = 0.0 return true end local function advance(self: WaveyEffect, seconds: number): boolean self.time += seconds * math. clamp(self. speed, 0.0, 20.0) if self. context then self.context: markNeedsUpdate() end return true end ``` ## Add the Scripted Path Effect to a Stroke Select or add a stroke to a shape: 1. Open the Options menu. 2. Select the Effects Tab and click the '+' to add an effect. 3. Find your effects under the Script Effects menu option. 4. Any inputs you have defined will apepar and can be edited here. Add Path Effect to a Stroke

## Adding Inputs See [Script Inputs](/docs/scripting/script-inputs). # Test Scripts Source: https://rive.app/docs/scripting/protocols/test-scripts Write tests for your scripts to ensure they are working correctly. See [Unit Testing](/docs/scripting/debugging/unit-testing). # Transition Condition Scripts Source: https://rive.app/docs/scripting/protocols/transition-condition-scripts Create custom state machine transitions using scripts [Conditions](/docs/editor/state-machine/transitions#conditions) are the rules that determine when the State Machine transitions from one state to another. Transition Condition Scripts let you define custom conditions when built-in comparisons aren’t enough—such as transitions that depend on complex logic or multiple view model properties evaluated together. ## Creating a Transition Condition Script [Create a new script](/docs/scripting/creating-scripts) and select **Transition Condition Script** as the type. ## Anatomy of a Transition Condition ```lua theme={null} type MyTransitionCondition = { context: Context, } -- Called once when the script initializes. function init(self: MyTransitionCondition, context: Context): boolean -- Context gives you access to your main view model and other data. self.context = context return true end -- Add your transition logic here. -- `evaluate` is fired every frame while the transition is active. -- Returning false prevents a transition, true allows a transition. function evaluate(self: MyTransitionCondition): boolean return false end -- Return a factory function that Rive uses to build the Transition Condition instance. return function(): TransitionCondition return { init = init, evaluate = evaluate, context = late(), } end ``` `evaluate` runs every frame while the transition is active. It should be fast and side-effect free, and only return whether the transition is allowed. ## Adding your Transition Condition Add a custom transition

## Script Inputs Inputs let you add parameters a transition without changing script logic—making the same condition reusable across different transitions or states. For more information on adding inputs to your scripts, see [Script Inputs](/docs/scripting/script-inputs). Inputs can control scripts, but scripts can't change the value of inputs. If you need to control a view model property from your script, access the [Main View model through context](/docs/scripting/data-binding#accessing-the-main-view-model) or [View Model Inputs](/docs/scripting/script-inputs#view-model-inputs). ### Setting an Input To set the value of an input, select the Properties icon next to the transition. transition script inputs

### Data Binding an Input Right-click your property and select Data Bind to bind your input to a view model property. data binding transition script inputs

# Util Scripts Source: https://rive.app/docs/scripting/protocols/util-scripts Create helper modules to organize shared logic across your scripts. Util scripts let you organize your code into small, focused modules that can be reused across multiple scripts. They’re ideal for math helpers, geometry utilities, color functions, or any logic that should be broken out into its own script. ## Creating a Util Script [Create a new script](/docs/scripting/creating-scripts) and select **Util** as the type. ```lua theme={null} --- Example helper function. local function add(a: number, b: number): MyUtil return a + b, end -- Return the functions you'd like to use in another script return { add = add, } ``` **Usage:** ```lua theme={null} local MyUtil = require("MyUtil") local result = MyUtil.add(2, 3) print(result) -- 5 ``` ## Utils with Custom Types Custom types defined in your Util scripts will automatically be accessible in the parent script. ```lua theme={null} --- Defines the return type for this util. --- The type is automatically available when you require the script. export type AdditionResult = { exampleValue: number, someString: string } --- Example helper function. local function add(a: number, b: number): AdditionResult return { exampleValue = a + b, someString = "4 out of 5 dentists recommend Rive" } end return { add = add, } ``` **Usage:** ```lua theme={null} -- With type annotation local result: AdditionResult = MyUtil.add(2, 3) ``` # Script Inputs Source: https://rive.app/docs/scripting/script-inputs Scripted Inputs are the bridge between your scripts and the Rive editor, allowing you to customize and control script behavior through custom input fields. By defining inputs in your scripts, you expose configurable properties — like numbers, colors, booleans, view model instances, and artboard components — that appear directly in the Rive interface. This means you can write the logic once in a script, and then experiment freely with values, animate properties over time, bind data from external sources, and reuse the same script across multiple instances with different configurations. Inputs transform static scripts into flexible, designer-friendly tools that enable true collaboration and rapid iteration. ## Defining Inputs To make new script inputs, add them to the type and set the defaults in the script's return function. ```lua theme={null} -- Define the script's data and inputs. type ScriptInputs = { score: Input, menu: Input, newArtboard: Input>, } -- Return a factory function that Rive uses to build the Node instance. return function(): Node return { score = 0, menu = late(), newArtboard = late(), } end ``` ## Setting Input Values To access the input properties in the right sidebar of the editor, select your [Node](/docs/scripting/protocols/node-scripts) or [Layout script](/docs/scripting/protocols/layout-scripts) in the Hierarchy Panel or the [Converter](/docs/scripting/protocols/converter-scripts) in the Data Panel. Node script input

## Data Binding Inputs You can use [Data Binding](/docs/editor/data-binding/overview) to control input values at runtime. To data bind an input, right-click the input field in right sidebar, choose Data Bind, and select a property. Data bind a converter input

## Listening for Changes to Inputs The `update` function fires every time any input changes. ```lua theme={null} function update(self: MyNode) print('An update changed') end ``` # WGSL Shaders Source: https://rive.app/docs/scripting/wgsl-shaders Create and render custom WGSL shaders in Rive. Shaders are currently only available in [Early Access](https://rive.app/downloads?utm_source=docs\&utm_medium=content). Runtime support is either in development or available as experimental builds. Have feedback? Join the [Early Access community](https://community.rive.app/c/early-access/) to share your thoughts and help shape the feature. Shaders in Rive let you write custom WGSL programs that run on the GPU and render to a GPU canvas, which can then be drawn in your Rive file. They are useful for effects, procedural graphics, and visuals that go beyond what the vector renderer and standard Node scripts can produce. **What's a shader?** A shader is a small program that runs on the GPU. GPUs are good at running the same program across many vertices or pixels in parallel, which makes shaders useful for graphics effects. A typical GPU pipeline uses two shader functions: * **Vertex shader** - decides where vertices are drawn. * **Fragment shader** - decides the color of each pixel covered by those vertices. ## Creating a Shader Asset [Create a new script](/docs/scripting/creating-scripts), select **Shader** as the type, and name it `BasicShader`. The [AI Agent](/docs/editor/ai-agent/ai-agent) can be a helpful way to create or iterate on shader code. Describe the effect you want, then review and test the generated WGSL in your file. ## Basic WGSL Shader This shader draws a single large triangle that covers the render target. This is a common technique called a fullscreen triangle. The fragment shader then colors each pixel with a gradient. No vertex or index buffers are needed because the triangle points are defined directly in the shader. Basic gradient shader preview

```wgsl theme={null} // ---------------------------------------------------------------------------- // VertexOutput describes the data that flows OUT of the vertex shader and // INTO the fragment shader. Think of it as a small "package" of values that // gets automatically interpolated (smoothly blended) across each pixel of // the triangle before the fragment shader receives it. // ---------------------------------------------------------------------------- struct VertexOutput { // @builtin(position) is REQUIRED — it tells the GPU where this vertex // sits on screen, in "clip space" (x and y roughly range from -1 to 1). @builtin(position) position: vec4, // @location(0) is a CUSTOM output we're choosing to pass along — in this // case, UV coordinates (a 2D position ranging from 0 to 1) that we will // use in the fragment shader to build our gradient. @location(0) uv: vec2, } // ---------------------------------------------------------------------------- // The VERTEX shader. // @vertex marks this function as the entry point that runs once per vertex. // The GPU calls this function 3 times (once per corner of our triangle), // automatically passing in vertexIndex = 0, 1, then 2. // ---------------------------------------------------------------------------- @vertex fn vs_main(@builtin(vertex_index) vertexIndex: u32) -> VertexOutput { // Here we define 3 fixed 2D points that make up one giant triangle. // It's intentionally bigger than the screen (-1..3 instead of -1..1) so // that after clipping, it ends up covering the ENTIRE visible area with // just a single triangle — a cheap way to draw a fullscreen effect. var pos = array, 3>( vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0), ); // Look up which of the 3 points we're currently processing. let p = pos[vertexIndex]; // Create the output package described by VertexOutput above. var out: VertexOutput; // Clip space positions need to be a vec4 (x, y, z, w). We use z = 0.0 // (no depth) and w = 1.0 (no perspective division needed for 2D). out.position = vec4(p, 0.0, 1.0); // Convert our clip-space point (range -1..1) into UV space (range 0..1), // which is a more convenient range for coloring/texturing later on. // Formula: uv = position * 0.5 + 0.5 out.uv = p * 0.5 + vec2(0.5, 0.5); return out; } // ---------------------------------------------------------------------------- // The FRAGMENT shader. // @fragment marks this function as the entry point that runs once per pixel // covered by the triangle. It receives the interpolated VertexOutput values // (the "in" parameter) and must return a final color for that pixel. // ---------------------------------------------------------------------------- @fragment fn fs_main(in: VertexOutput) -> @location(0) vec4 { // The returned color is a vec4: (red, green, blue, alpha), with each // channel ranging from 0.0 (none) to 1.0 (full intensity). // // Here we build a simple gradient: // - red grows from left (0.0) to right (1.0) following UV.x // - green grows from top/bottom (0.0) to (1.0) following UV.y // - blue stays fixed at 0.5 (a constant medium blue tint) // - alpha is 1.0, meaning fully opaque (not transparent) return vec4(in.uv.x, in.uv.y, 0.5, 1.0); } ``` ## Rendering the Shader with a Script ```lua theme={null} type ShaderDemo = { -- The GPUCanvas is an offscreen render target we draw our shader into. -- It behaves like a small texture we fully control with the GPU. canvas: GPUCanvas?, -- The GPUPipeline bundles our compiled shader together with the -- fixed-function GPU settings (what format to draw into, how vertices -- are laid out, etc). It's built once and reused every frame. pipeline: GPUPipeline?, } function init(self: ShaderDemo, context: Context): boolean -- Create a 200x200 GPU canvas to render our shader's output into. self.canvas = context:gpuCanvas({ width = 200, height = 200 }) -- Fetch the compiled shader asset named "BasicShader" local shader = context:shader("BasicShader") if shader and self.canvas then -- Build the pipeline: the same shader module provides both the -- @vertex (vs_main) and @fragment (fs_main) entry points. self.pipeline = GPUPipeline.new({ vertex = shader, fragment = shader, -- No vertex buffers needed — BasicShader generates its fullscreen -- triangle's positions directly from the vertex index. vertexLayout = {}, -- The pipeline's output color format must match the canvas format -- it will be rendering into. colorTargets = { { format = self.canvas.format } }, }) end return true end function drawCanvas(self: ShaderDemo) if self.canvas and self.pipeline then -- Start a GPU render pass targeting our canvas. "clear" wipes it to -- clearColor (opaque black here) before drawing anything new. local pass = self.canvas:beginRenderPass({ color = { { loadOp = "clear", storeOp = "store", clearColor = { 0, 0, 0, 1 } } }, }) -- Tell the GPU which pipeline (shader + settings) to use for the -- draw call below. pass:setPipeline(self.pipeline) -- Draw 3 vertices with no vertex/index buffers — this runs vs_main -- three times (vertexIndex 0, 1, 2), producing our fullscreen triangle, -- then runs fs_main once per covered pixel to shade it. pass:draw(3) -- Submit the pass; the canvas now holds the shader's rendered image. pass:finish() end end function draw(self: ShaderDemo, renderer: Renderer) if self.canvas then -- The GPU canvas exposes its rendered result as a normal Image, so we -- can composite it into the rest of the Rive scene like any other -- image — no special shader knowledge needed here. local sampler = ImageSampler("clamp", "clamp", "bilinear") renderer:drawImage(self.canvas.image, sampler, "srcOver", 1) end end return function(): Node return { canvas = nil, pipeline = nil, init = init, drawCanvas = drawCanvas, draw = draw, } end ``` ### How It Works #### `context:shader` `context:shader("BasicShader")` retrieves the compiled shader asset by name. The name must match the shader asset in your file. #### `GPUCanvas` `context:gpuCanvas()` creates the render target the shader draws into. The canvas exposes its rendered result as `canvas.image`. #### `GPUPipeline` `GPUPipeline.new()` combines the shader with render settings such as vertex layout and color target format. #### `drawCanvas` Use `drawCanvas` for GPU rendering. This is where you begin a render pass, set the pipeline, and issue draw calls. #### `draw` Use `draw` to draw the rendered canvas image into the Rive scene. ## Shader Targets When nothing is selected in the editor, the Inspector shows file-level **Shader Targets** options. Use these options to choose which shader languages Rive should generate from your WGSL shaders: * **Metal (MSL)** * **GLSL ES 300** * **HLSL** * **SPIR-V** Enable the targets required by the runtimes and platforms where your file will be used. Shader Targets options in the Inspector

# Learn Rive Source: https://rive.app/docs/tutorials/learn-rive Discover tutorials, example files, videos, demos, and community resources to learn Rive and build interactive experiences. Ask questions, share your work, find jobs, and connect with other Rive users. A complete YouTube series covering the fundamentals of Rive. Deep dives, product updates, and insights into building interactive experiences. Stay up to date with new features, tutorials, and case studies. Chat with the community in real time and get quick feedback. ## Learn by Example Learn by opening Rive files and runtime demos. Explore real Rive files and open them directly in the editor to see how they’re built. Examples that use scripting to control behavior and interactivity. See how Rive integrates across web, mobile, and game engines. ## Featured videos

` element, Heading 2 to `