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.

9.6 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 type { ESEngineModule, CppRegistry } from '../src/wasm';
import type { Entity } from '../src/types';
import {
    TweenAPI,
    TweenHandle,
    EasingType,
    TweenTarget,
    TweenState,
    LoopMode,
} from '../src/animation/Tween';

function createMockAnimModule() {
    const calls: Record<string, any[][]> = {};
    function track(name: string, ...args: any[]) {
        (calls[name] ??= []).push(args);
    }

    let nextTweenEntity = 1000;

    const registry = {} as CppRegistry;

    const module = {
        anim_createTween: vi.fn((_reg: CppRegistry, entity: number, targetProp: number,
            from: number, to: number, duration: number,
            easing: number, delay: number, loopMode: number, loopCount: number) => {
            return nextTweenEntity++;
        }),
        anim_cancelTween: vi.fn(),
        anim_cancelAllTweens: vi.fn(),
        anim_pauseTween: vi.fn(),
        anim_resumeTween: vi.fn(),
        anim_setTweenBezier: vi.fn(),
        anim_setSequenceNext: vi.fn(),
        anim_updateTweens: vi.fn(),
        anim_getTweenState: vi.fn(() => TweenState.Running),
    } as unknown as ESEngineModule;

    return { module, registry, calls };
}

describe('Tween API', () => {
    let module: ESEngineModule;
    let registry: CppRegistry;
    let tween: TweenAPI;

    beforeEach(() => {
        const mock = createMockAnimModule();
        module = mock.module;
        registry = mock.registry;
        tween = new TweenAPI(module, registry);
    });

    // =========================================================================
    // Enums
    // =========================================================================

    describe('enums', () => {
        it('EasingType values should match C++ enum', () => {
            expect(EasingType.Linear).toBe(0);
            expect(EasingType.EaseInQuad).toBe(1);
            expect(EasingType.EaseOutBounce).toBe(13);
            expect(EasingType.CubicBezier).toBe(14);
            expect(EasingType.Step).toBe(15);
        });

        it('TweenTarget values should match C++ enum', () => {
            expect(TweenTarget.PositionX).toBe(0);
            expect(TweenTarget.PositionY).toBe(1);
            expect(TweenTarget.ScaleX).toBe(3);
            expect(TweenTarget.ColorA).toBe(9);
            expect(TweenTarget.CameraOrthoSize).toBe(12);
        });

        it('TweenState values should match C++ enum', () => {
            expect(TweenState.Running).toBe(0);
            expect(TweenState.Paused).toBe(1);
            expect(TweenState.Completed).toBe(2);
            expect(TweenState.Cancelled).toBe(3);
        });

        it('LoopMode values should match C++ enum', () => {
            expect(LoopMode.None).toBe(0);
            expect(LoopMode.Restart).toBe(1);
            expect(LoopMode.PingPong).toBe(2);
        });
    });

    // =========================================================================
    // tween.to()
    // =========================================================================

    describe('tween.to()', () => {
        it('should call WASM createTween with correct params', () => {
            const entity = 42 as Entity;
            tween.to(entity, TweenTarget.PositionX, 0, 100, 1.5);

            expect(module.anim_createTween).toHaveBeenCalledWith(
                registry, 42, TweenTarget.PositionX,
                0, 100, 1.5,
                EasingType.Linear, 0, LoopMode.None, 0,
            );
        });

        it('should pass easing option', () => {
            tween.to(1 as Entity, TweenTarget.ColorA, 1, 0, 0.5, {
                easing: EasingType.EaseOutQuad,
            });

            expect(module.anim_createTween).toHaveBeenCalledWith(
                registry, 1, TweenTarget.ColorA,
                1, 0, 0.5,
                EasingType.EaseOutQuad, 0, LoopMode.None, 0,
            );
        });

        it('should pass delay option', () => {
            tween.to(1 as Entity, TweenTarget.ScaleX, 1, 2, 1, {
                delay: 0.5,
            });

            expect(module.anim_createTween).toHaveBeenCalledWith(
                registry, 1, TweenTarget.ScaleX,
                1, 2, 1,
                EasingType.Linear, 0.5, LoopMode.None, 0,
            );
        });

        it('should pass loop options', () => {
            tween.to(1 as Entity, TweenTarget.PositionY, 0, 50, 2, {
                loop: LoopMode.PingPong,
                loopCount: 3,
            });

            expect(module.anim_createTween).toHaveBeenCalledWith(
                registry, 1, TweenTarget.PositionY,
                0, 50, 2,
                EasingType.Linear, 0, LoopMode.PingPong, 3,
            );
        });

        it('should return a TweenHandle', () => {
            const handle = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            expect(handle).toBeInstanceOf(TweenHandle);
        });
    });

    // =========================================================================
    // TweenHandle
    // =========================================================================

    describe('TweenHandle', () => {
        it('should report state from WASM', () => {
            (module.anim_getTweenState as ReturnType<typeof vi.fn>)
                .mockReturnValueOnce(TweenState.Paused);

            const handle = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            expect(handle.state).toBe(TweenState.Paused);
        });

        it('should call WASM setBezier', () => {
            const handle = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            handle.bezier(0.25, 0.1, 0.25, 1.0);

            expect(module.anim_setTweenBezier).toHaveBeenCalledWith(
                registry, handle.entity, 0.25, 0.1, 0.25, 1.0,
            );
        });

        it('bezier() should return this for chaining', () => {
            const handle = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            const result = handle.bezier(0, 0, 1, 1);
            expect(result).toBe(handle);
        });

        it('should chain tweens with then()', () => {
            const h1 = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            const h2 = tween.to(1 as Entity, TweenTarget.PositionY, 0, 20, 1);
            h1.then(h2);

            expect(module.anim_setSequenceNext).toHaveBeenCalledWith(
                registry, h1.entity, h2.entity,
            );
        });

        it('then() should return this for chaining', () => {
            const h1 = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            const h2 = tween.to(1 as Entity, TweenTarget.PositionY, 0, 20, 1);
            const result = h1.then(h2);
            expect(result).toBe(h1);
        });

        it('should pause a tween', () => {
            const handle = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            handle.pause();

            expect(module.anim_pauseTween).toHaveBeenCalledWith(registry, handle.entity);
        });

        it('should resume a tween', () => {
            const handle = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            handle.resume();

            expect(module.anim_resumeTween).toHaveBeenCalledWith(registry, handle.entity);
        });

        it('should cancel a tween via handle', () => {
            const handle = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            handle.cancel();

            expect(module.anim_cancelTween).toHaveBeenCalledWith(registry, handle.entity);
        });
    });

    // =========================================================================
    // Instance methods
    // =========================================================================

    describe('instance methods', () => {
        it('tween.cancel() should delegate to WASM', () => {
            const handle = tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            tween.cancel(handle);

            expect(module.anim_cancelTween).toHaveBeenCalledWith(registry, handle.entity);
        });

        it('tween.cancelAll() should delegate to WASM', () => {
            const entity = 5 as Entity;
            tween.cancelAll(entity);

            expect(module.anim_cancelAllTweens).toHaveBeenCalledWith(registry, 5);
        });

        it('tween.update() should delegate to WASM', () => {
            tween.update(0.016);

            expect(module.anim_updateTweens).toHaveBeenCalledWith(registry, 0.016);
        });
    });

    // =========================================================================
    // Per-app isolation
    // =========================================================================

    describe('isolation', () => {
        it('two TweenAPI instances drive independent WASM calls', () => {
            const { module: module2, registry: registry2 } = createMockAnimModule();
            const tween2 = new TweenAPI(module2, registry2);

            tween.to(1 as Entity, TweenTarget.PositionX, 0, 10, 1);
            tween2.to(2 as Entity, TweenTarget.PositionY, 0, 20, 1);

            expect(module.anim_createTween).toHaveBeenCalledTimes(1);
            expect(module2.anim_createTween).toHaveBeenCalledTimes(1);
            expect(module.anim_createTween).toHaveBeenCalledWith(
                registry, 1, TweenTarget.PositionX,
                0, 10, 1,
                EasingType.Linear, 0, LoopMode.None, 0,
            );
            expect(module2.anim_createTween).toHaveBeenCalledWith(
                registry2, 2, TweenTarget.PositionY,
                0, 20, 1,
                EasingType.Linear, 0, LoopMode.None, 0,
            );
        });
    });
});