Skip to main content

Runtime Compatibility Baseline

This page tracks three independent dimensions for Luau surfaces:

  • what is bound in runtime
  • what is documented upstream
  • what is editor-visible / usable in typical production workflows

Baseline Snapshot​

  • Audit date: June 4, 2026
  • Runtime repo: rive-app/rive-runtime
  • Current C++ WASM runtime release line (npm): 2.37.8
  • Checked npm packages: @rive-app/canvas, @rive-app/canvas-lite, @rive-app/webgl2, @rive-app/canvas-advanced (all resolved to 2.37.8)
  • Runtime source gitHead (npm metadata for 2.37.8 packages): bc560112ab2ee7d0afd3418bd97970c2fcb36532
  • npm publish timestamp for @rive-app/[email protected]: May 21, 2026 18:06:40 UTC
  • Docs comparison source: https://rive.app/docs/llms-full.txt fetched June 4, 2026
  • Source-level API snapshot checked: runtime-v0.1.106 at commit 5360c834eac2adbdfc49c808d1b2a8c61b014bbf
  • Superseded historical source audit: runtime-v0.1.64 at commit b25a32218c6308ac8dc4b1cb69df62de84d78ba4

Use this snapshot when deciding whether LERP content is current for C++ runtime behavior.

Separate runtime facts from editor rollout

LERP now tracks the public package/docs baseline (2.37.8), the source-level API snapshot used for binding checks (runtime-v0.1.106), and the editor availability tier separately. Shader/GPU APIs are present in the source-level snapshot and public docs, but the shader asset workflow remains Rive Early Access only and should not be assumed available in standard workspaces.

Source-of-truth rule

For release tracking, LERP records both:

  • npm package metadata (version, time, gitHead) for shipped web runtime line
  • upstream runtime tag/commit used for binding-level API verification

Release Tiering Used in LERP​

LERP uses the following tier labels:

  • Officially released: teach as stable curriculum surface (runtime + docs + editor workflow are broadly usable)
  • Rive Early Access only: runtime/reference material exists, but the editor workflow currently requires Rive Early Access; do not assume availability in standard workspaces
  • Preview / rollout-dependent: runtime/docs may expose it, but editor visibility/tooling is not consistently available yet
  • Not exposed: not usable from current C++ Luau bindings

This prevents course drift when upstream API pages move faster than editor rollout.

"Coming Soon" Reality Check​

Status legend:

  • Live: Exposed and usable in current runtime bindings
  • Partial: Surface exists but is limited vs docs wording
  • Not exposed: Not currently available in Luau bindings at this baseline
Surface in docsRuntime statusNotes
FocusEventLivelistenerContext:asFocus() returns focus payload with isFocus
KeyPhaseLiveExposed as "down", "repeat", "up" through keyboard invocation
KeyboardEventLivekey, modifier flags, and phase are available
ListenerContextLiveis... / as... methods are implemented and wired
TextInputLivelistenerContext:asTextInput().text is available
NoneEventLiveisNone() and asNone() are available
NodeReadData.paint + node:asPath() + node:asPaint()LivePaint/path access is implemented in Lua artboard bindings
AudioSource.durationLivesource.duration is exposed in Lua audio bindings
ReportedEventPartialInvocation exists; exposed payload is currently limited (delaySeconds)
ViewModelChangePartialInvocation exists; payload wrapper is currently minimal
PointerTypePartialNo standalone type table; PointerEvent.type string values are live
ViewModel.nameNot exposedDocumented upstream but not exposed in current Lua ViewModel wrapper
OutputNot exposedNo runtime Lua Output surface at this baseline

Runtime Surfaces Tracked in Current Baseline​

The rows below were revalidated against the June 4 public package/docs baseline (2.37.8) and source-level API snapshot (runtime-v0.1.106). Shader/GPU rows are live in the checked source/docs, but remain Early Access editor workflow material.

SurfaceRuntime statusLERP tierNotes
Mat4LiveOfficially releasedFull constructors, multiplication, inversion, transpose, and vector transforms are bound
Promise, async, awaitLiveOfficially releasedPromise chaining/cancel/status APIs plus async coroutine bridge are available
ViewModel:getImage(name)LiveOfficially releasedReturns Property<Image>?
ViewModel:getIndex()LiveOfficially releasedReturns list-item index; returns -1 when VM is not list-bound
PropertyList:removeAt, removeAllOf, clearLiveOfficially releasedRemoval/clear operations are implemented, with 1-based removeAt input
ListenerContext:isGamepad() / asGamepad()LiveOfficially releasedGamepad invocation payload is exposed (deviceId, buttonMask, axis0)
Node keyboardEvent(self, event)LiveOfficially releasedReturning true stops propagation
Node textEvent(self, event)LiveOfficially releasedReturning true stops propagation
context:canvas(options) + Canvas methodsLiveOfficially releasedOffscreen canvas with beginFrame / endFrame / resize, plus image/width/height
context:decodeImage(buffer) + DecodedImageLiveOfficially releasedPromise resolves to { data, width, height } RGBA premultiplied pixels
context:gpuCanvas(options) + GPUCanvasLiveRive Early Access onlyRuntime surface exists, but shader/GPU editor workflow availability currently requires Rive Early Access
context:features() + GPUFeaturesLiveRive Early Access onlyCapability flags and limits for GPU preview workflows; relevant to Early Access shader material
context:shader(name) + ShaderLiveRive Early Access onlyRequires shader assets and Early Access editor visibility; can return nil in non-enabled workflows
GPUBuffer, GPUTexture, GPUSampler, GPUBindGroup, GPUBindGroupLayout, GPUPipeline, GPURenderPass, GPUTextureViewLiveRive Early Access onlyExposed in the shader reference/runtime surface, but taught as Early Access until editor/tooling rollout is broad
Scripted Interpolator protocolLive (runtime-backed)Officially releasedtransform / transformValue hooks available with linear fallback behavior

Shader Early-Access Baseline Addendum (June 4, 2026)​

The public npm/docs baseline above has been rechecked at 2.37.8, and the current source-level audit uses runtime-v0.1.106. Shader/GPU scripting is part of that current source snapshot, but this material is currently Rive Early Access only because the editor workflow for shader assets is not broadly available.

Use this addendum as the source of truth for LERP's shader lessons, not as a signal that shader scripting is broadly released in standard Rive workspaces.

  • Shader baseline date: June 4, 2026
  • Shader API source reviewed: runtime-v0.1.106 at commit 5360c834eac2adbdfc49c808d1b2a8c61b014bbf
  • Public docs source checked: https://rive.app/docs/llms-full.txt, including GPUCanvas, GPU object-family pages, context:gpuCanvas, context:features, context:shader, and drawCanvas
  • Local reference document: /Users/ivg/github/luau-scripting/rive_shader_api_reference_runtime_v0106_type_safe.md
  • Local example corpus: /Users/ivg/github/luau-scripting/gpu_shaders
  • Current availability tier: Rive Early Access only

LERP now teaches the following shader-specific rules:

SurfaceLERP guidanceNotes
drawCanvas(self)Use for Canvas:beginFrame(...) and GPUCanvas:beginRenderPass(...)draw(self, renderer) remains the normal compositing callback
context:shader(name)Use for compiled .wgsl shader asset lookupReturns Shader?; guard nil
GPUCanvas.formatUse for pipeline color-target formatAvoid hard-coded formats unless you intentionally own the render target
Image:view()Use to sample image assets in shader bind groupsShader usage is Rive Early Access only because it depends on GPU workflow availability
Dynamic UBO offsetsTreat as layout/binding ordered byte offsetsUse 256-byte alignment
Direct 3D model importNot provided by the shader API itselfConvert mesh data externally into buffers/textures

Compatibility naming note: older docs and examples may mention context:loadShader(name) or context:preferredCanvasFormat(). New LERP shader examples use context:shader(name) and GPUCanvas.format.

Practical Guidance for LERP Content​

  • Teach ListenerAction.performAction(self, listenerContext) as the primary listener callback shape.
  • Use listenerContext:is...() and listenerContext:as...() for event-safe branching.
  • Treat PointerEvent.type as string-based ("pointerDown", "pointerMove", etc.).
  • Do not teach viewModel.name as available in Luau at this baseline.
  • Do not present Output<T> as currently exposed in C++ Luau bindings.
  • For list-bound ViewModels, use viewModel:getIndex() and handle detached state (-1).
  • For PropertyList:removeAt(index), use 1-based indices and validate bounds.
  • Keep GPU shader/pipeline material in Rive Early Access only sections until editor-side shader asset visibility is broadly available.
  • When context:shader(name) returns nil, treat that as a possible asset name, packaging, or rollout/tooling gap before assuming script logic failure.
  • Use drawCanvas(self) for GPU and offscreen-canvas render passes; use draw(self, renderer) to composite the resulting image.

Re-Audit Workflow (for future updates)​

  1. Fetch latest runtime: git clone/git pull rive-app/rive-runtime.
  2. Record latest npm release line for C++ WASM runtime packages:
    • npm view @rive-app/canvas version
    • npm view @rive-app/canvas-lite version
    • npm view @rive-app/webgl2 version
    • npm view @rive-app/canvas-advanced version
  3. Pin npm gitHead hash and npm publish timestamp in this page.
  4. Pin upstream runtime source tag/commit used for API verification.
  5. Pull latest docs machine-readable source (/docs/llms-full.txt) and list (Coming soon) API sections.
  6. For each surface, verify:
    • type/wrapper exists in runtime headers
    • Lua atoms/bindings exist
    • invocation/dispatch path exists (not only a stub)
  7. Update:
    • this page
    • affected API lessons/examples/quizzes
    • changelog entry with audit protocol details

Audit Protocol (what this update checked)​

For the June 4, 2026 pass, LERP used this verification sequence:

  1. Runtime release check via npm registry
    • Ran npm view for @rive-app/canvas, @rive-app/canvas-lite, @rive-app/webgl2, and @rive-app/canvas-advanced
    • Confirmed all report 2.37.8
  2. npm source pin
    • Pinned npm gitHead bc560112ab2ee7d0afd3418bd97970c2fcb36532 for runtime line 2.37.8
    • Recorded the @rive-app/[email protected] publish timestamp: May 21, 2026 18:06:40 UTC
  3. Public docs source
    • Fetched https://rive.app/docs/llms-full.txt
    • Confirmed the docs now include GPUCanvas, GPU object-family pages, context:gpuCanvas, context:features, context:shader, and drawCanvas
    • Confirmed Output remains marked (Coming soon)
  4. Shader/API source pin
    • Pinned runtime-v0.1.106 at 5360c834eac2adbdfc49c808d1b2a8c61b014bbf for source-level API verification
    • Spot-checked the compatibility rows in Luau binding headers/source/tests, including listener payloads, NodeReadData.paint, asPath, asPaint, audio duration, ViewModel property/list helpers, Promise/async, Mat4, canvas/GPU context APIs, GPU object bindings, and Scripted Interpolator
    • Kept shader/GPU lessons in Rive Early Access only tier because editor-side shader asset workflow availability is not broadly assumed
  5. Course sync pass
    • Updated runtime compatibility notes, API baseline callouts, errata header, and changelog wording

For the May 12, 2026 pass, LERP used this verification sequence:

  1. Runtime release check via npm registry
    • Ran npm view for @rive-app/canvas, @rive-app/canvas-lite, @rive-app/webgl2, and @rive-app/canvas-advanced
    • Confirmed all report 2.37.6
  2. npm source pin
    • Pinned npm gitHead 2833de372c0d22596494c89c328008ce5b1106d7 for runtime line 2.37.6
  3. Upstream runtime API snapshot pin
    • Pinned runtime-v0.1.64 at b25a32218c6308ac8dc4b1cb69df62de84d78ba4
  4. Docs delta source
    • Compared against https://rive.app/docs/llms-full.txt, including APIs marked (Coming soon)
  5. Binding-level verification
    • Confirmed availability/limits by checking runtime Luau bindings and invocation paths (not docs text alone)
  6. Course sync pass
    • Updated API pages, lessons, examples, quizzes, and compatibility notes

Changelog Requirements for Runtime Audits​

Every runtime-audit changelog entry should include:

  • Audit date
  • Upstream source tag/commit used for API validation
  • npm runtime release line + packages checked
  • npm gitHead + npm publish timestamp
  • Which surfaces changed status (Officially released, Rive Early Access only, Preview / rollout-dependent, Not exposed)
  • Which course pages were updated (docs + lessons + quizzes)