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.

21.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
    Animator,
    AnimatorControllerAPI,
    registerAnimatorController,
    getRegisteredAnimatorController,
    clearAnimatorControllerStore,
    evaluateAnimatorTransitions,
    resolveParams,
    selectBlendClip,
    type AnimatorBlend1D,
    type AnimatorControllerDef,
    type AnimatorData,
} from '../src/animation/Animator';
import { SpriteAnimator, type SpriteAnimatorData } from '../src/animation/SpriteAnimator';
import { AnimatorControllerAssetLoader } from '../src/asset/loaders/AnimatorControllerAssetLoader';
import type { LoadContext } from '../src/asset/AssetLoader';

function heroController(): AnimatorControllerDef {
    return {
        parameters: [
            { name: 'speed', type: 'float', default: 0 },
            { name: 'grounded', type: 'bool', default: true },
            { name: 'jump', type: 'trigger' },
        ],
        initialState: 'idle',
        states: [
            { name: 'idle', clip: 'idle_clip', transitions: [
                { to: 'run', conditions: [{ param: 'speed', op: 'gt', value: 0.1 }] },
            ] },
            { name: 'run', clip: 'run_clip', speed: 1.5, loop: true, transitions: [
                { to: 'idle', conditions: [{ param: 'speed', op: 'lt', value: 0.1 }] },
            ] },
            { name: 'jump', clip: 'jump_clip', transitions: [
                { to: 'idle', conditions: [{ param: 'grounded', op: 'true' }] },
            ] },
        ],
        anyStateTransitions: [
            { to: 'jump', conditions: [{ param: 'jump', op: 'trigger' }] },
        ],
    };
}

// ---------------------------------------------------------------------------
// Pure evaluator
// ---------------------------------------------------------------------------

describe('evaluateAnimatorTransitions', () => {
    const def = heroController();

    it('fires a float-gt transition', () => {
        const r = evaluateAnimatorTransitions(def, 'idle', { speed: 5, grounded: true }, new Set());
        expect(r.next).toBe('run');
        expect(r.consumedTriggers).toEqual([]);
    });

    it('stays when no condition holds', () => {
        expect(evaluateAnimatorTransitions(def, 'idle', { speed: 0 }, new Set()).next).toBeNull();
    });

    it('fires the reverse float-lt transition', () => {
        expect(evaluateAnimatorTransitions(def, 'run', { speed: 0 }, new Set()).next).toBe('idle');
    });

    it('checks bool true/false', () => {
        expect(evaluateAnimatorTransitions(def, 'jump', { grounded: true }, new Set()).next).toBe('idle');
        expect(evaluateAnimatorTransitions(def, 'jump', { grounded: false }, new Set()).next).toBeNull();
    });

    it('any-state transition takes precedence over the current state', () => {
        // speed=5 would fire idle->run, but the any-state jump trigger wins.
        const r = evaluateAnimatorTransitions(def, 'idle', { speed: 5 }, new Set(['jump']));
        expect(r.next).toBe('jump');
        expect(r.consumedTriggers).toEqual(['jump']);
    });

    it('fires a trigger transition and reports it consumed', () => {
        const r = evaluateAnimatorTransitions(def, 'idle', { speed: 0 }, new Set(['jump']));
        expect(r.next).toBe('jump');
        expect(r.consumedTriggers).toEqual(['jump']);
    });

    it('gates hasExitTime transitions on clipFinished', () => {
        const d: AnimatorControllerDef = {
            parameters: [],
            initialState: 'attack',
            states: [
                { name: 'attack', clip: 'attack', transitions: [
                    { to: 'idle', conditions: [], hasExitTime: true },
                ] },
                { name: 'idle', clip: 'idle', transitions: [] },
            ],
        };
        // clip still playing → does not fire
        expect(evaluateAnimatorTransitions(d, 'attack', {}, new Set(), false).next).toBeNull();
        // clip finished → auto-advances
        expect(evaluateAnimatorTransitions(d, 'attack', {}, new Set(), true).next).toBe('idle');
    });

    it('eq / neq comparisons', () => {
        const d: AnimatorControllerDef = {
            parameters: [{ name: 'phase', type: 'float', default: 0 }],
            initialState: 'a',
            states: [
                { name: 'a', clip: 'a', transitions: [{ to: 'b', conditions: [{ param: 'phase', op: 'eq', value: 2 }] }] },
                { name: 'b', clip: 'b', transitions: [{ to: 'a', conditions: [{ param: 'phase', op: 'neq', value: 2 }] }] },
            ],
        };
        expect(evaluateAnimatorTransitions(d, 'a', { phase: 2 }, new Set()).next).toBe('b');
        expect(evaluateAnimatorTransitions(d, 'a', { phase: 1 }, new Set()).next).toBeNull();
        expect(evaluateAnimatorTransitions(d, 'b', { phase: 1 }, new Set()).next).toBe('a');
    });
});

describe('resolveParams', () => {
    const def = heroController();
    it('seeds declared defaults, excludes triggers', () => {
        expect(resolveParams(def, new Map())).toEqual({ speed: 0, grounded: true });
    });
    it('applies per-entity overrides', () => {
        expect(resolveParams(def, new Map<string, number | boolean>([['speed', 9]]))).toEqual({ speed: 9, grounded: true });
    });
});

// ---------------------------------------------------------------------------
// 1D blend selection (pure)
// ---------------------------------------------------------------------------

describe('selectBlendClip', () => {
    const blend: AnimatorBlend1D = {
        parameter: 'speed',
        // intentionally unordered to exercise the sort
        thresholds: [
            { value: 7, clip: 'run' },
            { value: 0, clip: 'idle' },
            { value: 3, clip: 'walk' },
        ],
    };

    it('floors to the greatest threshold <= value', () => {
        expect(selectBlendClip(blend, 0).clip).toBe('idle');
        expect(selectBlendClip(blend, 2.9).clip).toBe('idle');
        expect(selectBlendClip(blend, 3).clip).toBe('walk');
        expect(selectBlendClip(blend, 6.9).clip).toBe('walk');
        expect(selectBlendClip(blend, 7).clip).toBe('run');
        expect(selectBlendClip(blend, 100).clip).toBe('run');
    });

    it('clamps up to the first stop below all thresholds', () => {
        expect(selectBlendClip(blend, -5).clip).toBe('idle');
    });

    it('returns an empty clip for an empty blend', () => {
        expect(selectBlendClip({ parameter: 'x', thresholds: [] }, 1).clip).toBe('');
    });
});

// ---------------------------------------------------------------------------
// AnimatorControllerAPI.update drives SpriteAnimator (mock World)
// ---------------------------------------------------------------------------

function makeWorld() {
    const store = new Map<unknown, Map<number, unknown>>();
    const mapOf = (c: unknown) => {
        let m = store.get(c);
        if (!m) { m = new Map(); store.set(c, m); }
        return m;
    };
    return {
        insert(e: number, c: unknown, data: unknown) { mapOf(c).set(e, data); },
        get(e: number, c: unknown) { return mapOf(c).get(e); },
        update(e: number, c: unknown, edit: (draft: any) => void) {
            const draft = mapOf(c).get(e);
            if (draft === undefined) throw new Error('update: entity does not carry it');
            edit(draft);
            mapOf(c).set(e, draft);
        },
        has(e: number, c: unknown) { return mapOf(c).has(e); },
        getEntitiesWithComponents(comps: unknown[]) {
            const [first, ...rest] = comps;
            return [...mapOf(first).keys()].filter((e) => rest.every((c) => mapOf(c).has(e)));
        },
    } as any;
}

function spriteData(over: Partial<SpriteAnimatorData> = {}): SpriteAnimatorData {
    return { clip: '', speed: 1, playing: false, loop: true, enabled: true, currentFrame: 5, frameTimer: 0.3, ...over };
}

describe('AnimatorControllerAPI.update', () => {
    const E = 1;

    function setup() {
        const ctrl = new AnimatorControllerAPI();
        ctrl.registerController('hero', heroController());
        const world = makeWorld();
        world.insert(E, Animator, { controller: 'hero', currentState: '', enabled: true } as AnimatorData);
        world.insert(E, SpriteAnimator, spriteData());
        return { ctrl, world };
    }

    it('seeds the initial state and applies its clip on first update', () => {
        const { ctrl, world } = setup();
        ctrl.update(world);
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('idle');
        const sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;
        expect(sp.clip).toBe('idle_clip');
        expect(sp.currentFrame).toBe(0);
        expect(sp.frameTimer).toBe(0);
        expect(sp.playing).toBe(true);
    });

    it('transitions on a float parameter and switches the clip (with state speed/loop)', () => {
        const { ctrl, world } = setup();
        ctrl.update(world); // → idle
        ctrl.setFloat(E, 'speed', 5);
        ctrl.update(world); // → run
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('run');
        const sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;
        expect(sp.clip).toBe('run_clip');
        expect(sp.speed).toBe(1.5);
    });

    it('transitions back when the parameter reverses', () => {
        const { ctrl, world } = setup();
        ctrl.update(world);
        ctrl.setFloat(E, 'speed', 5); ctrl.update(world);
        ctrl.setFloat(E, 'speed', 0); ctrl.update(world);
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('idle');
    });

    it('any-state trigger jumps, consumes the trigger, then returns', () => {
        const { ctrl, world } = setup();
        ctrl.update(world); // idle
        ctrl.setTrigger(E, 'jump');
        ctrl.update(world); // → jump (trigger consumed)
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('jump');
        // grounded defaults true → next update returns to idle, and the trigger
        // was consumed so it does not re-fire.
        ctrl.update(world);
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('idle');
    });

    it('disabled animator does not change state', () => {
        const { ctrl, world } = setup();
        world.insert(E, Animator, { controller: 'hero', currentState: 'run', enabled: false } as AnimatorData);
        ctrl.setFloat(E, 'speed', 0);
        ctrl.update(world);
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('run');
    });

    it('removeEntity drops parameter state', () => {
        const { ctrl } = setup();
        ctrl.setFloat(E, 'speed', 9);
        expect(ctrl.getFloat(E, 'speed')).toBe(9);
        ctrl.removeEntity(E);
        expect(ctrl.getFloat(E, 'speed')).toBe(0);
    });

    it('auto-advances on exit time when the current clip finishes', () => {
        const ctrl = new AnimatorControllerAPI();
        ctrl.registerController('atk', {
            parameters: [],
            initialState: 'attack',
            states: [
                { name: 'attack', clip: 'attack', loop: false, transitions: [
                    { to: 'idle', conditions: [], hasExitTime: true },
                ] },
                { name: 'idle', clip: 'idle', transitions: [] },
            ],
        });
        const world = makeWorld();
        world.insert(E, Animator, { controller: 'atk', currentState: '', enabled: true } as AnimatorData);
        world.insert(E, SpriteAnimator, spriteData());

        ctrl.update(world); // → attack, applyMotion sets playing = true
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('attack');

        // Still playing → stays in attack.
        ctrl.update(world);
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('attack');

        // Simulate the completion latch written by SpriteAnimationAPI.
        world.update(E, SpriteAnimator, (sp: SpriteAnimatorData) => { sp.playing = false; sp.finished = true; });

        ctrl.update(world); // exit time met → idle
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('idle');
        expect((world.get(E, SpriteAnimator) as SpriteAnimatorData).clip).toBe('idle');
    });

    it('drives the Spine driver on entry to a spine state (and not every frame)', () => {
        const setAnimation = vi.fn();
        const ctrl = new AnimatorControllerAPI();
        ctrl.setSpineDriver({ setAnimation });
        ctrl.registerController('caster', {
            parameters: [{ name: 'cast', type: 'trigger' }],
            initialState: 'idle',
            states: [
                { name: 'idle', spine: { animation: 'idle', loop: true }, transitions: [
                    { to: 'cast', conditions: [{ param: 'cast', op: 'trigger' }] },
                ] },
                { name: 'cast', spine: { animation: 'cast', loop: false }, transitions: [] },
            ],
        });
        const world = makeWorld();
        // No SpriteAnimator — a pure-spine entity.
        world.insert(E, Animator, { controller: 'caster', currentState: '', enabled: true } as AnimatorData);

        ctrl.update(world); // → idle (entry) → setAnimation('idle', true)
        expect(setAnimation).toHaveBeenCalledWith(E, 'idle', true);
        expect(setAnimation).toHaveBeenCalledTimes(1);

        ctrl.update(world); // no state change → no re-set
        expect(setAnimation).toHaveBeenCalledTimes(1);

        ctrl.setTrigger(E, 'cast');
        ctrl.update(world); // → cast → setAnimation('cast', false)
        expect(setAnimation).toHaveBeenLastCalledWith(E, 'cast', false);
        expect(setAnimation).toHaveBeenCalledTimes(2);
    });

    it('spine states are inert without a driver (no throw)', () => {
        const ctrl = new AnimatorControllerAPI();
        ctrl.registerController('s', {
            parameters: [], initialState: 'a',
            states: [{ name: 'a', spine: { animation: 'a' }, transitions: [] }],
        });
        const world = makeWorld();
        world.insert(E, Animator, { controller: 's', currentState: '', enabled: true } as AnimatorData);
        expect(() => ctrl.update(world)).not.toThrow();
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('a');
    });

    it('a 1D-blend state switches clip within the state as the parameter crosses thresholds', () => {
        const ctrl = new AnimatorControllerAPI();
        ctrl.registerController('loco', {
            parameters: [{ name: 'speed', type: 'float', default: 0 }],
            initialState: 'move',
            states: [{
                name: 'move',
                blend: { parameter: 'speed', thresholds: [
                    { value: 0, clip: 'idle' },
                    { value: 3, clip: 'walk' },
                    { value: 7, clip: 'run', speed: 2 },
                ] },
                transitions: [],
            }],
        });
        const world = makeWorld();
        world.insert(E, Animator, { controller: 'loco', currentState: '', enabled: true } as AnimatorData);
        world.insert(E, SpriteAnimator, spriteData());

        ctrl.update(world); // seed 'move', speed 0 → idle
        expect((world.get(E, SpriteAnimator) as SpriteAnimatorData).clip).toBe('idle');

        ctrl.setFloat(E, 'speed', 4); ctrl.update(world);
        let sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;
        expect(sp.clip).toBe('walk');
        // No state change occurred — still 'move'.
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('move');

        ctrl.setFloat(E, 'speed', 9); ctrl.update(world);
        sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;
        expect(sp.clip).toBe('run');
        expect(sp.speed).toBe(2); // per-threshold speed

        ctrl.setFloat(E, 'speed', 1); ctrl.update(world);
        expect((world.get(E, SpriteAnimator) as SpriteAnimatorData).clip).toBe('idle');
    });
});

// ---------------------------------------------------------------------------
// Runtime load-by-path: the .esanimator loader + global store + API fallback.
// Closes the gap where a controller was editable but a Play-time Animator whose
// `controller` is an asset path resolved to nothing and silently did nothing.
// ---------------------------------------------------------------------------

describe('AnimatorController runtime load-by-path', () => {
    const E = 1;
    const PATH = 'assets/animations/player.esanimator';

    beforeEach(() => clearAnimatorControllerStore());

    it('the global store round-trips and clears', () => {
        expect(getRegisteredAnimatorController(PATH)).toBeUndefined();
        registerAnimatorController(PATH, heroController());
        expect(getRegisteredAnimatorController(PATH)?.initialState).toBe('idle');
        clearAnimatorControllerStore();
        expect(getRegisteredAnimatorController(PATH)).toBeUndefined();
    });

    it('getController falls back to the path store when the name is not code-registered', () => {
        const ctrl = new AnimatorControllerAPI();
        expect(ctrl.getController(PATH)).toBeUndefined();
        registerAnimatorController(PATH, heroController());
        expect(ctrl.getController(PATH)?.initialState).toBe('idle');
    });

    it('update() drives an Animator whose controller is ONLY in the path store', () => {
        const ctrl = new AnimatorControllerAPI(); // nothing registered by name
        registerAnimatorController(PATH, heroController());
        const world = makeWorld();
        world.insert(E, Animator, { controller: PATH, currentState: '', enabled: true } as AnimatorData);
        world.insert(E, SpriteAnimator, spriteData());

        ctrl.update(world); // seeds from the path-loaded controller
        expect((world.get(E, Animator) as AnimatorData).currentState).toBe('idle');
        expect((world.get(E, SpriteAnimator) as SpriteAnimatorData).clip).toBe('idle_clip');

        ctrl.setFloat(E, 'speed', 5); ctrl.update(world);
        expect((world.get(E, SpriteAnimator) as SpriteAnimatorData).clip).toBe('run_clip');
    });

    it('a code-registered name wins over a path store entry of the same key', () => {
        const ctrl = new AnimatorControllerAPI();
        ctrl.registerController(PATH, { ...heroController(), initialState: 'run' });
        registerAnimatorController(PATH, heroController()); // initialState 'idle'
        expect(ctrl.getController(PATH)?.initialState).toBe('run'); // code path wins
    });

    it('the .esanimator loader prepares an era and writes nothing anywhere', async () => {
        // Preparing is the whole of it: the slot holds the era and answers the
        // lookup, so a loader that also wrote a store would be a second copy of
        // which controller a name means.
        const loader = new AnimatorControllerAssetLoader();
        expect(loader.type).toBe('animatorcontroller');
        expect(loader.extensions).toEqual(['.esanimator']);

        const payload = JSON.stringify(heroController());
        const ctx = {
            catalog: { getBuildPath: (p: string) => p },
            loadText: async () => payload,
        } as unknown as LoadContext;

        const era = await loader.registry.prepare(PATH, ctx);
        expect(era.value.controllerId).toBe(PATH);
        expect((era.published as { initialState: string }).initialState).toBe('idle');
        expect(getRegisteredAnimatorController(PATH), 'prepare wrote a store').toBeUndefined();
    });

    it('acquires and resolves the clips a LAYER plays, not only the base one', async () => {
        // Shipped once without this: the loader walked `def.states` and called it
        // the controller, so no clip a layer played was fetched or resolved —
        // visible in a real project, invisible to a hand-built one.
        const withLayer = {
            version: 2, parameters: [], initialState: 'Hold',
            states: [{ name: 'Hold', transitions: [], motion: { kind: 'timeline', clip: 'base.estimeline' } }],
            layers: [{
                name: 'Upper', initialState: 'Hold',
                states: [{ name: 'Hold', transitions: [], motion: { kind: 'timeline', clip: 'upper.estimeline' } }],
            }],
        };
        const acquired: string[] = [];
        const ctx = {
            catalog: { getBuildPath: (p: string) => p },
            loadText: async () => JSON.stringify(withLayer),
            acquireAsset: async (_type: string, ref: string) => { acquired.push(ref); },
        } as unknown as LoadContext;

        const era = await new AnimatorControllerAssetLoader().registry.prepare('assets/rig.esanimator', ctx);
        expect(acquired.sort()).toEqual(['assets/base.estimeline', 'assets/upper.estimeline']);
        // Resolved IN PLACE, or the driver looks the clip up under a name nothing
        // was registered as and the layer is silent in exactly the same way.
        const def = era.published as { layers: { states: { motion: { clip: string } }[] }[] };
        expect(def.layers[0]!.states[0]!.motion.clip).toBe('assets/upper.estimeline');
    });

    it('acquires the avatar its clips were authored on, which no component names', async () => {
        // Without it the clip side of a retarget is never loaded, and a rig that
        // names its own avatar plays the clips' raw values: the character-rig
        // knight lay on its back for as long as it existed.
        const withAvatar = {
            version: 2, parameters: [], initialState: 'Hold', avatar: 'hero.esavatar',
            states: [{ name: 'Hold', transitions: [], motion: { kind: 'timeline', clip: 'idle.estimeline' } }],
        };
        const acquired: Array<[string, string]> = [];
        const ctx = {
            catalog: { getBuildPath: (p: string) => p },
            loadText: async () => JSON.stringify(withAvatar),
            acquireAsset: async (type: string, ref: string) => { acquired.push([type, ref]); },
        } as unknown as LoadContext;

        const era = await new AnimatorControllerAssetLoader().registry.prepare('assets/models/loco.esanimator', ctx);
        expect(acquired).toContainEqual(['avatar', 'assets/models/hero.esavatar']);
        expect((era.published as { avatar: string }).avatar).toBe('assets/models/hero.esavatar');
    });
});