上下文（Context）

上下文（Context）是在脚本化节点初始化（通过 init 函数）期间提供的对象。 它作为脚本与 Rive 运行时之间的桥梁，提供以下能力：

• 更新调度（Update scheduling）—— 请求节点在下一帧更新。
• 数据（ViewModels）—— 访问绑定到节点或根画板上的 ViewModel 数据上下文。
• 资源（Assets）—— 按名称获取已添加到 Rive 文件中的资源（图像、Blob 和音频）。

方法（Methods）

markNeedsUpdate

markNeedsUpdate() -> ()

将对象标记为下一帧需要更新。 当发生变化时（例如来自监听器回调）且需要运行时重新调用节点的 update 函数时，请调用此方法。 注意：从 update() 内部调用 markNeedsUpdate 会被忽略。请在 init()、advance()、监听器回调或事件处理器中使用。

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?

返回绑定到节点当前数据上下文的 视图模型（ViewModel）。这是从脚本中读取数据绑定属性最常用的方式。

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?

返回绑定到根画板数据上下文的 视图模型（ViewModel）。 当需要从深层嵌套节点访问顶层数据时很有用。

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?

返回提供给此节点的数据上下文。

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?

按名称返回图像资源，如果未找到则返回 nil。 返回的 图像（Image） 可通过 drawImage 绘制。

另请参阅 ImageSampler。

查看 脚本演示 以了解工作示例。

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?

按名称返回 二进制块（Blob）（原始二进制数据）资源，如果未找到则返回 nil。 适用于加载嵌入在 Rive 文件中的自定义数据文件。

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('Blob data buffer:', self.myBlob.data)
    end

    return true
end

return function(): Node<DrawBlob>
    return {
        myBlob = nil,
        init = init,
    }
end

audio

audio(name: string) -> AudioSource?

按名称返回 音频源（AudioSource） 资源。返回的源可通过全局 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

创建一个用于 Rive Renderer 绘制的 2D 画布。 在 drawCanvas 内使用 beginFrame/endFrame 进行渲染。

描述符是可选的。省略描述符（或传入 width/height 为 0）会创建一个没有后备纹理的 deferred canvas——这对于在 init 阶段还不知道尺寸的 layout scripts 很有用。等真实尺寸已知后，调用 canvas:resize(w, h)。处于 deferred 状态时，canvas.image 为 nil，width/height 报告为 0；调用 beginFrame() 会抛出指向 resize() 的错误。可检查 canvas.width > 0 来决定是否执行相关工作。

gpuCanvas

gpuCanvas(desc: {width: number, height: number,}?) -> GPUCanvas

创建一个 GPU 画布 —— 1× 呈现目标。通过 canvas:beginRenderPass(...) 渲染到它。对于 MSAA，需自行使用 GPUTexture.new({ sampleCount = N, renderTarget = true }) 分配多重采样颜色和深度纹理，并在描述符中传入。

描述符是可选的。省略描述符（或传入 width/height 为 0）会创建一个没有后备纹理的 deferred canvas——这对于在 init 阶段还不知道尺寸的 layout scripts 很有用。等真实尺寸已知后，调用 canvas:resize(w, h)。处于 deferred 状态时，width/height 报告为 0，调用 colorView() 会抛出指向 resize() 的错误。可检查 canvas.width > 0 来决定是否执行相关工作。

features

features() -> GPUFeatures

查询 GPU 能力。返回一个包含当前后端支持的 features 和 limits 的 table。

preferredCanvasFormat

preferredCanvasFormat() -> TextureFormat

返回当前平台的原生画布纹理格式。

这是 context:gpuCanvas(...) 后备纹理所使用的格式，因此也是 canvas.format 将报告的格式。等效于 WebGPU 的 navigator.gpu.getPreferredCanvasFormat()。

• Metal（macOS/iOS）：'rgba8unorm'（离屏画布，非 CAMetalLayer 表面）
• D3D11/D3D12（Windows）：'bgra8unorm'
• Vulkan、OpenGL、WebGPU：'rgba8unorm'（安全默认值；实际表面格式可能不同——请使用 canvas.format 获取画布存在后的权威值）

在 init 时使用此方法创建与画布格式匹配的 GPUTexture 和 GPUPipeline：

local fmt = context:preferredCanvasFormat()
self.pipeline = GPUPipeline.new({ colorTargets = {{ format = fmt }}, ... })

loadShader

loadShader(name: string) -> Shader?

按资源名称加载已编译的着色器。返回一个可在 GPUPipeline.new() 中使用的 Shader，如果未找到则返回 nil。

decodeImage

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

将压缩的图像数据（PNG、JPEG、WebP）解码为预乘的 RGBA8 像素。 返回一个解析为 DecodedImage table 的 Promise。 可在 async() 内使用 await()，或链式调用 :andThen()。