Scene

Scene graph objects for artboards, nodes, and animations.

---

Artboard

Represents a Rive artboard instance.

Attributes

Attribute	Type	Access	Description
width	number	read/write	Artboard width
height	number	read/write	Artboard height
frameOrigin	boolean	read/write	Origin is frame origin
data	typed	read-only	Associated ViewModel data

Methods

artboard:draw(renderer)

Renders the artboard.

artboard:draw(renderer: Renderer)

artboard:advance(deltaTime)

Advances animations. Returns false when done (non-looping).

artboard:advance(deltaTime: number): boolean

artboard:instance(viewModel?)

Creates an independent copy, optionally bound to a ViewModel.

artboard:instance(viewModel?: ViewModel): Artboard

artboard:animation(name)

Gets an animation by name.

artboard:animation(name: string): Animation?

artboard:bounds()

Gets the bounding box.

artboard:bounds(): Vector, Vector  -- min, max

artboard:node(name)

Gets a node's data by name.

artboard:node(name: string): NodeData?

artboard:addToPath(path, transform?)

Adds the artboard's geometry to a Path, optionally transformed.

artboard:addToPath(path: Path, transform?: Mat2D)

Pointer Methods (Event Forwarding)

Used to forward pointer events to nested/instantiated artboards. Returns hit-test result (0 = miss, non-zero = hit).

artboard:pointerDown(event: PointerEvent): number
artboard:pointerUp(event: PointerEvent): number
artboard:pointerMove(event: PointerEvent): number
artboard:pointerExit(event: PointerEvent): number

Note: Use these methods to forward PointerEvent objects to nested artboards. Node script handlers already receive PointerEvent objects. See PointerEvent.

See Also: Animation, PointerEvent

---

Node

A scripted node that can be attached to any Node in Rive. Renders in the local transform space of the hosting Node.

The hosting Node is a scene-hierarchy relationship, not an extra lifecycle parameter. Nesting a script node under a group or shape affects transform inheritance, opacity, and draw order. A Node script still receives the normal Node protocol values (context, renderer, seconds, pointer events) and does not automatically receive the parent shape's NodeData or PathData.

Protocol Methods

init(self, context): boolean

Called once when the node is created. Return true to keep the script active.

function init(self: MyNode, context: Context): boolean
    self.counter = 0
    print("Node initialized")
    return true
end

advance(self, seconds): boolean

Optional per-frame update. Return true to continue receiving calls.

function advance(self: MyNode, seconds: number): boolean
    self.counter += seconds
    return true  -- Keep running
end

update(self)

Called when an Input value changes.

function update(self: MyNode)
    print("Input changed!")
end

draw(self, renderer)

Called to render the node.

function draw(self: MyNode, renderer: Renderer)
    renderer:drawPath(self.path, self.paint)
end

Pointer Event Handlers

pointerDown(self, event)

Triggered when pointer presses down.

function pointerDown(self: MyNode, event: PointerEvent)
    print(`Pressed at ({event.position.x}, {event.position.y})`)
    event:hit()  -- Consume the event
end

pointerMove(self, event)

Triggered when pointer moves.

pointerUp(self, event)

Triggered when pointer releases.

pointerExit(self, event)

Triggered when pointer leaves the node area.

Factory Pattern

Node scripts return a factory function:

function draw(self: MyNode, renderer: Renderer)
end

return function(): Node<MyNode>
    return {
        init = init,
        advance = advance,
        draw = draw,
        pointerDown = pointerDown,
        myProperty = late(),  -- Deferred initialization
    }
end

See Also: PointerEvent, Renderer, NodeData

---

Animation

Controls animation playback.

Attributes

animation.duration

Total animation length in seconds. Type: number (read-only)

Methods

animation:advance(deltaTime)

Advances the animation. Returns false when complete (non-looping).

animation:advance(deltaTime: number): boolean

animation:setTime(seconds)

Jumps to a specific time.

animation:setTime(seconds: number)

animation:setTimeFrames(frames)

Jumps to a specific frame.

animation:setTimeFrames(frames: number)

animation:setTimePercentage(percent)

Jumps to a percentage (0.0-1.0) of duration.

animation:setTimePercentage(percent: number)

Example: Animation Scrubber

-- Assumes you have an Artboard reference (e.g., Input<Artboard<...>> named artboard)
function update(self)
    local anim = self.artboard:animation("Idle")
    anim:setTimePercentage(self.progress)
end

See Also: Artboard.animation

Next Steps

• Continue to Data & Input
• Need a refresher? Review Quick Reference