animouse/dist/states/ClipState.d.ts

lightweight animation state machine for three js

import type { Callback } from "eventail";
import { type AnimationAction } from "three";
import { AnimationState } from "./AnimationState";
/**
 * Animation state that wraps a single Three.js AnimationAction.
 * Manages the lifecycle of a single animation clip, handling playback,
 * weight control, and iteration events.
 *
 * This state automatically detects animation completion and restart events,
 * emitting appropriate state events based on the animation's loop type.
 */
export declare class ClipState extends AnimationState {
    /**
     * Internal anchor that wraps the AnimationAction with additional tracking data.
     */
    private readonly anchor;
    /**
     * Creates a new ClipState from a Three.js AnimationAction.
     * Initializes the animation to a stopped state and configures iteration events
     * based on the animation's loop type. Sets up anchor with duration tracking
     * and event state management.
     *
     * @param animationAction - The Three.js AnimationAction to wrap (finite duration required)
     * @throws {Error} When the animation clip duration is not a positive finite number
     * @see {@link assertValidPositiveNumber} for duration validation details
     */
    constructor(animationAction: AnimationAction);
    /**
     * Registers a callback to be called when the animation reaches a specific time.
     * The callback will be invoked every time the animation crosses the specified time threshold.
     *
     * @param unitTime - Time in unit range [0, 1] when the callback should be invoked
     * @param callback - Function to call when the time event occurs, receives the action and state as parameters
     */
    onTimeEvent(unitTime: number, callback: Callback): void;
    /**
     * Registers a callback to be called once when the animation reaches a specific time.
     * The callback will be invoked only the first time the animation crosses the specified time threshold.
     *
     * @param unitTime - Time in unit range [0, 1] when the callback should be invoked
     * @param callback - Function to call when the time event occurs, receives the action and state as parameters
     */
    onceTimeEvent(unitTime: number, callback: Callback): void;
    /**
     * Removes a previously registered time event callback.
     * Unregisters the callback from the specified time point and cleans up associated resources.
     *
     * @param unitTime - Time in unit range [0, 1] where the callback was registered
     * @param callback - The callback function to remove
     */
    offTimeEvent(unitTime: number, callback: Callback): void;
    protected ["onEnterInternal"](): void;
}