titan_animation.js

import { Pose } from "./pose.js";
import { ResourceReferenceError } from "../core/scene.js";

/**
 * Animation represents a sequence of poses (keyframes) over time.
 * @class Animation
 */
export class Animation {
    /**
     * @param {string} name - Animation name (e.g., "walk", "idle", "attack").
     * @param {boolean} loop - Whether animation loops.
     */
    constructor(name = "animation", loop = true) {
        this.name = name;
        this.loop = loop;
        this.keyframes = []; // Array of { time: number, pose: Pose }
        this.duration = 0;
    }

    /**
     * Add a keyframe to the animation.
     * @param {number} time - Time in seconds for this keyframe.
     * @param {Pose} pose - The pose at this keyframe.
     * @returns {Animation} This animation (for chaining).
     */
    addKeyframe(time, pose) {
        if (!Number.isFinite(time) || time < 0) {
            throw new ResourceReferenceError("animation", this.name, "animation.keyframes[].time", "keyframe time must be a non-negative number", "a valid animation keyframe time");
        }
        if (!(pose instanceof Pose)) {
            throw new ResourceReferenceError("animation", this.name, "animation.keyframes[].pose", "keyframe pose is incompatible", "a Pose instance");
        }
        this.keyframes.push({ time, pose });
        this.keyframes.sort((a, b) => a.time - b.time);
        this.duration = Math.max(this.duration, time);
        return this;
    }

    /**
     * Get the interpolated pose at a given time.
     * @param {number} time - Time in seconds.
     * @returns {Pose} Interpolated pose.
     */
    getPoseAtTime(time) {
        if (this.keyframes.length === 0) {
            return new Pose();
        }

        if (this.keyframes.length === 1) {
            return this.keyframes[0].pose;
        }

        // Handle looping
        if (this.loop && this.duration > 0) {
            time = time % this.duration;
        } else {
            time = Math.min(time, this.duration);
        }

        // Find the two keyframes to interpolate between
        let prevKeyframe = this.keyframes[0];
        let nextKeyframe = this.keyframes[this.keyframes.length - 1];

        for (let i = 0; i < this.keyframes.length - 1; i++) {
            if (time >= this.keyframes[i].time && time < this.keyframes[i + 1].time) {
                prevKeyframe = this.keyframes[i];
                nextKeyframe = this.keyframes[i + 1];
                break;
            }
        }

        // Calculate interpolation factor
        const timeDiff = nextKeyframe.time - prevKeyframe.time;
        const t = timeDiff > 0 ? (time - prevKeyframe.time) / timeDiff : 0;

        return Pose.Lerp(prevKeyframe.pose, nextKeyframe.pose, t);
    }

    /**
     * Create an Animation from JSON data.
     * @param {Object} data - JSON animation data.
     * @returns {Animation}
     * @example
     * Animation.fromJSON({
     *   name: "walk",
     *   loop: true,
     *   frames: [
     *     { time: 0, limbs: { "LegL": { rotation: -0.3 } } },
     *     { time: 0.25, limbs: { "LegL": { rotation: 0.3 } } }
     *   ]
     * });
     */
    static fromJSON(data) {
        Animation.#validateJSON(data);
        const anim = new Animation(data.name, data.loop ?? true);

        if (data.frames) {
            for (const frame of data.frames) {
                const pose = new Pose(frame.limbs || {});
                anim.addKeyframe(frame.time, pose);
            }
        }

        return anim;
    }

    static #validateJSON(data) {
        if (!data || typeof data !== "object" || Array.isArray(data)) {
            throw new ResourceReferenceError("animation", data, "animation", "animation data must be an object", "an animation object");
        }
        if (typeof data.name !== "string" || !data.name.trim()) {
            throw new ResourceReferenceError("animation", data.name, "animation.name", "animation name is missing or empty", "a non-empty animation name");
        }
        if (data.loop !== undefined && typeof data.loop !== "boolean") {
            throw new ResourceReferenceError("animation", data.loop, "animation.loop", "loop must be boolean", "a boolean loop value");
        }
        if (data.frames === undefined) return;
        if (!Array.isArray(data.frames)) {
            throw new ResourceReferenceError("animation", data.frames, "animation.frames", "frames must be an array", "an animation frame array");
        }
        data.frames.forEach((frame, index) => {
            const location = `animation.frames[${index}]`;
            if (!frame || typeof frame !== "object" || Array.isArray(frame)) {
                throw new ResourceReferenceError("animation", frame, location, "frame must be an object", "a frame with time and limbs");
            }
            if (!Number.isFinite(frame.time) || frame.time < 0) {
                throw new ResourceReferenceError("animation", frame.time, `${location}.time`, "frame time must be a non-negative number", "a valid frame time");
            }
            if (frame.limbs !== undefined &&
                (!frame.limbs || typeof frame.limbs !== "object" || Array.isArray(frame.limbs))) {
                throw new ResourceReferenceError("animation", frame.limbs, `${location}.limbs`, "limbs must be an object", "a limb pose object");
            }
            for (const [limbName, limb] of Object.entries(frame.limbs || {})) {
                if (!limb || typeof limb !== "object" || Array.isArray(limb)) {
                    throw new ResourceReferenceError("animation", limb, `${location}.limbs.${limbName}`, "limb pose must be an object", "a limb transform object");
                }
            }
        });
    }
}