titan_animator.js

import { Component } from "../components/component.js";
import { Rig } from "./rig.js";

/**
 * Animator component plays animations on a Rig.
 * Handles animation playback, transitions, and timing.
 * @class Animator
 * @extends Component
 */
export class Animator extends Component {
    constructor() {
        super();
        this.animations = {}; // { name: Animation }
        this.currentAnimation = null;
        this.currentTime = 0;
        this.speed = 1.0;
        this.playing = false;
        this._rig = null;
        this._gameplayEventUnsubscribers = [];
    }

    /**
     * Bind gameplay events to animation names. The event source must expose
     * on(eventName, listener), returning an unsubscribe function (or provide
     * off(eventName, listener)). Mapping values may be animation names or
     * functions that return an animation name for the event payload.
     * Existing bindings are replaced when this method is called again.
     * @param {Object} eventSource - Event emitter with on(event, listener).
     * @param {Object<string, string|Function>} eventMap - Event-to-animation mapping.
     * @returns {Animator} This animator (for chaining).
     */
    bindGameplayEvents(eventSource, eventMap) {
        if (!eventSource || typeof eventSource.on !== "function") {
            throw new TypeError("Animator.bindGameplayEvents requires an event source with on(event, listener)");
        }
        if (!eventMap || typeof eventMap !== "object" || Array.isArray(eventMap)) {
            throw new TypeError("Animator.bindGameplayEvents requires an event mapping object");
        }
        this.unbindGameplayEvents();
        for (const [eventName, resolveAnimation] of Object.entries(eventMap)) {
            if (typeof resolveAnimation !== "string" && typeof resolveAnimation !== "function") {
                throw new TypeError(`Animation mapping for event \\"${eventName}\\" must be a name or function`);
            }
            const listener = (event) => {
                const animationName = typeof resolveAnimation === "function"
                    ? resolveAnimation(event)
                    : resolveAnimation;
                if (typeof animationName === "string" && animationName) this.play(animationName);
            };
            const unsubscribe = eventSource.on(eventName, listener);
            this._gameplayEventUnsubscribers.push(typeof unsubscribe === "function"
                ? unsubscribe
                : () => eventSource.off?.(eventName, listener));
        }
        return this;
    }

    /** Remove all gameplay event bindings. */
    unbindGameplayEvents() {
        for (const unsubscribe of this._gameplayEventUnsubscribers) unsubscribe();
        this._gameplayEventUnsubscribers = [];
        return this;
    }

    /**
     * Add an animation to the animator.
     * @param {Animation} animation - The animation to add.
     * @returns {Animator} This animator (for chaining).
     */
    addAnimation(animation) {
        this.animations[animation.name] = animation;
        return this;
    }

    /**
     * Get an animation by name.
     * @param {string} name - Animation name.
     * @returns {Animation|null}
     */
    getAnimation(name) {
        return this.animations[name] || null;
    }

    /**
     * Play an animation by name.
     * @param {string} name - Animation name.
     * @param {boolean} restart - Whether to restart if already playing this animation.
     */
    play(name, restart = false) {
        const anim = this.getAnimation(name);
        if (!anim) {
            console.warn(`Animation "${name}" not found`);
            return;
        }

        if (this.currentAnimation === anim && !restart) {
            this.playing = true;
            return;
        }

        this.currentAnimation = anim;
        this.currentTime = 0;
        this.playing = true;
    }

    /**
     * Stop the current animation.
     */
    stop() {
        this.playing = false;
    }

    /**
     * Pause the current animation.
     */
    pause() {
        this.playing = false;
    }

    /**
     * Resume a paused animation.
     */
    resume() {
        this.playing = true;
    }

    /**
     * Update the animator. Should be called each frame.
     * @param {number} deltaTime - Time since last frame in seconds.
     */
    update(deltaTime) {
        if (!this.playing || !this.currentAnimation) return;

        // Get rig if not cached
        if (!this._rig && this.entity) {
            this._rig = this.entity.GetComponent(Rig);
        }

        if (!this._rig) return;

        // Advance time
        this.currentTime += deltaTime * this.speed;

        // Get pose at current time
        const pose = this.currentAnimation.getPoseAtTime(this.currentTime);

        // Apply pose to rig
        this._rig.applyPose(pose);

        // Check if animation ended (non-looping)
        if (!this.currentAnimation.loop && this.currentTime >= this.currentAnimation.duration) {
            this.playing = false;
        }
    }

    /**
     * Check if currently playing a specific animation.
     * @param {string} name - Animation name.
     * @returns {boolean}
     */
    isPlaying(name) {
        return this.playing && this.currentAnimation && this.currentAnimation.name === name;
    }
}