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 {
evaluateChannel,
applyWrapMode,
sampleTimeline,
type SampleDeps,
} from '../src/timeline/TimelineEvaluator';
import {
WrapMode,
TrackType,
InterpType,
type PropertyChannel,
type TimelineAsset,
} from '../src/timeline/TimelineTypes';
import { q } from '../src/math/quat';
function ch(keyframes: PropertyChannel['keyframes'], property = 'value'): PropertyChannel {
return { property, keyframes };
}
describe('evaluateChannel', () => {
it('returns 0 for an empty channel and the lone value for one keyframe', () => {
expect(evaluateChannel(ch([]), 1)).toBe(0);
expect(evaluateChannel(ch([{ time: 0, value: 7, inTangent: 0, outTangent: 0 }]), 5)).toBe(7);
});
it('clamps to the endpoints outside the keyframe range', () => {
const c = ch([
{ time: 1, value: 10, inTangent: 0, outTangent: 0 },
{ time: 3, value: 30, inTangent: 0, outTangent: 0 },
]);
expect(evaluateChannel(c, 0)).toBe(10);
expect(evaluateChannel(c, 5)).toBe(30);
});
it('interpolates linearly', () => {
const c = ch([
{ time: 0, value: 0, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear },
{ time: 2, value: 100, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear },
]);
expect(evaluateChannel(c, 1)).toBeCloseTo(50, 5);
});
it('holds the previous value with Step interpolation', () => {
const c = ch([
{ time: 0, value: 5, inTangent: 0, outTangent: 0, interpolation: InterpType.Step },
{ time: 2, value: 99, inTangent: 0, outTangent: 0, interpolation: InterpType.Step },
]);
expect(evaluateChannel(c, 1.9)).toBe(5);
expect(evaluateChannel(c, 2)).toBe(99);
});
it('eases (easeIn = t^2 at the midpoint)', () => {
const c = ch([
{ time: 0, value: 0, inTangent: 0, outTangent: 0, interpolation: InterpType.EaseIn },
{ time: 1, value: 1, inTangent: 0, outTangent: 0, interpolation: InterpType.EaseIn },
]);
expect(evaluateChannel(c, 0.5)).toBeCloseTo(0.25, 5);
});
it('hermite passes through both keyframes', () => {
const c = ch([
{ time: 0, value: 0, inTangent: 1, outTangent: 1, interpolation: InterpType.Hermite },
{ time: 1, value: 10, inTangent: 1, outTangent: 1, interpolation: InterpType.Hermite },
]);
expect(evaluateChannel(c, 0)).toBeCloseTo(0, 5);
expect(evaluateChannel(c, 1)).toBeCloseTo(10, 5);
});
});
describe('applyWrapMode', () => {
it('Once clamps and stops past the end', () => {
expect(applyWrapMode(5, 2, WrapMode.Once)).toEqual({ time: 2, stopped: true });
expect(applyWrapMode(1, 2, WrapMode.Once)).toEqual({ time: 1, stopped: false });
});
it('Loop wraps with fmod', () => {
expect(applyWrapMode(5, 2, WrapMode.Loop)).toEqual({ time: 1, stopped: false });
});
it('PingPong reflects in the second half', () => {
expect(applyWrapMode(3, 2, WrapMode.PingPong).time).toBeCloseTo(1, 5);
});
});
// A minimal mock world keyed by a sentinel component "definition" object.
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: (root, childPath) => (childPath ? null : root),
};
}
describe('sampleTimeline', () => {
it('applies a property track to the resolved component', () => {
const defs = { Transform: { __name: 'Transform' } };
const store = new Map<string, any>([
['Transform', { position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 } }],
]);
const asset: TimelineAsset = {
version: '1.1',
type: 'timeline',
duration: 2,
wrapMode: WrapMode.Once,
tracks: [{
type: TrackType.Property,
name: 'Move',
childPath: '',
component: 'Transform',
channels: [ch([
{ time: 0, value: 0, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear },
{ time: 2, value: 100, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear },
], 'position.x')],
}],
};
sampleTimeline(asset, 1, 1 as Entity, mockDeps(store, defs));
expect(store.get('Transform').position.x).toBeCloseTo(50, 5);
});
it('skipChannel omits muted channels', () => {
const defs = { Transform: { __name: 'Transform' } };
const store = new Map<string, any>([
['Transform', { position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 } }],
]);
const asset: TimelineAsset = {
version: '1.1', type: 'timeline', duration: 2, wrapMode: WrapMode.Once,
tracks: [{
type: TrackType.Property, name: 'Move', childPath: '', component: 'Transform',
channels: [
ch([{ time: 0, value: 11, inTangent: 0, outTangent: 0 }], 'position.x'),
ch([{ time: 0, value: 22, inTangent: 0, outTangent: 0 }], 'position.y'),
],
}],
};
sampleTimeline(asset, 0, 1 as Entity, mockDeps(store, defs), {
skipChannel: (_cp, _comp, prop) => prop === 'position.y',
});
expect(store.get('Transform').position.x).toBe(11);
expect(store.get('Transform').position.y).toBe(0); // muted → untouched
});
/** A one-track clip on Transform, its channels given by the caller. */
const rotationClip = (channels: PropertyChannel[]): TimelineAsset => ({
version: '1.2',
type: 'timeline',
duration: 1,
wrapMode: WrapMode.Once,
tracks: [{
type: TrackType.Property, name: 'Spin', childPath: '', component: 'Transform', channels,
}],
});
it('rotation.angle writes a half-angle quaternion (matches the C++ runtime)', () => {
const defs = { Transform: { __name: 'Transform' } };
const store = new Map<string, any>([
['Transform', { position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 } }],
]);
const angle = Math.PI / 2; // 90°
const asset = rotationClip([ch([{ time: 0, value: angle, inTangent: 0, outTangent: 0 }], 'rotation.angle')]);
sampleTimeline(asset, 0, 1 as Entity, mockDeps(store, defs));
const rot = store.get('Transform').rotation;
expect(rot.w).toBeCloseTo(Math.cos(angle / 2), 5);
expect(rot.z).toBeCloseTo(Math.sin(angle / 2), 5);
expect(rot.x).toBeCloseTo(0, 5);
expect(rot.y).toBeCloseTo(0, 5);
});
it('rotation.angle keeps the other two axes — a clip cannot flatten a pose', () => {
const defs = { Transform: { __name: 'Transform' } };
// Pitched 30° about X, the pose an imported model arrives with.
const pitch = { w: Math.cos(Math.PI / 12), x: Math.sin(Math.PI / 12), y: 0, z: 0 };
const store = new Map<string, any>([['Transform', { rotation: { ...pitch } }]]);
const asset = rotationClip([ch([{ time: 0, value: Math.PI / 2, inTangent: 0, outTangent: 0 }], 'rotation.angle')]);
sampleTimeline(asset, 0, 1 as Entity, mockDeps(store, defs));
const [ex, ey, ez] = q.toEuler(store.get('Transform').rotation);
expect(ex).toBeCloseTo(30, 4);
expect(ey).toBeCloseTo(0, 4);
expect(ez).toBeCloseTo(90, 4);
});
it('the four components interpolate to a unit quaternion', () => {
const defs = { Transform: { __name: 'Transform' } };
const store = new Map<string, any>([['Transform', { rotation: { w: 1, x: 0, y: 0, z: 0 } }]]);
// Identity → 90° about Y, sampled at the midpoint. Component-wise that
// lands at length ~0.924; normalized it is the 45° turn slerp gives.
const kf = (time: number, value: number) => ({ time, value, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear });
const half = Math.SQRT1_2;
const asset = rotationClip([
ch([kf(0, 0), kf(1, 0)], 'rotation.x'),
ch([kf(0, 0), kf(1, half)], 'rotation.y'),
ch([kf(0, 0), kf(1, 0)], 'rotation.z'),
ch([kf(0, 1), kf(1, half)], 'rotation.w'),
]);
sampleTimeline(asset, 0.5, 1 as Entity, mockDeps(store, defs));
const rot = store.get('Transform').rotation;
expect(Math.hypot(rot.w, rot.x, rot.y, rot.z)).toBeCloseTo(1, 6);
expect(q.toEuler(rot)[1]).toBeCloseTo(45, 1);
});
});