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
log
markNeedsUpdate
markNeedsUpdate from inside update() are ignored. Use it from init(), advance(), listener callbacks, or event handlers instead.
viewModel
rootViewModel
globalViewModel
globalViewModelNames
globalViewModel to fetch the corresponding view model.
dataContext
image
drawImage.
See also ImageSampler.
Check out Scripting demos to see a working example.
blob
font
bindableArtboard
name is nil; nil when
there is no such artboard. Assign it to a view model artboard
property (see ViewModel:getArtboard) and whatever is bound to that
property shows it, bound to the same data an artboard chosen in the
editor would be: the host’s. For an artboard of another file, decode
that file with decodeFile and use RiveFile:bindableArtboard.
audio
Audio API.
canvas
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.
clearColor is ignored here; pass it to beginFrame instead.
gpuCanvas
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.
gpuTarget
view
is nil and passes into it drop. Nil where the host can never expose
one; keep a gpuCanvas and draw its image instead.
features
shader
decodeImage
loadImage
drawImage, or assign it
to a view model image property so whatever is bound to it shows it.
Native runtimes decode on the calling thread, and the Promise rejects
with “failed to decode image data” when the bytes do not decode. Web
runtimes, the editor and the CLI preview decode in the background:
there the Promise resolves with an Image whose width and height are 0
until it has decoded, and bytes that do not decode give an Image that
never draws.