Skip to main content

Rive Configuration

Overview​

Maestro overlays use Rive animations to provide smooth, vector-based graphics and interactive animations. Rive enables high-quality animations that scale perfectly across different screen sizes while maintaining small file sizes.

What is Rive?​

Rive is a real-time interactive design and animation tool that creates lightweight, scalable animations. Unlike traditional video or GIF-based animations, Rive animations are:

  • Vector-based: Scale to any size without quality loss
  • Interactive: Respond to user input and state changes
  • Lightweight: Small file sizes compared to video alternatives
  • Dynamic: Content can be updated programmatically at runtime

How Overlays Use Rive​

Animation File​

Overlays use a centrally hosted Rive animation file, like the one below:

const WINNING_BET_RIVE_FILE_URL = 'https://link-to-rive-file/67db106027ddcdcd2ecb97d4.riv';

This file contains:

  • Animation sequences for different overlay types
  • Text placeholders for dynamic content
  • State machines for interaction handling
  • Responsive layout definitions

Dynamic Text Updates​

The Rive animation includes text components that are updated programmatically:

// Set title text
riveInstance.setTextRunValueAtPath('Title', overlayTitle, 'compNotification');

// Set metadata text  
riveInstance.setTextRunValueAtPath('Metadata', overlayMetadata, 'compNotification');

State Machine Control​

Rive animations use state machines to control animation playback:

// Get state machine inputs
const inputs = riveInstance.stateMachineInputs('stateMachine');

// Trigger the play animation
const triggerPlayInput = inputs.find(input => input.name === 'triggerPlay');
if (triggerPlayInput) {
  triggerPlayInput.fire();
}

Implementation Details​

Canvas Setup​

Overlays render Rive animations on HTML5 canvas elements:

// Create Rive instance
const riveInstance = new Rive({
  src: WINNING_BET_RIVE_FILE_URL,
  canvas: canvasElement,
  autoplay: true,
  stateMachines: 'stateMachine',
  onLoad: () => {
    // Configure animation after loading
    configureRiveAnimation();
  }
});

Text Configuration​

After the Rive file loads, text values are set based on overlay content:

function configureRiveAnimation() {
  // Set overlay title
  const title = overlayType === OverlayType.WinningBet 
    ? 'You won your bet!' 
    : 'Fantasy Update';
    
  riveInstance.setTextRunValueAtPath('Title', title, 'compNotification');
  
  // Set overlay message
  const message = getOverlayMessage(overlayData);
  riveInstance.setTextRunValueAtPath('Metadata', message, 'compNotification');
  
  // Trigger animation playback
  triggerAnimation();
}

Animation Lifecycle​

  1. Loading: Rive file is downloaded and parsed
  2. Initialization: Canvas is set up with proper dimensions
  3. Configuration: Text values and state are set
  4. Playback: Animation begins automatically
  5. Interaction: User can interact with the overlay
  6. Cleanup: Resources are disposed when overlay is hidden

Text Placeholders​

The Rive animation includes predefined text placeholders:

Title Placeholder​

  • Path: 'Title' in 'compNotification' component
  • Usage: Main overlay title (e.g., "You won your bet!")

Metadata Placeholder​

  • Path: 'Metadata' in 'compNotification' component
  • Usage: Secondary information (e.g., bet details, game information)

State Machine Inputs​

The Rive animation includes several state machine inputs:

triggerPlay​

  • Type: Trigger input
  • Purpose: Starts the main animation sequence
  • Usage: Called when overlay is first displayed

Additional Inputs​

Other inputs may be available for advanced animation control, such as:

  • Hover states
  • Click feedback
  • Exit animations

Responsive Design​

Rive animations automatically adapt to different overlay sizes:

// Standard size
const size = { width: 570, height: 128 };

// Compact size  
const compactSize = { width: 400, height: 96 };

// The Rive animation scales automatically
overlayEvent.size = size;

Performance Optimization​

Loading Optimization​

  • Caching: Rive files are cached by the browser
  • Preloading: Files can be preloaded for faster display
  • CDN Delivery: Files are served from a global CDN

Runtime Optimization​

  • GPU Acceleration: Rive uses hardware acceleration when available
  • Efficient Rendering: Only redraws when necessary
  • Memory Management: Proper cleanup prevents memory leaks
componentWillUnmount() {
  // Always clean up Rive instances
  if (this.riveInstance) {
    this.riveInstance.cleanup();
  }
}

Error Handling​

Load Errors​

Handle cases where the Rive file fails to load:

const riveInstance = new Rive({
  src: WINNING_BET_RIVE_FILE_URL,
  canvas: canvasElement,
  onLoadError: (error) => {
    console.error('Rive animation failed to load:', error);
    // Fallback to static overlay or hide overlay
    showFallbackOverlay();
  }
});

Text Setting Errors​

Handle errors when setting text values:

try {
  riveInstance.setTextRunValueAtPath('Title', title, 'compNotification');
} catch (error) {
  console.error('Failed to set overlay text:', error);
}

Integration Process​

To use custom Rive animations:

  1. Create Rive file with required components
  2. Upload to appropriate CDN location
  3. Update animation URL in overlay configuration
  4. Test with different overlay types and content

Browser Support​

Rive animations are supported in:

  • Chrome: 57+
  • Firefox: 52+
  • Safari: 11+
  • Edge: 79+

Fallback Strategies​

For unsupported browsers:

  • Static images can be used as fallbacks
  • CSS animations can provide basic motion
  • Overlay content remains functional without animation

Debugging Rive Animations​

Console Logging​

Enable detailed logging for animation debugging:

const riveInstance = new Rive({
  src: animationUrl,
  canvas: canvas,
  onLoad: () => console.log('Rive animation loaded successfully'),
  onLoadError: (error) => console.error('Rive load error:', error),
  onStateChange: (event) => console.log('State change:', event)
});

Animation Inspector​

Use Rive's debugging tools to inspect:

  • Text component paths
  • State machine inputs
  • Animation timing
  • Resource usage

Best Practices​

  • Test Loading: Always test animation loading in different network conditions
  • Handle Errors: Implement proper error handling and fallbacks
  • Optimize Assets: Keep Rive files as small as possible
  • Clean Up: Always dispose of Rive instances to prevent memory leaks
  • Monitor Performance: Track animation performance impact on your application
Last updated on