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 {
wrapModeFromName,
TrackType,
TIMELINE_FORMAT_VERSION,
type TimelineAsset,
type Track,
type PropertyTrack,
type SpineTrack,
type SpriteAnimTrack,
type AudioTrack,
type ParticleTrack,
type ActivationTrack,
type MarkerTrack,
type CustomEventTrack,
type AnimFramesTrack,
type CameraTrack,
type SequenceTrack,
} from './TimelineTypes';
import { log } from '../util/logger';
const STEP_TANGENT_THRESHOLD = 1e5;
type MigrationFn = (raw: any) => void;
const MIGRATIONS: [string, string, MigrationFn][] = [
['1.0', '1.1', (raw: any) => {
for (const track of raw.tracks ?? []) {
if (track.type === TrackType.Property) {
for (const ch of track.channels ?? []) {
for (const kf of ch.keyframes ?? []) {
if (kf.interpolation) continue;
if (Math.abs(kf.outTangent) >= STEP_TANGENT_THRESHOLD) {
kf.interpolation = 'step';
kf.outTangent = 0;
}
}
}
}
}
}],
// `rotation.z` named the Z EULER angle, not the quaternion's z component —
// the name a 3D rotation channel needs. The angle keeps its meaning under
// the name that says so, and a document written before this reads the same.
['1.1', '1.2', (raw: any) => {
for (const track of raw.tracks ?? []) {
if (track.type !== TrackType.Property) continue;
for (const ch of track.channels ?? []) {
if (ch.property === 'rotation.z') ch.property = 'rotation.angle';
}
}
}],
// Camera and sequence tracks arrived without changing what an older document means.
['1.2', '1.3', () => undefined],
];
function migrateAsset(raw: any): void {
let version = raw.version ?? '1.0';
for (const [from, to, fn] of MIGRATIONS) {
if (version === from) {
fn(raw);
version = to;
}
}
raw.version = TIMELINE_FORMAT_VERSION;
}
const finite = (v: unknown, fallback: number): number => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
function parseTrack(raw: any): Track {
const base = {
name: raw.name ?? '',
childPath: raw.childPath ?? '',
};
switch (raw.type) {
case TrackType.Property:
return {
...base,
type: TrackType.Property,
component: raw.component ?? '',
channels: (raw.channels ?? []).map((ch: any) => ({
property: ch.property,
// Default missing tangents to 0: a hand-authored keyframe without
// them hits the Hermite evaluator path where `undefined * dt` is
// NaN, poisoning the animated field.
keyframes: (ch.keyframes ?? []).map((kf: any) => ({
...kf,
inTangent: kf.inTangent ?? 0,
outTangent: kf.outTangent ?? 0,
})),
})),
} as PropertyTrack;
case TrackType.Spine:
return {
...base,
type: TrackType.Spine,
clips: raw.clips ?? [],
blendIn: raw.blendIn ?? 0,
} as SpineTrack;
case TrackType.SpriteAnim:
return {
...base,
type: TrackType.SpriteAnim,
clip: raw.clip ?? '',
startTime: raw.startTime ?? 0,
} as SpriteAnimTrack;
case TrackType.Audio:
return {
...base,
type: TrackType.Audio,
events: raw.events ?? [],
} as AudioTrack;
case TrackType.Activation:
return {
...base,
type: TrackType.Activation,
ranges: raw.ranges ?? [],
} as ActivationTrack;
case TrackType.Marker:
return {
...base,
type: TrackType.Marker,
markers: raw.markers ?? [],
} as MarkerTrack;
case TrackType.Particle:
return { ...base, type: TrackType.Particle, events: (raw.events ?? []).filter((e: any) =>
Number.isFinite(e.time) && e.time >= 0 && ['play', 'stop', 'reset'].includes(e.action))
.map((e: any) => ({ time: e.time, action: e.action })) } as ParticleTrack;
case TrackType.CustomEvent:
return {
...base,
type: TrackType.CustomEvent,
events: (raw.events ?? []).map((e: any) => ({
time: e.time ?? 0,
name: e.name ?? '',
payload: e.payload ?? {},
})),
} as CustomEventTrack;
case TrackType.AnimFrames:
return {
...base,
type: TrackType.AnimFrames,
frames: (raw.animFrames ?? []).map((f: any) => ({
texture: f.texture ?? '',
duration: f.duration,
})),
} as AnimFramesTrack;
case TrackType.Camera:
return {
...base,
childPath: '',
type: TrackType.Camera,
clips: (raw.clips ?? []).map((c: any) => ({
start: finite(c.start, 0),
duration: Math.max(0, finite(c.duration, 0)),
camera: typeof c.camera === 'string' ? c.camera : '',
...(typeof c.curve === 'number' ? { curve: c.curve } : {}),
})),
} as CameraTrack;
case TrackType.Sequence:
return {
...base,
childPath: '',
type: TrackType.Sequence,
clips: (raw.clips ?? []).map((c: any) => ({
start: finite(c.start, 0),
duration: Math.max(0, finite(c.duration, 0)),
timeline: typeof c.timeline === 'string' ? c.timeline : '',
root: typeof c.root === 'string' ? c.root : '',
speed: finite(c.speed, 1) || 1,
loop: c.loop === true,
})),
} as SequenceTrack;
default:
log.warn('timeline', `Unknown track type: ${raw.type}, skipping`);
return null as any;
}
}
export function parseTimelineAsset(rawJson: unknown): TimelineAsset {
const raw = (rawJson ?? {}) as Record<string, any>;
migrateAsset(raw);
return {
version: TIMELINE_FORMAT_VERSION,
type: 'timeline',
duration: raw.duration ?? 0,
wrapMode: wrapModeFromName(raw.wrapMode),
tracks: (raw.tracks ?? []).map(parseTrack).filter((t: Track | null) => t !== null),
};
}
export interface TimelineAssetPaths {
audio: string[];
animClips: string[];
textures: string[];
/** The timelines its sequence clips play. */
timelines: string[];
}
export function extractTimelineAssetPaths(asset: TimelineAsset): TimelineAssetPaths {
const audio = new Set<string>();
const animClips = new Set<string>();
const textures = new Set<string>();
const timelines = new Set<string>();
for (const track of asset.tracks) {
if (track.type === TrackType.Audio) {
for (const event of track.events) {
audio.add(event.clip);
}
} else if (track.type === TrackType.SpriteAnim) {
if (track.clip) {
animClips.add(track.clip);
}
} else if (track.type === TrackType.Sequence) {
for (const clip of track.clips) if (clip.timeline) timelines.add(clip.timeline);
} else if (track.type === TrackType.AnimFrames) {
for (const frame of track.frames) {
if (frame.texture) {
textures.add(frame.texture);
}
}
}
}
return {
audio: Array.from(audio),
animClips: Array.from(animClips),
textures: Array.from(textures),
timelines: Array.from(timelines),
};
}