RiveStateMachineInstance - Rive iOS Runtime

Overview

RiveStateMachineInstance represents an instance of a state machine within a Rive artboard. State machines provide interactive control over animations through inputs, handle events, and support touch interactions.

Properties

viewModelInstance

RiveDataBindingViewModelInstance*

required

The view model instance bound to this state machine (read-only, nullable).

State Machine Information

name

Returns the name of the state machine.

return

NSString*

required

The state machine’s name as defined in the Rive file.

- (NSString*)name;

Playback Control

advanceBy:

Advances the state machine by the specified elapsed time.

elapsedSeconds

double

required

The time in seconds to advance the state machine.

return

bool

required

Returns true if the state machine needs to keep advancing, false otherwise.

- (bool)advanceBy:(double)elapsedSeconds;

Input Management

getBool:

Retrieves a boolean input by name.

name

NSString*

required

The name of the boolean input.

return

const RiveSMIBool*

required

The boolean input, or nil if not found.

- (const RiveSMIBool*)getBool:(NSString*)name;

getTrigger:

Retrieves a trigger input by name.

name

NSString*

required

The name of the trigger input.

return

const RiveSMITrigger*

required

The trigger input, or nil if not found.

- (const RiveSMITrigger*)getTrigger:(NSString*)name;

getNumber:

Retrieves a number input by name.

name

NSString*

required

The name of the number input.

return

const RiveSMINumber*

required

The number input, or nil if not found.

- (const RiveSMINumber*)getNumber:(NSString*)name;

inputNames

Returns the names of all inputs in the state machine.

return

NSArray<NSString*>*

required

Array of input names.

- (NSArray<NSString*>*)inputNames;

inputCount

Returns the number of inputs in the state machine.

return

NSInteger

required

The number of inputs.

- (NSInteger)inputCount;

inputFromIndex:error:

Returns an input by its index.

index

NSInteger

required

Zero-based index of the input.

error

NSError**

required

Pointer to an error object that will be set if the operation fails.

return

RiveSMIInput*

required

The input at the specified index, or nil if an error occurs.

- (RiveSMIInput* __nullable)inputFromIndex:(NSInteger)index
                                     error:(NSError**)error;

inputFromName:error:

Returns an input by its name.

name

NSString*

required

Name of the input.

error

NSError**

required

Pointer to an error object that will be set if the operation fails.

return

RiveSMIInput*

required

The input with the specified name, or nil if an error occurs.

- (RiveSMIInput* __nullable)inputFromName:(NSString*)name
                                    error:(NSError**)error;

Layer and State Management

layerCount

Returns the number of layers in the state machine.

return

NSInteger

required

The number of layers.

- (NSInteger)layerCount;

stateChangedCount

Returns the number of state changes that occurred in the last advance.

return

NSInteger

required

The number of state changes.

- (NSInteger)stateChangedCount;

stateChangedFromIndex:error:

Returns a layer state that changed by its index.

index

NSInteger

required

Zero-based index of the state change.

error

NSError**

required

Pointer to an error object that will be set if the operation fails.

return

RiveLayerState*

required

The layer state at the specified index, or nil if an error occurs.

- (RiveLayerState* __nullable)stateChangedFromIndex:(NSInteger)index
                                              error:(NSError**)error;

stateChanges

Returns the names of all states that changed.

return

NSArray<NSString*>*

required

Array of state names that changed.

- (NSArray<NSString*>*)stateChanges;

Event Handling

reportedEventCount

Returns the number of events reported by the state machine since the last frame.

return

NSInteger

required

The number of reported events.

- (NSInteger)reportedEventCount;

reportedEventAt:

Returns a reported event by its index.

index

NSInteger

required

Zero-based index of the reported event.

return

const RiveEvent*

required

The event at the specified index.

- (const RiveEvent*)reportedEventAt:(NSInteger)index;

Touch Interaction

RiveHitResult Enum

Represents the result of a touch interaction.

none

RiveHitResult

required

No hit detected.

hit

RiveHitResult

required

Hit detected on a transparent area.

hitOpaque

RiveHitResult

required

Hit detected on an opaque area.

touchBeganAtLocation:

Notifies the state machine that a touch began.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchBeganAtLocation:(CGPoint)touchLocation;

touchBeganAtLocation:touchID:

Notifies the state machine that a touch began with a specific touch ID (for multitouch support).

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

touchID

int

required

A unique identifier for the touch event.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchBeganAtLocation:(CGPoint)touchLocation
                              touchID:(int)touchID;

touchMovedAtLocation:

Notifies the state machine that a touch moved.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchMovedAtLocation:(CGPoint)touchLocation;

touchMovedAtLocation:touchID:

Notifies the state machine that a touch moved with a specific touch ID.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

touchID

int

required

A unique identifier for the touch event.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchMovedAtLocation:(CGPoint)touchLocation
                              touchID:(int)touchID;

touchEndedAtLocation:

Notifies the state machine that a touch ended.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchEndedAtLocation:(CGPoint)touchLocation;

touchEndedAtLocation:touchID:

Notifies the state machine that a touch ended with a specific touch ID.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

touchID

int

required

A unique identifier for the touch event.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchEndedAtLocation:(CGPoint)touchLocation
                              touchID:(int)touchID;

touchCancelledAtLocation:

Notifies the state machine that a touch was cancelled.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchCancelledAtLocation:(CGPoint)touchLocation;

touchCancelledAtLocation:touchID:

Notifies the state machine that a touch was cancelled with a specific touch ID.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

touchID

int

required

A unique identifier for the touch event.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchCancelledAtLocation:(CGPoint)touchLocation
                                  touchID:(int)touchID;

touchExitedAtLocation:

Notifies the state machine that a touch exited the artboard.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchExitedAtLocation:(CGPoint)touchLocation;

touchExitedAtLocation:touchID:

Notifies the state machine that a touch exited the artboard with a specific touch ID.

touchLocation

CGPoint

required

The touch location in the coordinate space of the artboard.

touchID

int

required

A unique identifier for the touch event.

return

RiveHitResult

required

The hit result of the touch.

- (RiveHitResult)touchExitedAtLocation:(CGPoint)touchLocation
                               touchID:(int)touchID;

Data Binding

bindViewModelInstance:

Binds an instance of a view model to the state machine for updates. A strong reference to the instance being bound must be made if you wish to reuse instance properties or for observability. By default, the instance will also automatically be bound to the artboard containing the state machine.

instance

RiveDataBindingViewModelInstance*

required

The instance of a view model to bind.

- (void)bindViewModelInstance:(RiveDataBindingViewModelInstance*)instance
    NS_SWIFT_NAME(bind(viewModelInstance:));

Example Usage

// Get state machine from artboard
NSError* error = nil;
RiveStateMachineInstance* stateMachine = [artboard stateMachineFromName:@"State Machine 1" error:&error];

if (error) {
    NSLog(@"Failed to get state machine: %@", error);
    return;
}

// Get and set inputs
const RiveSMIBool* hoverInput = [stateMachine getBool:@"Hover"];
const RiveSMITrigger* clickInput = [stateMachine getTrigger:@"Click"];
const RiveSMINumber* progressInput = [stateMachine getNumber:@"Progress"];

// Set input values
[hoverInput setValue:YES];
[clickInput fire];
[progressInput setValue:0.75];

// Advance state machine in render loop
- (void)tick:(double)deltaTime {
    [stateMachine advanceBy:deltaTime];
    [artboard advanceBy:deltaTime];
    
    // Check for state changes
    NSInteger stateChanges = [stateMachine stateChangedCount];
    for (NSInteger i = 0; i < stateChanges; i++) {
        RiveLayerState* state = [stateMachine stateChangedFromIndex:i error:nil];
        NSLog(@"State changed: %@", [state name]);
    }
    
    // Check for events
    NSInteger eventCount = [stateMachine reportedEventCount];
    for (NSInteger i = 0; i < eventCount; i++) {
        const RiveEvent* event = [stateMachine reportedEventAt:i];
        NSLog(@"Event reported: %@", [event name]);
    }
}

// Handle touch events
- (void)touchesBegan:(NSSet<UITouch*>*)touches withEvent:(UIEvent*)event {
    UITouch* touch = [touches anyObject];
    CGPoint location = [touch locationInView:self.view];
    
    // Convert to artboard coordinates
    CGPoint artboardLocation = [self convertToArtboardSpace:location];
    
    RiveHitResult result = [stateMachine touchBeganAtLocation:artboardLocation];
    if (result == hitOpaque) {
        NSLog(@"Hit opaque area");
    }
}

High-Level API

Core Classes

State Machine Inputs

Data Binding

Supporting Types

​Overview

​Properties

​State Machine Information

​name

​Playback Control

​advanceBy:

​Input Management

​getBool:

​getTrigger:

​getNumber:

​inputNames

​inputCount

​inputFromIndex:error:

​inputFromName:error:

​Layer and State Management

​layerCount

​stateChangedCount

​stateChangedFromIndex:error:

​stateChanges

​Event Handling

​reportedEventCount

​reportedEventAt:

​Touch Interaction

​RiveHitResult Enum

​touchBeganAtLocation:

​touchBeganAtLocation:touchID:

​touchMovedAtLocation:

​touchMovedAtLocation:touchID:

​touchEndedAtLocation:

​touchEndedAtLocation:touchID:

​touchCancelledAtLocation:

​touchCancelledAtLocation:touchID:

​touchExitedAtLocation:

​touchExitedAtLocation:touchID:

​Data Binding

​bindViewModelInstance:

​Example Usage

Build docs developers (and LLMs) love

Overview

Properties

State Machine Information

name

Playback Control

advanceBy:

Input Management

getBool:

getTrigger:

getNumber:

inputNames

inputCount

inputFromIndex:error:

inputFromName:error:

Layer and State Management

layerCount

stateChangedCount

stateChangedFromIndex:error:

stateChanges

Event Handling

reportedEventCount

reportedEventAt:

Touch Interaction

RiveHitResult Enum

touchBeganAtLocation:

touchBeganAtLocation:touchID:

touchMovedAtLocation:

touchMovedAtLocation:touchID:

touchEndedAtLocation:

touchEndedAtLocation:touchID:

touchCancelledAtLocation:

touchCancelledAtLocation:touchID:

touchExitedAtLocation:

touchExitedAtLocation:touchID:

Data Binding

bindViewModelInstance:

Example Usage