Context - Rive

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`

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.

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`

viewModel() -> ViewModel?

Returns the ViewModel bound to the node’s immediate data context. This is the most common way to read data-bound properties from a script.

function init(self: MyNode, context: Context): boolean
  local vmi = context:viewModel()
  if vmi then
    local cannon = vmi:getTrigger('cannon')
  end

  return true
end

`rootViewModel`

rootViewModel() -> ViewModel?

Returns the ViewModel bound to the root artboard’s data context. Useful when you need to access top-level data from a deeply nested node.

function init(self: MyNode, context: Context): boolean
  local vmi = context:rootViewModel()
  if vmi then
    local cannon = vmi:getTrigger('cannon')
  end

  return true
end

`dataContext`

dataContext() -> DataContext?

Returns the data context provided to this node.

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`

image(name: string) -> Image?

Returns an image asset by name, or nil if not found. The returned Image can be drawn via drawImage. See also ImageSampler. Check out Scripting demos to see a working example.

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<DrawImage>
  return {
    myImage = nil,
    sampler = nil,
    init = init,
    draw = draw,
  }
end

`blob`

blob(name: string) -> Blob?

Returns a Blob (raw binary data) asset by name, or nil if not found. Useful for loading custom data files embedded in the Rive file.

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<DrawBlob>
    return {
        myBlob = nil,
        init = init,
    }
end

`audio`

audio(name: string) -> AudioSource?

Returns an AudioSource asset by name. The returned source can be played using the global Audio API.

type AudioExample = {
  play: Input<Trigger>,

  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<AudioExample>
  return {
    play = playSound,
    source = nil,
    init = init,
  }
end

`canvas`

canvas(desc: {width: number, height: number, clearColor: Color?,}?) -> Canvas

Create a 2D canvas for Rive Renderer drawing. Use beginFrame/endFrame inside drawCanvas 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`

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`

features() -> GPUFeatures

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

`shader`

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`

decodeImage(data: buffer) -> Promise<DecodedImage>

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().

​Methods

​markNeedsUpdate

​viewModel

​rootViewModel

​dataContext

​image

​blob

​audio

​canvas

​gpuCanvas

​features

​shader

​decodeImage