Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

19.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    SpriteAnimator.ts
 * @brief   Sprite frame animation component and system (pure TypeScript)
 */

import { defineComponent, type ComponentDef } from '../ecs/component';
import { defineResource } from '../ecs/resource';
import { getDefaultContext } from '../ecs/context';
import type { Entity, TextureHandle } from '../types';
import type { World } from '../ecs/world';
import { Sprite, type SpriteData } from '../ecs/component';

// =============================================================================
// Sprite Animation Clip
// =============================================================================

export interface SpriteAnimFrame {
    texture: TextureHandle;
    duration?: number;
    uvOffset?: { x: number; y: number };
    uvScale?: { x: number; y: number };
    /**
     * The anchor this frame renders with, in `Sprite.pivot`'s own space — resolved
     * at load time from the clip's per-frame/clip-wide anchors. Absent on EVERY
     * frame of a clip that authors no anchors, which is what keeps playback from
     * touching a pivot the entity owns.
     */
    pivot?: { x: number; y: number };
    /**
     * The size this frame renders at, in world units — resolved at load time from
     * the clip's sizing mode and the frame's natural size. Absent on EVERY frame of
     * a clip that does not own size, which is what keeps playback from resizing a
     * sprite the entity sized itself.
     */
    size?: { x: number; y: number };
}

export interface SpriteAnimEvent {
    frame: number;
    name: string;
    data?: unknown;
}

export type SpriteAnimEventHandler = (event: SpriteAnimEvent, entity: Entity) => void;

export interface SpriteAnimClip {
    name: string;
    frames: SpriteAnimFrame[];
    fps: number;
    loop: boolean;
    labels?: Record<string, number>;
    events?: SpriteAnimEvent[];
}

function frameDurationOf(clip: SpriteAnimClip, index: number, speed: number, fallback: number): number {
    const duration = clip.frames[index]?.duration;
    return Math.max(Number.MIN_VALUE, (duration !== undefined && Number.isFinite(duration) && duration > 0 ? duration : fallback) / speed);
}

export function shouldFireEvent(eventFrame: number, prevFrame: number, newFrame: number, totalFrames: number, loop: boolean): boolean {
    // Frame-0 initial apply only. Without the `=== 0`, the completion clamp
    // (currentFrame overflows → clamped to last, so prev === new === last) re-fires
    // the last frame's event a second time.
    if (prevFrame === newFrame && eventFrame === newFrame && newFrame === 0) return true;
    if (newFrame > prevFrame) {
        return eventFrame > prevFrame && eventFrame <= newFrame;
    }
    if (loop && newFrame < prevFrame) {
        return eventFrame > prevFrame || eventFrame <= newFrame;
    }
    return false;
}

// =============================================================================
// SpriteAnimation — per-App clip registry + frame-event listeners + system
// =============================================================================

/**
 * Owns one App's sprite-animation clip registry and frame-event listeners,
 * advances SpriteAnimator components, and drives goto-frame/label. Published as
 * the {@link SpriteAnimation} resource; read it as
 * `app.getResource(SpriteAnimation)`.
 */
export class SpriteAnimationAPI {
    private readonly clips = new Map<string, SpriteAnimClip>();
    private assetClips_: ((ref: string) => SpriteAnimClip | undefined) | null = null;
    private readonly entityListeners = new Map<Entity, SpriteAnimEventHandler[]>();
    private globalListeners: SpriteAnimEventHandler[] = [];
    // Remember the applied source without retaining an unloaded clip's frames.
    private readonly clipTokens = new WeakMap<SpriteAnimClip, object>();
    private readonly appliedAnimators = new WeakMap<SpriteAnimatorData, object>();
    private readonly pendingApplies = new WeakSet<SpriteAnimatorData>();
    private updating = false;

    // -- clip registry --------------------------------------------------------

    registerClip(clip: SpriteAnimClip): void {
        this.clips.set(clip.name, clip);
    }

    /**
     * Register an EXISTING clip object under an additional lookup name. Loaders
     * register a clip under its resolved load path, which in some realms is an
     * absolute URL — components reference the serialized project-relative ref,
     * so the two must alias to the SAME object (events attached through one
     * name fire for the other).
     */
    aliasClip(name: string, clip: SpriteAnimClip): void {
        this.clips.set(name, clip);
    }

    unregisterClip(name: string): void {
        this.clips.delete(name);
    }

    /**
     * @internal Where a clip loaded from a `.esanim` comes from: this app's
     * realm. A code registration wins, as it always did — what changes is that
     * the asset half is no longer a second copy kept in the map above.
     */
    useAssetClips(source: (ref: string) => SpriteAnimClip | undefined): void {
        this.assetClips_ = source;
    }

    getClip(name: string): SpriteAnimClip | undefined {
        return this.clips.get(name) ?? this.assetClips_?.(name);
    }

    clearClips(): void {
        this.clips.clear();
    }

    // -- frame-event listeners ------------------------------------------------

    onEvent(entity: Entity, handler: SpriteAnimEventHandler): () => void {
        this.entityListeners.set(entity, [...(this.entityListeners.get(entity) ?? []), handler]);
        return () => {
            const arr = this.entityListeners.get(entity);
            if (arr) {
                const idx = arr.indexOf(handler);
                if (idx < 0) return;
                if (arr.length === 1) this.entityListeners.delete(entity);
                else this.entityListeners.set(entity, [...arr.slice(0, idx), ...arr.slice(idx + 1)]);
            }
        };
    }

    onEventGlobal(handler: SpriteAnimEventHandler): () => void {
        this.globalListeners = [...this.globalListeners, handler];
        return () => {
            const idx = this.globalListeners.indexOf(handler);
            if (idx >= 0) this.globalListeners = [...this.globalListeners.slice(0, idx), ...this.globalListeners.slice(idx + 1)];
        };
    }

    removeEntityListeners(entity: Entity): void {
        this.entityListeners.delete(entity);
    }

    private isCurrentAnimator(world: World, entity: Entity, animator: SpriteAnimatorData, clipName: string, clip: SpriteAnimClip, frames: SpriteAnimFrame[], frameCount: number): boolean {
        if (!world.isEntityActive(entity) || !animator.enabled) {
            this.pendingApplies.add(animator);
            return false;
        }
        if (world.tryGet(entity, SpriteAnimator) !== animator
            || animator.clip !== clipName || this.getClip(clipName) !== clip
            || this.pendingApplies.has(animator)) return false;
        if (clip.frames !== frames || frames.length !== frameCount
            || !Number.isInteger(animator.currentFrame) || animator.currentFrame < 0 || animator.currentFrame >= frameCount) {
            this.appliedAnimators.delete(animator);
            return false;
        }
        return true;
    }

    private fireEvents(world: World, entity: Entity, animator: SpriteAnimatorData, clipName: string, clip: SpriteAnimClip, prevFrame: number, advanced: number, initial: boolean, looping: boolean): boolean {
        if (!clip.events || clip.events.length === 0) return true;
        if (!this.entityListeners.get(entity)?.length && !this.globalListeners.length) return true;
        const frames = clip.frames;
        const frameCount = frames.length;
        let first: SpriteAnimEvent | undefined;
        let firstDistance = 0;
        let ordered: { event: SpriteAnimEvent; distance: number }[] | undefined;
        for (const evt of clip.events) {
            if (!Number.isInteger(evt.frame) || evt.frame < 0 || evt.frame >= clip.frames.length) continue;
            const offset = evt.frame - prevFrame;
            const distance = initial && offset === 0 ? 0
                : looping ? ((offset + clip.frames.length) % clip.frames.length || clip.frames.length) : offset;
            if (!(distance === 0 && initial) && !(distance > 0 && distance <= advanced)) continue;
            if (!first) { first = evt; firstDistance = distance; }
            else {
                ordered ??= [{ event: first, distance: firstDistance }];
                ordered.push({ event: evt, distance });
            }
        }
        // Most updates cross one event: avoid an allocation on that hot path.
        // Long updates coalesce each declared event once, in playback order.
        if (ordered) ordered.sort((a, b) => a.distance - b.distance);
        const count = ordered?.length ?? (first ? 1 : 0);
        for (let i = 0; i < count; i++) {
            const evt = ordered ? ordered[i].event : first!;
            const listeners = this.entityListeners.get(entity);
            // Registration uses copy-on-write: these event snapshots stay
            // stable without allocating listener arrays on every frame.
            const globals = this.globalListeners;
            if (listeners) {
                for (const handler of listeners) {
                    handler(evt, entity);
                    if (!this.isCurrentAnimator(world, entity, animator, clipName, clip, frames, frameCount)) return false;
                }
            }
            for (const handler of globals) {
                handler(evt, entity);
                if (!this.isCurrentAnimator(world, entity, animator, clipName, clip, frames, frameCount)) return false;
            }
        }
        return true;
    }

    // -- per-frame system -----------------------------------------------------

    update(world: World, deltaTime: number): void {
        // A frame callback may control playback, but cannot recursively advance
        // this API's current animation pass. Always release the guard on error.
        if (this.updating) return;
        this.updating = true;
        try { this.updateWorld(world, deltaTime); }
        finally { this.updating = false; }
    }

    private updateWorld(world: World, deltaTime: number): void {
        const entities = world.getEntitiesWithComponents([SpriteAnimator]);
        if (entities.length === 0) return;
        const registry = world.getCppRegistry(), module = world.getWasmModule();
        const readSprite = world.resolveGetter(Sprite), writeSprite = world.resolveSetter(Sprite);

        for (const entity of entities) {
            // An earlier entity's event can remove a later entity/component
            // from the query snapshot we are currently walking.
            if (!world.isEntityActive(entity)) continue;
            const animator = world.tryGet(entity, SpriteAnimator);
            if (!animator) continue;
            if (!animator.enabled || !animator.clip) continue;
            const applied = this.appliedAnimators.get(animator);
            if (!animator.playing && !this.pendingApplies.has(animator) && !applied) continue;

            const clipName = animator.clip;
            const clip = this.getClip(clipName);
            if (!clip || clip.frames.length === 0) continue;

            // playing raised on a finished one-shot = replay from the top
            // (TimelinePlayer's flag contract).
            if (animator.finished && animator.playing) {
                animator.finished = false;
                animator.currentFrame = 0;
                animator.frameTimer = 0;
                this.appliedAnimators.delete(animator);
            }

            let token = this.clipTokens.get(clip);
            if (!token) { token = {}; this.clipTokens.set(clip, token); }
            const needsInitialApply = this.appliedAnimators.get(animator) !== token;
            if (!animator.playing && !this.pendingApplies.has(animator) && !needsInitialApply) continue;
            // Speed scales EVERY frame's duration (not just the fps fallback), and
            // is guarded: 0/negative would otherwise freeze (Infinity) or run the
            // timer backward.
            const speed = Number.isFinite(animator.speed) ? Math.max(animator.speed, 1e-4) : 1;
            const fallback = 1 / (Number.isFinite(clip.fps) && clip.fps > 0 ? clip.fps : 12);
            animator.currentFrame = Number.isFinite(animator.currentFrame)
                ? Math.max(0, Math.min(Math.floor(animator.currentFrame), clip.frames.length - 1)) : 0;
            const prevFrame = animator.currentFrame;
            const wasPlaying = animator.playing;
            const looping = animator.loop && clip.loop;
            const elapsed = wasPlaying && Number.isFinite(deltaTime) ? Math.max(0, deltaTime) : 0;
            animator.frameTimer = Math.min(Number.MAX_VALUE,
                (Number.isFinite(animator.frameTimer) ? Math.max(0, animator.frameTimer) : 0) + elapsed);

            let frameChanged = needsInitialApply || this.pendingApplies.has(animator);
            // Accumulate one cycle while walking it, then skip whole extra cycles
            // in constant time. At most two cycles are inspected, with no backlog.
            let steps = 0;
            let advanced = 0;
            let cycleDuration = 0;
            while (animator.playing && steps < clip.frames.length * 2) {
                if (looping && steps === clip.frames.length) animator.frameTimer %= cycleDuration;
                const frameDuration = frameDurationOf(clip, animator.currentFrame, speed, fallback);
                if (animator.frameTimer < frameDuration) break;
                animator.frameTimer -= frameDuration;
                if (steps < clip.frames.length) cycleDuration += frameDuration;
                steps++;
                animator.currentFrame++;
                if (animator.currentFrame >= clip.frames.length) {
                    if (looping) {
                        animator.currentFrame = 0;
                        advanced++;
                    } else {
                        animator.currentFrame = clip.frames.length - 1;
                        animator.playing = false;
                        animator.finished = true;
                        animator.frameTimer = 0;
                    }
                } else advanced++;
                frameChanged = true;
            }

            this.pendingApplies.delete(animator);
            if (needsInitialApply) this.appliedAnimators.set(animator, token);
            if (frameChanged) {
                if (!this.fireEvents(world, entity, animator, clipName, clip, prevFrame, advanced, needsInitialApply && wasPlaying, looping)) continue;
            }

            if (frameChanged && world.has(entity, Sprite)) {
                const frame = clip.frames[animator.currentFrame];
                // Borrow only after event callbacks. Speculation and editor
                // observers use the full mutation seam; a rebound world cannot
                // use accessors resolved against its previous registry.
                const direct = readSprite && writeSprite && !world.speculating && !getDefaultContext().editorBridge
                    && registry === world.getCppRegistry() && module === world.getWasmModule();
                const sprite = (direct ? readSprite(entity) : world.get(entity, Sprite)) as SpriteData;
                sprite.texture = frame.texture;
                // Copy (don't alias the clip's frame objects), and RESET to the full
                // texture when a frame carries no sub-rect — else a plain frame after
                // a sheet-cell frame renders through the stale cell window.
                if (frame.uvOffset) {
                    sprite.uvOffset = { x: frame.uvOffset.x, y: frame.uvOffset.y };
                    sprite.uvScale = frame.uvScale ? { x: frame.uvScale.x, y: frame.uvScale.y } : { x: 1, y: 1 };
                } else {
                    sprite.uvOffset = { x: 0, y: 0 };
                    sprite.uvScale = { x: 1, y: 1 };
                }
                // No reset branch on either: the loader gives EVERY frame of an
                // owning clip both, so absent here means the clip owns neither and
                // what the entity authored stands.
                if (frame.size) {
                    sprite.size = { x: frame.size.x, y: frame.size.y };
                }
                if (frame.pivot) {
                    sprite.pivot = { x: frame.pivot.x, y: frame.pivot.y };
                }
                if (direct) {
                    writeSprite(entity, sprite);
                    world.markChanged(entity, Sprite);
                } else world.set(entity, Sprite, sprite);
            }

            if (frameChanged) {
                // These are complete existing values: stamp their changes without
                // rebuilding defaults or allocating a replacement component.
                world.set(entity, SpriteAnimator, animator);
                this.appliedAnimators.set(animator, token);
            }
        }
    }

    // -- goto frame / label ---------------------------------------------------

    gotoFrame(animator: SpriteAnimatorData, frameIndex: number, andPlay: boolean = true): void {
        const clip = this.getClip(animator.clip);
        if (!clip || clip.frames.length === 0) return;

        animator.currentFrame = Math.max(0, Math.min(frameIndex, clip.frames.length - 1));
        animator.frameTimer = 0;
        animator.playing = andPlay;
        animator.finished = false;
        this.appliedAnimators.delete(animator);
        this.pendingApplies.add(animator);
    }

    gotoLabel(animator: SpriteAnimatorData, label: string, andPlay: boolean = true): void {
        const clip = this.getClip(animator.clip);
        if (!clip || !clip.labels) return;

        const frameIndex = clip.labels[label];
        if (frameIndex === undefined) return;

        this.gotoFrame(animator, frameIndex, andPlay);
    }
}

/**
 * Per-App sprite-animation resource (clip registry + frame-event listeners),
 * published by `AnimationPlugin`. Read as `app.getResource(SpriteAnimation)`.
 */
export const SpriteAnimation = defineResource<SpriteAnimationAPI>(null!, 'SpriteAnimation');

// =============================================================================
// SpriteAnimator Component
// =============================================================================

/** The fields of the `SpriteAnimator` component, whose tier this shape carries.
 *  @beta */
export interface SpriteAnimatorData {
    clip: string;
    speed: number;
    playing: boolean;
    loop: boolean;
    enabled: boolean;
    currentFrame: number;
    frameTimer: number;
    /** Latched when a one-shot clip completes; runtime-only, do not author.
     *  Raising `playing` on a finished animator replays from frame 0 — the
     *  same flag contract as TimelinePlayer. */
    finished: boolean;
}

/**
 * Frame playback on an entity: which clip, how fast, and where in it. The clip is
 * named rather than referenced, so a project registers clips from code or ships
 * them as `.esanim` and this stays the same either way.
 *
 * @beta
 */
export const SpriteAnimator: ComponentDef<SpriteAnimatorData> = defineComponent('SpriteAnimator', {
    clip: '',
    speed: 1.0,
    playing: true,
    loop: true,
    enabled: true,
    currentFrame: 0,
    frameTimer: 0,
    finished: false,
}, {
    assetFields: [{ field: 'clip', type: 'anim-clip' }],
});