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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect } from 'vitest';
import {
detectTimelineEvents,
advanceTimelineTS,
createTimelineState,
applyPlayerFlags,
latchPlayerFinish,
type TimelinePlayerFlags,
type TimelineState,
} from '../src/timeline/TimelineDrive';
import { TimelineEventType } from '../src/timeline/TimelineRuntime';
import { TimelineAPI } from '../src/timeline/TimelineControl';
import { resolveWrapMode } from '../src/timeline/TimelinePlugin';
import { WrapMode, TrackType, InterpType, type TimelineAsset } from '../src/timeline/TimelineTypes';
import type { SampleDeps } from '../src/timeline/TimelineEvaluator';
import type { AudioAPI } from '../src/audio/Audio';
const ROOT = 1 as const;
const resolveRoot = (root: number, childPath: string) => (childPath ? null : root);
function spineAsset(): TimelineAsset {
return {
version: '1.1', type: 'timeline', duration: 3, wrapMode: WrapMode.Once,
tracks: [{
type: TrackType.Spine, name: 'Char', childPath: '', blendIn: 0,
clips: [
{ start: 0, duration: 1, animation: 'a', loop: false, speed: 1 },
{ start: 1, duration: 1, animation: 'b', loop: true, speed: 2 },
],
}],
};
}
describe('detectTimelineEvents (1:1 with C++ evaluateEventTracks)', () => {
it('spine: enter clip → SpinePlay, switch clip → SpinePlay, exit → SpineStop', () => {
const asset = spineAsset();
const s = createTimelineState();
s.prevTime = 0; s.time = 0.5;
let ev = detectTimelineEvents(asset, s, resolveRoot, ROOT);
expect(ev).toEqual([{ kind: TimelineEventType.SpinePlay, entity: ROOT, intParam: 0, floatParam: 1, str: 'a' }]);
s.prevTime = 0.5; s.time = 1.5;
ev = detectTimelineEvents(asset, s, resolveRoot, ROOT);
expect(ev).toEqual([{ kind: TimelineEventType.SpinePlay, entity: ROOT, intParam: 1, floatParam: 2, str: 'b' }]);
s.prevTime = 1.5; s.time = 2.5; // past both clips
ev = detectTimelineEvents(asset, s, resolveRoot, ROOT);
expect(ev).toEqual([{ kind: TimelineEventType.SpineStop, entity: ROOT, intParam: 0, floatParam: 0, str: '' }]);
});
it('audio: fires only when an event time is crossed in (prev, time]', () => {
const asset: TimelineAsset = {
version: '1.1', type: 'timeline', duration: 2, wrapMode: WrapMode.Once,
tracks: [{ type: TrackType.Audio, name: 'SFX', childPath: '', events: [{ time: 0.5, clip: 'x', volume: 0.8 }] }],
};
const s = createTimelineState();
s.prevTime = 0.4; s.time = 0.6;
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)).toEqual([
{ kind: TimelineEventType.AudioPlay, entity: ROOT, intParam: 0, floatParam: 0.8, str: 'x' },
]);
s.prevTime = 0.6; s.time = 0.9; // 0.5 already passed
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)).toEqual([]);
});
it('audio: a loop-seam event fires via the split wrap segments, not the empty single span', () => {
const asset: TimelineAsset = {
version: '1.1', type: 'timeline', duration: 5, wrapMode: WrapMode.Loop,
tracks: [{ type: TrackType.Audio, name: 'SFX', childPath: '', events: [{ time: 0.05, clip: 'step', volume: 1 }] }],
};
const s = createTimelineState(WrapMode.Loop);
s.prevTime = 4.9; s.time = 0.1; // a frame that wrapped 4.9 → 5.1 → 0.1
// (prevTime, time] = (4.9, 0.1] is empty — the pre-fix single span misses the seam event.
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)).toEqual([]);
// The two seam segments advanceTimelineTS passes on a wrap DO cross t=0.05:
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT, [[4.9, 5], [0, 0.1]])).toEqual([
{ kind: TimelineEventType.AudioPlay, entity: ROOT, intParam: 0, floatParam: 1, str: 'step' },
]);
});
it('advanceTimelineTS: a looping clip keeps firing a near-start event every loop', () => {
const asset: TimelineAsset = {
version: '1.1', type: 'timeline', duration: 1, wrapMode: WrapMode.Loop,
tracks: [{ type: TrackType.Audio, name: 'SFX', childPath: '', events: [{ time: 0.05, clip: 'step', volume: 1 }] }],
};
const s = createTimelineState(WrapMode.Loop);
s.playing = true;
const deps: SampleDeps = { world: {} as SampleDeps['world'], getComponent: () => undefined, resolveChild: resolveRoot };
const plays: string[] = [];
const audio = { playSFX: (clip: string) => { plays.push(clip); } } as unknown as AudioAPI;
// 0.9s/frame: f1 0→0.9 crosses 0.05; f2 0.9→1.8→wrap→0.8 crosses 0.05 on the SEAM.
advanceTimelineTS(asset, ROOT, s, 0.9, { deps, audio });
advanceTimelineTS(asset, ROOT, s, 0.9, { deps, audio });
expect(plays).toEqual(['step', 'step']); // fired on BOTH loops (2nd is the wrap seam)
});
it('spriteAnim: fires once when startTime is crossed', () => {
const asset: TimelineAsset = {
version: '1.1', type: 'timeline', duration: 2, wrapMode: WrapMode.Once,
tracks: [{ type: TrackType.SpriteAnim, name: 'FX', childPath: '', clip: 'boom', startTime: 1 }],
};
const s = createTimelineState();
s.prevTime = 0.9; s.time = 1.1;
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)).toHaveLength(1);
s.prevTime = 1.1; s.time = 1.5;
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)).toEqual([]);
});
it('activation: emits active state every frame (range half-open)', () => {
const asset: TimelineAsset = {
version: '1.1', type: 'timeline', duration: 2, wrapMode: WrapMode.Once,
tracks: [{ type: TrackType.Activation, name: 'Show', childPath: '', ranges: [{ start: 0, end: 1 }] }],
};
const s = createTimelineState();
s.time = 0.5;
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)[0].intParam).toBe(1);
s.time = 1.5;
expect(detectTimelineEvents(asset, s, resolveRoot, ROOT)[0].intParam).toBe(0);
});
});
function mockDeps(store: Map<string, any>, defs: Record<string, object>): SampleDeps {
return {
world: {
has: (_e, def) => store.has((def as any).__name),
get: (_e, def) => store.get((def as any).__name),
set: (_e, def, data) => store.set((def as any).__name, data),
},
getComponent: (name) => defs[name],
resolveChild: resolveRoot,
};
}
describe('advanceTimelineTS (clock + property apply + stop)', () => {
const asset: TimelineAsset = {
version: '1.1', type: 'timeline', duration: 2, wrapMode: WrapMode.Once,
tracks: [{
type: TrackType.Property, name: 'Move', childPath: '', component: 'Transform',
channels: [{
property: 'position.x',
keyframes: [
{ time: 0, value: 0, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear },
{ time: 2, value: 100, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear },
],
}],
}],
};
it('advances time, applies the sampled value, and stops at the end (Once)', () => {
const defs = { Transform: { __name: 'Transform' } };
const store = new Map<string, any>([['Transform', { position: { x: 0, y: 0, z: 0 } }]]);
const s: TimelineState = createTimelineState(WrapMode.Once);
s.playing = true;
let stopped = advanceTimelineTS(asset, ROOT, s, 1, { deps: mockDeps(store, defs) });
expect(s.time).toBeCloseTo(1, 5);
expect(store.get('Transform').position.x).toBeCloseTo(50, 5);
expect(stopped).toBe(false);
expect(s.playing).toBe(true);
stopped = advanceTimelineTS(asset, ROOT, s, 5, { deps: mockDeps(store, defs) });
expect(s.time).toBeCloseTo(2, 5); // clamped to duration
expect(stopped).toBe(true);
expect(s.playing).toBe(false); // Once → stops
});
it('does nothing while paused', () => {
const defs = { Transform: { __name: 'Transform' } };
const store = new Map<string, any>([['Transform', { position: { x: 7, y: 0, z: 0 } }]]);
const s = createTimelineState();
s.playing = false;
advanceTimelineTS(asset, ROOT, s, 1, { deps: mockDeps(store, defs) });
expect(store.get('Transform').position.x).toBe(7); // untouched
});
});
describe('TimelinePlayer flag contract (applyPlayerFlags / latchPlayerFinish)', () => {
const bare = (duration = 1): TimelineAsset =>
({ version: '1.1', type: 'timeline', duration, wrapMode: WrapMode.Once, tracks: [] });
const deps: SampleDeps = {
world: {} as SampleDeps['world'],
getComponent: () => undefined,
resolveChild: resolveRoot,
};
function tick(flags: TimelinePlayerFlags, s: TimelineState, asset: TimelineAsset, dt: number): boolean {
const rewound = applyPlayerFlags(flags, s);
const fin = advanceTimelineTS(asset, ROOT, s, dt, { deps });
return latchPlayerFinish(flags, s, fin) || rewound;
}
it('latches finished (and clears playing) when a Once clip completes', () => {
const flags: TimelinePlayerFlags = { playing: true, finished: false };
const s = createTimelineState(WrapMode.Once);
expect(tick(flags, s, bare(1), 0.4)).toBe(false);
expect(flags).toEqual({ playing: true, finished: false });
expect(tick(flags, s, bare(1), 0.7)).toBe(true); // crosses the end
expect(flags).toEqual({ playing: false, finished: true });
expect(s.time).toBeCloseTo(1, 5); // parked at the end
});
it('replays from the top when playing is raised on a finished clip', () => {
const flags: TimelinePlayerFlags = { playing: true, finished: false };
const s = createTimelineState(WrapMode.Once);
tick(flags, s, bare(1), 2); // run to completion
expect(flags.finished).toBe(true);
flags.playing = true; // the replay raise (FSM action / game code / editor)
expect(tick(flags, s, bare(1), 0.25)).toBe(true); // finished cleared → write-back
expect(flags).toEqual({ playing: true, finished: false });
expect(s.time).toBeCloseTo(0.25, 5); // advanced from 0, not from the end
});
it('an ultra-short clip replays and re-finishes within one tick', () => {
const flags: TimelinePlayerFlags = { playing: true, finished: false };
const s = createTimelineState(WrapMode.Once);
tick(flags, s, bare(0.05), 1);
flags.playing = true;
expect(tick(flags, s, bare(0.05), 1)).toBe(true);
expect(flags).toEqual({ playing: false, finished: true });
});
it('a stop that is not a Once completion clears playing without latching finished', () => {
const flags: TimelinePlayerFlags = { playing: true, finished: false };
const s = createTimelineState(WrapMode.Once);
s.playing = false; // stopped by some non-completion source
expect(latchPlayerFinish(flags, s, false)).toBe(true);
expect(flags).toEqual({ playing: false, finished: false });
});
it('applyPlayerFlags mid-clip is a plain sync (no rewind, no write-back)', () => {
const flags: TimelinePlayerFlags = { playing: true, finished: false };
const s = createTimelineState(WrapMode.Once);
s.time = 0.5;
s.prevTime = 0.4;
expect(applyPlayerFlags(flags, s)).toBe(false);
expect(s.time).toBeCloseTo(0.5, 5);
expect(s.playing).toBe(true);
});
});
describe('TimelineAPI write-through (play/pause/stop reach the component flags)', () => {
it('routes to raise/lower/reset so the flag survives the per-tick reconcile', () => {
const calls: string[] = [];
const api = new TimelineAPI({
raise: e => calls.push(`raise:${e}`),
lower: e => calls.push(`lower:${e}`),
reset: e => calls.push(`reset:${e}`),
});
api.play(ROOT);
api.pause(ROOT);
api.stop(ROOT);
expect(calls).toEqual([`raise:${ROOT}`, `lower:${ROOT}`, `reset:${ROOT}`]);
});
it('stop also rewinds the clock state', () => {
const api = new TimelineAPI();
const s = api.ensureState(ROOT, WrapMode.Once, 1);
s.playing = true;
s.time = 1.5;
s.prevTime = 1.4;
api.stop(ROOT);
expect(s).toMatchObject({ playing: false, time: 0, prevTime: 0 });
});
});
/** The clip declares the wrap mode; the player's field only overrides it. */
describe('whose wrap mode wins', () => {
it('takes the clip\'s when the player names no override', () => {
expect(resolveWrapMode('', WrapMode.Loop)).toBe(WrapMode.Loop);
expect(resolveWrapMode('', WrapMode.PingPong)).toBe(WrapMode.PingPong);
expect(resolveWrapMode('', WrapMode.Once)).toBe(WrapMode.Once);
});
it('lets the player override the clip when it names one', () => {
expect(resolveWrapMode('once', WrapMode.Loop)).toBe(WrapMode.Once);
expect(resolveWrapMode('loop', WrapMode.Once)).toBe(WrapMode.Loop);
});
// An override nobody can spell must not silently become Once and re-create
// the bug: it is not a name, so it is not an override.
it('falls back to the clip for a name it cannot decode', () => {
expect(resolveWrapMode('sideways', WrapMode.Loop)).toBe(WrapMode.Loop);
});
});
describe('nested sequences', () => {
const deps: SampleDeps = { world: {} as SampleDeps['world'], getComponent: () => undefined, resolveChild: resolveRoot };
const child: TimelineAsset = {
version: '1.3', type: 'timeline', duration: 2, wrapMode: WrapMode.Once,
tracks: [{ type: TrackType.CustomEvent, name: 'E', childPath: '', events: [{ time: 0, name: 'go', payload: {} }] }],
};
const parent: TimelineAsset = {
version: '1.3', type: 'timeline', duration: 6, wrapMode: WrapMode.Once,
tracks: [{ type: TrackType.Sequence, name: 'S', childPath: '', clips: [
{ start: 1, duration: 2, timeline: 'child', root: '', speed: 1, loop: false },
] }],
};
const lookup = (ref: string) => (ref === 'child' ? child : undefined);
it('runs a nested clock, forgets it after the clip and starts it over on re-entry', () => {
const s = createTimelineState(WrapMode.Once);
s.playing = true;
const shots: unknown[] = [];
const step = (dt: number) => advanceTimelineTS(parent, ROOT, s, dt, { deps, lookup, onShot: (x) => shots.push(x) });
step(0.5);
expect(Object.keys(s.nested)).toHaveLength(0);
step(1);
expect(Object.keys(s.nested)).toEqual(['0.0/']);
expect(s.nested['0.0/']!.time).toBeCloseTo(0.5);
step(2);
expect(Object.keys(s.nested)).toHaveLength(0);
expect(shots.every((x) => x === null)).toBe(true);
});
it('does nothing for nested clips without a lookup', () => {
const s = createTimelineState(WrapMode.Once);
s.playing = true;
advanceTimelineTS(parent, ROOT, s, 1.5, { deps });
expect(Object.keys(s.nested)).toHaveLength(0);
});
});
describe('native particle event tracks', () => {
it('keeps the ping-pong phase across frames and shares entry/crossing semantics with animator motions', () => {
const asset: TimelineAsset={version:'1.3',type:'timeline',duration:1,wrapMode:WrapMode.PingPong,
tracks:[{type:TrackType.Particle,name:'burst',childPath:'',events:[{time:0,action:'play'},{time:.5,action:'stop'}]}]};
const state=createTimelineState(WrapMode.PingPong);state.playing=true;
const calls:string[]=[],particle={reset:()=>calls.push('reset'),play:()=>calls.push('play'),stop:()=>calls.push('stop')};
const deps:SampleDeps={world:{} as SampleDeps['world'],getComponent:()=>undefined,resolveChild:resolveRoot};
advanceTimelineTS(asset,ROOT,state,0,{deps,particle});
advanceTimelineTS(asset,ROOT,state,0,{deps,particle});
const times:number[]=[];
for(let i=0;i<4;i++){advanceTimelineTS(asset,ROOT,state,.6,{deps,particle});times.push(state.time);}
[.6,.8,.2,.4].forEach((time,i)=>expect(times[i]).toBeCloseTo(time));
expect(calls).toEqual(['reset','play','stop','stop','reset','play']);
const api=new TimelineAPI();const owned=api.ensureState(ROOT,WrapMode.PingPong,1);
Object.assign(owned,state);api.stop(ROOT);api.play(ROOT);
advanceTimelineTS(asset,ROOT,owned,.1,{deps,particle});
expect(owned.time).toBeCloseTo(.1);expect(calls.slice(-2)).toEqual(['reset','play']);
});
it('restarts once at zero, stops at its key, and fires again across a loop', () => {
const asset: TimelineAsset={version:'1.3',type:'timeline',duration:1,wrapMode:WrapMode.Loop,
tracks:[{type:TrackType.Particle,name:'burst',childPath:'',events:[{time:0,action:'play'},{time:.5,action:'stop'}]}]};
const state=createTimelineState(WrapMode.Loop);state.playing=true;
const calls:string[]=[],particle={reset:()=>calls.push('reset'),play:()=>calls.push('play'),stop:()=>calls.push('stop')};
const deps:SampleDeps={world:{} as SampleDeps['world'],getComponent:()=>undefined,resolveChild:resolveRoot};
advanceTimelineTS(asset,ROOT,state,.1,{deps,particle});
advanceTimelineTS(asset,ROOT,state,.1,{deps,particle});
expect(calls).toEqual(['reset','play']);
advanceTimelineTS(asset,ROOT,state,.4,{deps,particle});
expect(calls).toEqual(['reset','play','stop']);
advanceTimelineTS(asset,ROOT,state,.5,{deps,particle});
expect(calls).toEqual(['reset','play','stop','reset','play']);
});
});