animouse/dist/states/AnimationTree.d.ts

lightweight animation state machine for three js

import type { Callback } from "eventail";
import type { AnimationAction } from "three";
import type { Anchor } from "../mescellaneous/miscellaneous";
import { AnimationState } from "./AnimationState";
/**
 * Abstract base class for animation trees in the animation state machine.
 * Provides foundation for different tree types (linear, polar, freeform, etc.)
 * and manages animation anchors with their weights.
 *
 * Animation trees organize and control multiple animation actions through
 * a hierarchical structure, automatically managing playback and weight distribution.
 */
export declare abstract class AnimationTree extends AnimationState {
    /**
     * Map linking animation actions to their corresponding anchors.
     * Used to look up anchor information when registering time-based events.
     */
    protected readonly actionToAnchor: Map<AnimationAction, Anchor>;
    /**
     * Registers a callback to be called when the specified animation action reaches a specific time.
     * The callback will be invoked every time the animation crosses the specified time threshold.
     *
     * @param action - The animation action to monitor for time events
     * @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
     * @throws {Error} When the action is not registered in this animation tree
     */
    onTimeEvent(action: AnimationAction, unitTime: number, callback: Callback): void;
    /**
     * Registers a callback to be called once when the specified animation action reaches a specific time.
     * The callback will be invoked only the first time the animation crosses the specified time threshold.
     *
     * @param action - The animation action to monitor for time events
     * @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
     * @throws {Error} When the action is not registered in this animation tree
     */
    onceTimeEvent(action: AnimationAction, unitTime: number, callback: Callback): void;
    /**
     * Removes a previously registered time event callback for the specified animation action.
     * Unregisters the callback from the specified time point and cleans up associated resources.
     *
     * @param action - The animation action to remove the time event from
     * @param unitTime - Time in unit range [0, 1] where the callback was registered
     * @param callback - The callback function to remove
     * @throws {Error} When the action is not registered in this animation tree
     */
    offTimeEvent(action: AnimationAction, unitTime: number, callback: Callback): void;
    /**
     * Updates the weight of a specific animation anchor (AnimationAction + parameters).
     * Handles animation playbook lifecycle: starting, stopping, and weight adjustments.
     * Combines the raw weight with the tree's influence to get the final action weight.
     *
     * When transitioning from zero to non-zero weight: starts playback, resets time to 0,
     * resets event tracking state, and emits PLAY event.
     * When transitioning from non-zero to zero weight: stops playback, resets time to 0,
     * resets event tracking state, and emits STOP event.
     * For weight-only changes: updates the animation action weight without lifecycle changes.
     *
     * @param anchor - The animation anchor containing the action and parameters to update
     * @param weight - The raw weight value before applying tree influence (finite number). If not provided, uses the anchor's current weight
     * @throws {Error} When weight is not a finite number or is outside the range [0, 1]
     * @see {@link AnimationStateEvent.PLAY} for play event details
     * @see {@link AnimationStateEvent.STOP} for stop event details
     */
    protected updateAnchorWeight(anchor: Anchor, weight?: number): void;
    /**
     * Abstract method to update influence for all anchors in the animation tree.
     * Called when the tree's influence changes but relative weights remain the same.
     * Concrete implementations should apply the new influence to all anchors
     * while maintaining their existing relative weight distribution.
     *
     * This method is called automatically when the tree's influence changes.
     */
    protected abstract updateAnchorsInfluence(): void;
}