animouse/dist/AnimationMachine.d.ts

lightweight animation state machine for three js

import type { AnimationMixer } from "three";
import type { AnimationState } from "./states/AnimationState";
/**
 * Condition function for event-triggered transitions.
 * Determines whether a transition should occur based on event context.
 *
 * @param from - Source state (undefined if transition can occur from any state)
 * @param to - Target state for the transition
 * @param event - Event name or identifier that triggered the evaluation
 * @param args - Additional arguments passed with the event
 * @returns True if the transition should occur, false otherwise
 */
type EventCondition = (from: AnimationState | undefined, to: AnimationState, event: string | number, ...args: any[]) => boolean;
/**
 * Condition function for data-driven transitions.
 * Evaluated continuously to determine if automatic transitions should occur.
 *
 * @param from - Source state where the transition originates
 * @param to - Target state for the transition
 * @param args - Additional data arguments for condition evaluation
 * @returns True if the transition should occur, false otherwise
 */
type DataCondition = (from: AnimationState, to: AnimationState, ...args: any[]) => boolean;
/**
 * Configuration for event-triggered transitions between animation states.
 * These transitions occur when specific events are handled by the state machine.
 */
export interface EventTransition {
    /** Optional source state. If not specified, transition can occur from any state */
    from?: AnimationState;
    /** Target state to transition to */
    to: AnimationState;
    /** Duration of the transition in seconds (finite non-negative number) */
    duration: number;
    /** Optional condition that must be met for the transition to occur */
    condition?: EventCondition;
}
/**
 * Configuration for automatic transitions that occur at animation completion.
 * These transitions are triggered when ITERATE or FINISH events are emitted.
 */
export interface AutomaticTransition {
    /** Target state to transition to */
    to: AnimationState;
    /** Duration of the transition in seconds (finite non-negative number) */
    duration: number;
}
/**
 * Configuration for data-driven transitions evaluated continuously each update.
 * These transitions occur when their condition functions return true.
 */
export interface DataTransition {
    /** Target state to transition to */
    to: AnimationState;
    /** Duration of the transition in seconds (finite non-negative number) */
    duration: number;
    /** Optional data arguments to be passed to the condition function */
    data?: any[];
    /** Condition function that determines if the transition should occur */
    condition: DataCondition;
}
/**
 * Animation state machine for managing state transitions and blending.
 *
 * Controls animation states with support for:
 * - **Event-based transitions**: Triggered by specific events with optional conditions
 * - **Automatic transitions**: Triggered when animations complete (ITERATE/FINISH events)
 * - **Data-driven transitions**: Evaluated continuously based on condition functions
 *
 * Handles blending between states using configurable transition durations.
 * Multiple states can be active during transitions, with weights interpolated linearly.
 */
export declare class AnimationMachine {
    /** Internal storage for the currently active animation state */
    private currentStateInternal;
    /** States that are currently fading out during transitions */
    private fadingStates;
    /** The THREE.js animation mixer used for updating animations */
    private readonly mixer;
    /** Map of event names to their possible transitions */
    private readonly eventTransitions;
    /** Map of states to their automatic transitions that occur at animation end */
    private readonly automaticTransitions;
    /** Map of states to their data-driven transitions */
    private readonly dataTransitions;
    /** Time remaining in the current transition */
    private transitionElapsedTime?;
    /**
     * Creates a new animation state machine with the specified initial state.
     * Activates the initial state with full influence.
     *
     * @param initialState - The starting animation state to activate
     * @param mixer - The THREE.js animation mixer for updating animations
     */
    constructor(initialState: AnimationState, mixer: AnimationMixer);
    /**
     * Gets the currently active animation state.
     * During transitions, this returns the state being transitioned to.
     *
     * @returns The current active animation state
     */
    get currentState(): AnimationState;
    /**
     * Adds an event-triggered transition to the state machine.
     * Multiple transitions can be registered for the same event with different source states.
     * When an event is handled, the first matching transition is executed.
     *
     * @param event - The event name or identifier that triggers this transition
     * @param transition - The transition configuration with target state and duration
     * @throws {Error} When transition duration is not a finite non-negative number
     * @throws {Error} When transition creates a recursive loop (from === to)
     * @throws {Error} When transition already exists for the same event and source state
     */
    addEventTransition(event: string | number, transition: EventTransition): void;
    /**
     * Adds an automatic transition that occurs when an animation completes.
     * Listens for ITERATE and FINISH events from the source state to trigger transitions.
     * Only one automatic transition can be registered per source state.
     *
     * @param from - The source state that will trigger the automatic transition
     * @param transition - The transition configuration with target state and duration
     * @throws {Error} When transition duration is not a finite non-negative number
     * @throws {Error} When transition creates a recursive loop (from === to)
     * @throws {Error} When an automatic transition already exists for the source state
     */
    addAutomaticTransition(from: AnimationState, transition: AutomaticTransition): void;
    /**
     * Adds a data-driven transition evaluated continuously during updates.
     * The condition function is called each frame when the source state is active.
     * Multiple data transitions can be registered per state, but only one per target.
     *
     * @param from - The source state where the transition can originate
     * @param transition - The transition configuration with condition and target state
     * @throws {Error} When transition duration is not a finite non-negative number
     * @throws {Error} When transition creates a recursive loop (from === to)
     * @throws {Error} When a data transition to the same target already exists
     */
    addDataTransition(from: AnimationState, transition: DataTransition): void;
    /**
     * Handles an event by executing the first matching transition.
     * Evaluates registered transitions for the event in registration order.
     *
     * @param event - The event name or identifier to handle
     * @param args - Additional arguments passed to transition condition functions
     * @returns True if a transition was executed, false if no matching transition found
     */
    handleEvent(event: string | number, ...args: unknown[]): boolean;
    /**
     * Updates the animation state machine and all animations for one frame.
     *
     * Updates current state and fading states, evaluates data-driven transitions,
     * progresses active transitions by interpolating state influences, and updates
     * the animation mixer.
     *
     * @param deltaTime - Time elapsed since last update in seconds
     * @throws {Error} When deltaTime is not a finite non-negative number
     */
    update(deltaTime: number): void;
    /**
     * Transitions to a new animation state over the specified duration.
     *
     * @private
     * @param {AnimationState} state - The state to transition to
     * @param {number} duration - The duration of the transition in seconds
     */
    private transitionTo;
    /**
     * Handles animation iteration events for automatic transitions.
     *
     * @private
     * @param {AnimationState} state - The state that completed an iteration
     */
    private onStateIteration;
}
export {};