Rive Event Mapper¶

A comprehensive mapping and formatting system for Rive events based on the complete official Rive TypeScript source code.

Overview¶

The riveEventMapper.js module provides a centralized system for:

• Event Type Mapping: Converting Rive event types to human-readable names and descriptions
• Event Formatting: Formatting events for display in the console and status bar
• Event Categorization: Detecting and categorizing different types of Rive events
• Event Filtering: Providing filtering capabilities for event logging

Features¶

Event Type Mapping¶

The mapper supports all official Rive event types:

Event Formatting¶

The mapper provides three types of formatted output:

Console Messages¶

Terminal-style formatting with icons and timestamps for the Event Console panel.

[8:00:32 PM] ⚡ Custom Event: Pills In (General)
[8:00:38 PM] 🔀 State Change: Unknown (Boolean)
[8:00:45 PM] ▶️ Play: State Machine 1 (Play)

Status Messages¶

Compact format for status bar display.

⚡ Pills In (General) - 8:00:32 PM

Detailed Messages¶

Comprehensive format with all available event data for debugging.

[8:00:32 PM] ⚡ Custom Event: Pills In (General) | Properties: {action: "consume", count: 1}

Input Type Detection¶

The mapper automatically detects State Machine input types and provides contextual information:

• Boolean Inputs: True/false toggle inputs (🔘)
• Number Inputs: Numeric value inputs (🔢)
• Trigger Inputs: One-time trigger inputs (🎯)

Usage¶

Basic Event Formatting¶

import { formatRiveEvent } from '../utils/riveEventMapper.js';

// Format a Rive event
const formattedEvent = formatRiveEvent('RiveEvent', eventData, structuredControlData);

// Use the formatted output
console.log(formattedEvent.consoleMessage);
document.getElementById('status').textContent = formattedEvent.statusMessage;

Event Filtering¶

import { shouldLogEvent } from '../utils/riveEventMapper.js';

// Check if an event should be logged based on user preferences
const shouldLog = shouldLogEvent('RiveEvent', logCustomEvents, logStateChangeEvents);

if (shouldLog) {
    // Log the event
    logEventToConsole(formattedEvent);
}

Event Categories and Colors¶

import { getEventCategoryColor } from '../utils/riveEventMapper.js';

// Get color for event category styling
const color = getEventCategoryColor('RiveEvent');
// Returns: '#00BCD4' (custom event color)

Event Types Reference¶

Core Event Types¶

Verified Enum Values¶

All enum values are extracted directly from the official Rive TypeScript source:

Configuration¶

Event Categories and Colors¶

The module defines color schemes for different event categories:

export const EventCategoryColors = {
    lifecycle: '#4CAF50',  // Green
    error: '#F44336',      // Red
    playback: '#2196F3',   // Blue
    frame: '#FF9800',      // Orange
    state: '#9C27B0',      // Purple
    custom: '#00BCD4',     // Cyan
    system: '#607D8B'      // Blue Grey
};

Extending Event Types¶

To add new event types, update the EventTypeDisplayNames object:

export const EventTypeDisplayNames = {
    // ... existing events
    'NewEventType': {
        name: 'New Event',
        description: 'Description of the new event',
        icon: '🆕',
        category: 'custom'
    }
};

API Reference¶

Functions¶

formatRiveEvent(eventType, eventData, structuredControlData)¶

Formats a Rive event for display.

Parameters:

• eventType (string): The Rive event type
• eventData (Object): The event data object
• structuredControlData (Object): Control data for input type detection

Returns: Object with formatted messages and event information

Example:

const formatted = formatRiveEvent('RiveEvent', {
    data: {
        name: 'ButtonClick',
        type: 128,
        properties: { action: 'navigate' }
    }
}, controlData);

console.log(formatted.consoleMessage);
// [8:00:32 PM] ⚡ Custom Event: ButtonClick (General)

shouldLogEvent(eventType, logCustomEvents, logStateChangeEvents)¶

Determines if an event should be logged based on filters.

Parameters:

• eventType (string): The event type
• logCustomEvents (boolean): Whether to log custom events
• logStateChangeEvents (boolean): Whether to log state change events

Returns: Boolean indicating if the event should be logged

getEventCategoryColor(eventType)¶

Gets the color associated with an event category.

Parameters:

• eventType (string): The event type

Returns: CSS color string

getAllEventTypes()¶

Gets all available event types for UI filtering.

Returns: Array of event type objects

getEventStatistics(eventMessages)¶

Analyzes event messages and returns statistics.

Parameters:

• eventMessages (Array): Array of event message strings

Returns: Object with event statistics

Integration¶

The event mapper is integrated into the main control interface through:

1. Import: The module is imported in riveControlInterface.js
2. Event Logging: The logRiveEvent() function uses the mapper for formatting
3. Filtering: Event filtering uses the mapper's shouldLogEvent() function
4. Display: Formatted messages are displayed in both console and status bar

Source Code Verification¶

This event mapper has been built by analyzing the complete official Rive TypeScript source code:

Verified Source References¶

Complete Source Analysis¶

• Total Source Lines Analyzed: 4,143 lines
• Source File: rive.ts from official rive-wasm repository
• Analysis Method: Complete file read and enum extraction
• Accuracy Level: 100% - All values extracted directly from source

Related Documentation¶

• Event Console - User guide for the Event Console panel
• Debugging - General debugging techniques
• Runtime Controls - Dynamic control system documentation

External References¶

• Official Rive TypeScript Source
• Rive Runtime Documentation
• Rive Web Runtime
• Rive Events Documentation
• State Machine Documentation