Rive Instance Methods Reference¶

const rive = new Rive({
  canvas: document.getElementById('canvas'),
  src: 'animation.riv',
  autoplay: true,
  stateMachines: 'State Machine 1',
  layout: new Layout({
    fit: Fit.Cover,
    alignment: Alignment.Center
  })
});

// Play a single animation
rive.play('idle');

// Play multiple animations
rive.play(['idle', 'walk']);

// Resume all paused animations
rive.play();

// Pause specific animation
rive.pause('walk');

// Pause all animations
rive.pause();

// Scrub animation to 2.5 seconds
rive.scrub('walk', 2.5);

// Stop specific animation
rive.stop('walk');

// Stop all animations
rive.stop();

rive.reset({
  artboard: 'Character',
  animations: ['idle'],
  autoplay: true
});

rive.load({
  src: 'new-animation.riv',
  autoplay: true,
  stateMachines: 'State Machine 1'
});

const inputs = rive.stateMachineInputs('State Machine 1');
inputs.forEach(input => {
  console.log(input.name, input.type);
});

// Set boolean state in nested artboard
rive.setBooleanStateAtPath('isActive', true, 'nested/artboard/path');

// Set number state in nested artboard
rive.setNumberStateAtPath('speed', 50, 'character/movement');

// Fire trigger in nested artboard
rive.fireStateAtPath('jump', 'character/actions');

const viewModel = rive.viewModelByName('PlayerData');
if (viewModel) {
  console.log('Found view model:', viewModel.name);
  console.log('Instance count:', viewModel.instanceCount);
}

const viewModel = rive.viewModelByIndex(0);
if (viewModel) {
  const instance = viewModel.defaultInstance();
}

const defaultVM = rive.defaultViewModel();
if (defaultVM) {
  const instance = defaultVM.instance();
  // Work with the instance
}

const viewModel = rive.viewModelByName('GameData');
const instance = viewModel?.defaultInstance();
if (instance) {
  rive.bindViewModelInstance(instance);

  // Now you can manipulate the instance
  instance.number('score')?.value = 100;
  instance.string('playerName')?.value = 'Player 1';
}

const enums = rive.enums();
enums.forEach(dataEnum => {
  console.log('Enum:', dataEnum.name);
  console.log('Values:', dataEnum.values);
});

const viewModel = rive.viewModelByName('PlayerData');
const instance = viewModel?.instanceByName('Player1');

const instance = viewModel.defaultInstance();
const scoreProperty = instance?.number('player/score');
if (scoreProperty) {
  scoreProperty.value = 150;
  console.log('Score:', scoreProperty.value);
}

const nameProperty = instance?.string('player/name');
if (nameProperty) {
  nameProperty.value = 'John Doe';
}

const isActiveProperty = instance?.boolean('player/isActive');
if (isActiveProperty) {
  isActiveProperty.value = true;
}

const colorProperty = instance?.color('theme/primaryColor');
if (colorProperty) {
  colorProperty.rgb(255, 0, 0); // Set to red
  colorProperty.opacity(0.8); // Set opacity
}

const triggerProperty = instance?.trigger('actions/reset');
triggerProperty?.trigger(); // Fire the trigger

const stateProperty = instance?.enum('player/state');
if (stateProperty) {
  console.log('Available states:', stateProperty.values);
  stateProperty.value = 'running';
  // Or by index
  stateProperty.valueIndex = 1;
}

const itemsList = instance?.list('inventory/items');
if (itemsList) {
  console.log('List length:', itemsList.length);

  // Add a new instance
  const newItem = viewModel.instance();
  itemsList.addInstance(newItem);

  // Remove at index
  itemsList.removeInstanceAt(0);

  // Swap items
  itemsList.swap(0, 1);
}

const imageProperty = instance?.image('avatar/picture');
if (imageProperty) {
  // Decode and set a new image
  const imageBytes = await fetch('avatar.png').then(r => r.arrayBuffer());
  const decodedImage = await decodeImage(new Uint8Array(imageBytes));
  imageProperty.value = decodedImage;
}

const nestedInstance = instance?.viewModel('player/stats');
if (nestedInstance) {
  nestedInstance.number('health')?.value = 100;
}

const newStatsInstance = statsViewModel.instance();
const success = instance.replaceViewModel('player/stats', newStatsInstance);

const titleText = rive.getTextRunValue('titleText');
console.log('Title:', titleText);

rive.setTextRunValue('titleText', 'Welcome to the Game!');

const text = rive.getTextRunValueAtPath('label', 'ui/header');

rive.setTextRunValueAtPath('score', '1000', 'ui/hud/scoreDisplay');

// Useful when you need to update the canvas immediately
rive.drawFrame();

// After canvas resize
rive.resizeToCanvas();

// Resize with default device pixel ratio
rive.resizeDrawingSurfaceToCanvas();

// Or with custom ratio
rive.resizeDrawingSurfaceToCanvas(2);

rive.setupRiveListeners({
  isTouchScrollEnabled: true // Allow scrolling on touch devices
});

// Stop rendering when tab is not visible
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    rive.stopRendering();
  } else {
    rive.startRendering();
  }
});

// Show default FPS counter
rive.enableFPSCounter();

// Or with custom callback
rive.enableFPSCounter((fps) => {
  console.log('Current FPS:', fps);
});

rive.on(EventType.Load, () => {
  console.log('Rive loaded!');
});

rive.on(EventType.StateChange, (event) => {
  console.log('States changed:', event.data);
});

rive.on(EventType.RiveEvent, (event) => {
  console.log('Rive event:', event.data);
});

const handler = (event) => console.log(event);
rive.on(EventType.Loop, handler);
// Later...
rive.off(EventType.Loop, handler);

// Remove all loop listeners
rive.removeAllRiveEventListeners(EventType.Loop);

// Remove all listeners
rive.removeAllRiveEventListeners();

// Resize artboard
rive.artboardWidth = 800;
rive.artboardHeight = 600;

const contents = rive.contents;
contents?.artboards.forEach(artboard => {
  console.log('Artboard:', artboard.name);
  console.log('Animations:', artboard.animations);
  console.log('State Machines:', artboard.stateMachines);
});

rive.volume = 0.5; // Set to 50% volume

rive.layout = new Layout({
  fit: Fit.Contain,
  alignment: Alignment.Center
});

// Clean up when component unmounts
rive.cleanup();

const rive = new Rive({
  canvas: document.getElementById('canvas'),
  src: 'animation.riv',
  autoplay: false,
  onLoad: () => {
    // Setup after load
    const vm = rive.defaultViewModel();
    const instance = vm?.defaultInstance();
    if (instance) {
      rive.bindViewModelInstance(instance);

      // Set initial values
      instance.string('playerName')?.value = 'Player 1';
      instance.number('score')?.value = 0;
    }

    // Start playing
    rive.play('idle');
  },
  onLoadError: (e) => {
    console.error('Failed to load:', e);
  }
});

// Clean up on page unload
window.addEventListener('beforeunload', () => {
  rive.cleanup();
});

const audioBytes = await fetch('sound.mp3').then(r => r.arrayBuffer());
const audio = await decodeAudio(new Uint8Array(audioBytes));

// Use the audio with an AudioAsset
audioAsset.setAudioSource(audio);

// Clean up when done
audio.unref();

const imageBytes = await fetch('sprite.png').then(r => r.arrayBuffer());
const image = await decodeImage(new Uint8Array(imageBytes));

// Use the image with an ImageAsset
imageAsset.setRenderImage(image);

// Clean up when done
image.unref();

const fontBytes = await fetch('custom-font.ttf').then(r => r.arrayBuffer());
const font = await decodeFont(new Uint8Array(fontBytes));

// Use the font with a FontAsset
fontAsset.setFont(font);

// Clean up when done
font.unref();

RuntimeLoader.getInstance((runtime) => {
  // Use the runtime
  const renderer = runtime.makeRenderer(canvas);
});

const runtime = await RuntimeLoader.awaitInstance();
const renderer = runtime.makeRenderer(canvas);

// Use a custom CDN or local WASM file
RuntimeLoader.setWasmUrl('/assets/rive.wasm');

const riveFile = new RiveFile({
  src: 'animation.riv',
  onLoad: () => console.log('File loaded'),
  onLoadError: (e) => console.error('Load error:', e)
});

await riveFile.init();

const newLayout = currentLayout.copyWith({
  fit: Fit.Cover,
  alignment: Alignment.TopLeft
});

// Called internally in constructor
this.init({
  src: this.src,
  buffer: this.buffer,
  riveFile: this.riveFile,
  autoplay: params.autoplay,
  animations: params.animations,
  stateMachines: params.stateMachines,
  artboard: params.artboard,
  useOffscreenRenderer: params.useOffscreenRenderer,
});

// Called internally during initialization
this.initData(artboard, startingAnimationNames, startingStateMachineNames, autoplay, autoBind)
  .then((hasInitialized) => {
    if (hasInitialized) {
      return this.setupRiveListeners();
    }
  });

// Automatically called in the render loop
// 1. Calculate elapsed time
// 2. Advance animations and state machines
// 3. Apply changes to artboard
// 4. Clear canvas and draw
// 5. Handle events (loops, state changes)
// 6. Request next frame if playing

// Called during draw() to ensure proper alignment
this.alignRenderer();

// Used by public getTextRunValue() method
const textRun = this.retrieveTextRun(textRunName);
return textRun ? textRun.text : undefined;

// Used by public methods like setBooleanStateAtPath()
const input = this.retrieveInputAtPath(inputName, path);
if (input && input.type === StateMachineInputType.Boolean) {
  input.asBool().value = value;
}

// Used by public property access methods
public number(path: string): ViewModelInstanceNumber | null {
  const viewmodelInstanceValue = this.propertyFromPath(path, PropertyType.Number);
  return viewmodelInstanceValue as ViewModelInstanceNumber;
}

// When you call play(), internally it triggers:
// 1. taskQueue processing if not ready
// 2. animator.play() 
// 3. setupRiveListeners() if needed
// 4. startRendering() which calls draw()
// 5. draw() runs the render loop

// Understanding this helps debug issues like:
// - Why animations don't start immediately
// - How state changes are propagated
// - When listeners are attached/detached

// While technically possible in JavaScript, accessing private fields is discouraged:
// DON'T DO THIS - may break in future versions
const internalLayout = rive._layout; // Bad practice

// DO THIS instead - use public API
const publicLayout = rive.layout; // Good practice