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.

12.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  The JS-side value tween manager (the fallback path for fields the C++
 *        TweenTarget doesn't cover). Pure timing/easing/loop/sequence logic —
 *        the only wasm touchpoint is polling a linked C++ sequence's state, which
 *        a stub module stands in for. It sat at ~20% with none of its branches
 *        (delay carry-over, ping-pong, loop counts, chaining, same-frame resume)
 *        asserted.
 */
import { describe, it, expect, vi } from 'vitest';
import { ValueTweenManager, ValueTweenHandle } from '../src/animation/ValueTween';
import { TweenGroup } from '../src/animation/TweenGroup';
import { TweenState, LoopMode } from '../src/animation/TweenTypes';
import type { CppRegistry } from '../src/wasm';
import type { AnimCore } from '../src/animation/Tween';
import { TweenAPI } from '../src/animation/Tween';

// The manager only ever calls module.anim_getTweenState (for C++ sequences);
// everything else is pure JS. A closure-controlled stub covers that one seam.
function makeManager(cppState: () => number = () => TweenState.Running) {
  const module = { anim_getTweenState: vi.fn(() => cppState()) } as unknown as AnimCore;
  const registry = {} as CppRegistry;
  return new ValueTweenManager(module, registry);
}

describe('ValueTweenManager progression', () => {
  it.each([0, -1])('completes an immediate tween of duration %j without emitting NaN', duration => {
    const m = makeManager(), seen = vi.fn();
    const id = m.create(10, 30, duration, seen);
    m.update(0);
    expect(seen.mock.calls).toEqual([[30]]);
    expect(m.getState(id)).toBe(TweenState.Completed);
  });

  it('honors the delay before applying an immediate tween', () => {
    const m = makeManager(), seen = vi.fn();
    const id = m.create(10, 30, 0, seen, { delay: .5 });
    m.update(.25);
    expect(seen).not.toHaveBeenCalled();
    m.update(.25);
    expect(seen.mock.calls).toEqual([[30]]);
    expect(m.getState(id)).toBe(TweenState.Completed);
  });
  it('does not recursively step the native engine through TweenAPI.update', () => {
    const nativeStep = vi.fn();
    const api = new TweenAPI({ anim_updateTweens: nativeStep } as unknown as AnimCore, {} as CppRegistry);
    let nested = false;
    api.value(0, 1, 1, () => {
      if (!nested) { nested = true; api.update(.25); }
    });
    api.update(.25);
    expect(nativeStep).toHaveBeenCalledOnce();
  });
  it('defers tweens created by a callback until the next update', () => {
    const m = makeManager(), child = vi.fn();
    let created = false;
    m.create(0, 1, 1, () => {
      if (!created) { created = true; m.create(0, 1, 1, child); }
    });
    m.update(.5);
    expect(child).not.toHaveBeenCalled();
    m.update(.25);
    expect(child).toHaveBeenCalledWith(.25);
  });

  it('does not recursively advance playback from an update callback', () => {
    const m = makeManager();
    let nested = false;
    const values: number[] = [];
    m.create(0, 1, 1, value => {
      values.push(value);
      if (!nested) { nested = true; m.update(.25); }
    });
    m.update(.25);
    expect(values).toEqual([.25]);
  });

  it.each(['cancel', 'pause'] as const)('preserves callback %s at completion and leaves the sequence paused', action => {
    const m = makeManager(), next = vi.fn();
    const id = m.create(0, 1, 1, () => m[action](id));
    const child = m.create(0, 1, 1, next);
    m.setSequenceNext(id, child);
    m.update(1);
    expect(m.getState(id)).toBe(action === 'cancel' ? TweenState.Cancelled : TweenState.Paused);
    expect(m.getState(child)).toBe(TweenState.Paused);
    expect(next).not.toHaveBeenCalled();
  });

  it('releases the update guard when a callback throws', () => {
    const m = makeManager();
    let fail = true;
    const values: number[] = [];
    m.create(0, 1, 1, value => {
      if (fail) { fail = false; throw new Error('callback failed'); }
      values.push(value);
    });
    expect(() => m.update(.25)).toThrow('callback failed');
    m.update(.25);
    expect(values).toEqual([.5]);
  });

  it('drives the callback with the linearly-eased value', () => {
    const m = makeManager();
    const seen: number[] = [];
    m.create(0, 100, 1, (v) => seen.push(v));
    m.update(0.25);
    m.update(0.25);
    expect(seen).toEqual([25, 50]);
  });

  it('delivers the end value, then stays queryable as Completed until the NEXT update', () => {
    const m = makeManager();
    let last = -1;
    const id = m.create(10, 30, 1, (v) => { last = v; });
    m.update(1);
    expect(last).toBe(30);
    // Sweep is deferred one frame: a just-completed entry stays queryable as
    // Completed for the rest of this frame so a composition polling afterwards
    // observes Completed (not a same-frame-deleted → Cancelled). It's reaped at
    // the start of the next update.
    expect(m.getState(id)).toBe(TweenState.Completed);
    m.update(0.016);
    expect(m.getState(id)).toBe(TweenState.Cancelled);
  });

  it('a parallel group of value tweens completes (not stuck as Cancelled)', () => {
    const m = makeManager();
    const id = m.create(0, 1, 1, () => {});
    // How a composition observes a member: a Completable reading the live state.
    const member = { get state() { return m.getState(id); }, pause() {}, resume() {}, cancel() {} };
    let done = false;
    const group = new TweenGroup([member]);
    group.onComplete(() => { done = true; });
    // TweenAPI.update order: value manager advances/completes first, THEN the
    // composition polls. The completed member must read Completed, not Cancelled.
    m.update(1);
    expect(group.checkComplete()).toBe(true);
    expect(done).toBe(true);
  });

  it('holds during the delay, then applies the leftover dt once it elapses', () => {
    const m = makeManager();
    const seen: number[] = [];
    m.create(0, 100, 1, (v) => seen.push(v), { delay: 0.5 });
    m.update(0.3);          // still inside the delay
    expect(seen).toEqual([]);
    m.update(0.3);          // 0.1 of dt spills past the delay into the tween
    expect(seen).toHaveLength(1);
    expect(seen[0]).toBeCloseTo(10, 6); // ~0.1s into a 1s 0→100 tween (float carry)
  });
});

describe('ValueTweenManager state transitions', () => {
  it('pause() freezes progress and resume() thaws it', () => {
    const m = makeManager();
    const seen: number[] = [];
    const id = m.create(0, 100, 1, (v) => seen.push(v));
    m.pause(id);
    m.update(0.5);
    expect(seen).toEqual([]);
    expect(m.getState(id)).toBe(TweenState.Paused);
    m.resume(id);
    m.update(0.5);
    expect(seen).toEqual([50]);
  });

  it('cancel() stops the tween and drops it on the next update', () => {
    const m = makeManager();
    const cb = vi.fn();
    const id = m.create(0, 100, 1, cb);
    m.cancel(id);
    expect(m.getState(id)).toBe(TweenState.Cancelled);
    m.update(1);
    expect(cb).not.toHaveBeenCalled();
    expect(m.getState(id)).toBe(TweenState.Cancelled); // swept
  });

  it('getState() reports Cancelled for an unknown id', () => {
    expect(makeManager().getState(999)).toBe(TweenState.Cancelled);
  });
});

describe('ValueTweenManager looping', () => {
  it('keeps loop phase finite when elapsed addition would overflow', () => {
    const m = makeManager(), seen = vi.fn();
    m.create(0, 10, Number.MAX_VALUE, seen, { loop: LoopMode.Restart });
    m.update(Number.MAX_VALUE / 2);
    m.update(Number.MAX_VALUE);
    expect(seen.mock.calls).toEqual([[5], [10]]);
  });
  it.each([LoopMode.Restart, LoopMode.PingPong])('retains long-frame phase for loop mode %j', loop => {
    const run = (steps: number[]) => {
      const m = makeManager(); let value = -1;
      m.create(0, 10, 1, v => { value = v; }, { loop });
      for (const dt of steps) m.update(dt);
      return value;
    };
    expect(run([1.25])).toBeCloseTo(run([.25, .25, .25, .25, .25]));
    expect(run([1000000.25])).toBeCloseTo(2.5);
  });

  it.each([LoopMode.Restart, LoopMode.PingPong])('completes all finite cycles in one long update, mode %j', loop => {
    const m = makeManager(), seen = vi.fn();
    const id = m.create(0, 10, 1, seen, { loop, loopCount: 2 });
    m.update(10.25);
    expect(seen.mock.calls).toEqual([[loop === LoopMode.Restart ? 10 : 0]]);
    expect(m.getState(id)).toBe(TweenState.Completed);
  });

  it('carries delay remainder into a looping tween', () => {
    const m = makeManager(), seen = vi.fn();
    m.create(0, 10, 1, seen, { delay: .5, loop: LoopMode.PingPong });
    m.update(1.75);
    expect(seen.mock.calls).toEqual([[7.5]]);
  });
  it('Restart replays loopCount times then completes', () => {
    const m = makeManager();
    const seen: number[] = [];
    m.create(0, 10, 1, (v) => seen.push(v), { loop: LoopMode.Restart, loopCount: 2 });
    m.update(1); // first pass reaches 10, loops
    m.update(1); // second pass reaches 10, completes
    expect(seen).toEqual([10, 10]);
  });

  it('PingPong reverses from/to each cycle', () => {
    const m = makeManager();
    const seen: number[] = [];
    m.create(0, 10, 1, (v) => seen.push(v), { loop: LoopMode.PingPong, loopCount: 2 });
    m.update(1); // 0→10
    m.update(1); // now 10→0
    expect(seen).toEqual([10, 0]);
  });

  it('loopCount 0 loops forever (never completes)', () => {
    const m = makeManager();
    const cb = vi.fn();
    const id = m.create(0, 10, 1, cb, { loop: LoopMode.Restart, loopCount: 0 });
    for (let i = 0; i < 4; i++) m.update(1);
    expect(m.getState(id)).toBe(TweenState.Running);
    expect(cb).toHaveBeenCalledTimes(4);
  });
});

describe('ValueTweenManager sequencing', () => {
  it('setSequenceNext pauses the follow-up until the leader completes, then resumes it in-frame', () => {
    const m = makeManager();
    const bSeen: number[] = [];
    const a = m.create(0, 10, 1, () => {});
    const b = m.create(0, 20, 10, (v) => bSeen.push(v)); // long, so it survives its first tick
    m.setSequenceNext(a, b);
    expect(m.getState(b)).toBe(TweenState.Paused);
    m.update(1); // a completes → b resumes and advances by the same dt
    expect(m.getState(b)).toBe(TweenState.Running);
    expect(bSeen).toEqual([2]); // 1s into a 10s 0→20 tween
  });

  it('setSequenceNextExternal pauses the external immediately and resumes it on completion', () => {
    const m = makeManager();
    const ext = { pause: vi.fn(), resume: vi.fn() };
    const a = m.create(0, 10, 1, () => {});
    m.setSequenceNextExternal(a, ext);
    expect(ext.pause).toHaveBeenCalledTimes(1);
    expect(ext.resume).not.toHaveBeenCalled();
    m.update(1);
    expect(ext.resume).toHaveBeenCalledTimes(1);
  });

  it('a registered C++ sequence keeps the JS tween paused until the C++ side reports Completed', () => {
    let cpp = TweenState.Running;
    const m = makeManager(() => cpp);
    const cb = vi.fn();
    const j = m.create(0, 10, 1, cb);
    m.registerCppSequence(1 as never, j);
    expect(m.getState(j)).toBe(TweenState.Paused);
    m.update(1);                       // C++ still running → JS stays paused
    expect(m.getState(j)).toBe(TweenState.Paused);
    expect(cb).not.toHaveBeenCalled();
    cpp = TweenState.Completed;
    m.update(1);                       // C++ done → JS resumes and runs this frame
    expect(cb).toHaveBeenCalled();
  });
});

describe('ValueTweenHandle', () => {
  it('routes state and lifecycle calls back to its manager', () => {
    const m = makeManager();
    const id = m.create(0, 10, 1, () => {});
    const h = new ValueTweenHandle(m, id);
    expect(h.id).toBe(id);
    expect(h.manager).toBe(m);
    expect(h.state).toBe(TweenState.Running);
    h.pause();
    expect(m.getState(id)).toBe(TweenState.Paused);
    h.resume();
    expect(m.getState(id)).toBe(TweenState.Running);
    h.cancel();
    expect(h.state).toBe(TweenState.Cancelled);
  });

  it('then(handle) chains via setSequenceNext; then(external) chains via the external hook', () => {
    const m = makeManager();
    const a = new ValueTweenHandle(m, m.create(0, 1, 1, () => {}));
    const b = new ValueTweenHandle(m, m.create(0, 1, 1, () => {}));
    expect(a.then(b)).toBe(a);            // fluent
    expect(m.getState(b.id)).toBe(TweenState.Paused); // follow-up paused

    const c = new ValueTweenHandle(m, m.create(0, 1, 1, () => {}));
    const ext = { pause: vi.fn(), resume: vi.fn() };
    c.then(ext);
    expect(ext.pause).toHaveBeenCalledTimes(1);
  });
});