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.

feat(anim): pure-TS timeline runtime (parity, not yet wired) — REARCH_ANIMATION P4c (1/2)

esengine71810ee6a654
diff --git a/sdk/src/timeline/TimelineDrive.ts b/sdk/src/timeline/TimelineDrive.ts
new file mode 100644
index 000000000..5b3a1efb7
--- /dev/null
+++ b/sdk/src/timeline/TimelineDrive.ts
@@ -0,0 +1,140 @@
+/**
+ * @file TimelineDrive.ts
+ * @brief Pure-TS per-frame timeline runtime — the replacement for the C++
+ * TimelineSystem::advance (docs/REARCH_ANIMATION.md P4c).
+ *
+ * Holds a per-entity playback clock and, each frame: advances time (speed + wrap),
+ * samples property tracks (via the shared evaluator), and edge-detects event-track
+ * triggers (spine/audio/spriteAnim/activation) dispatching them through the shared
+ * {@link applyTimelineEvent}. The interpolation + event-detection logic is a 1:1
+ * port of TimelineSystem.cpp (evaluateChannel / advance / evaluateEventTracks) so
+ * playback matches the C++ runtime bit-for-bit and that runtime can be deleted.
+ */
+
+import { applyWrapMode, sampleTimeline, type SampleDeps, type SampleOptions } from './TimelineEvaluator';
+import { applyTimelineEvent, TimelineEventType } from './TimelineRuntime';
+import { TrackType, WrapMode, type TimelineAsset } from './TimelineTypes';
+import type { AudioAPI } from '../audio/Audio';
+import type { Entity } from '../types';
+
+/** Per-entity playback state (replaces the C++ Instance clock). */
+export interface TimelineState {
+ time: number;
+ prevTime: number;
+ playing: boolean;
+ speed: number;
+ wrapMode: WrapMode;
+ /** Per spine event-track (keyed by track index in asset.tracks): current clip, or -1. */
+ spineClipIndices: Record<number, number>;
+}
+
+export function createTimelineState(wrapMode: WrapMode = WrapMode.Once, speed = 1): TimelineState {
+ return { time: 0, prevTime: 0, playing: false, speed, wrapMode, spineClipIndices: {} };
+}
+
+export interface FiredEvent {
+ kind: number; // TimelineEventType
+ entity: Entity;
+ intParam: number; // loop / active
+ floatParam: number; // clip speed / volume
+ str: string; // animation / clip path
+}
+
+/**
+ * Edge-detect event-track triggers fired in (prevTime, time] — a 1:1 port of
+ * TimelineSystem::evaluateEventTracks. Mutates `state.spineClipIndices`.
+ */
+export function detectTimelineEvents(
+ asset: TimelineAsset, state: TimelineState,
+ resolveChild: (root: Entity, childPath: string) => Entity | null, root: Entity,
+): FiredEvent[] {
+ const out: FiredEvent[] = [];
+ const { time, prevTime } = state;
+
+ for (let i = 0; i < asset.tracks.length; i++) {
+ const track = asset.tracks[i];
+ if (track.type === TrackType.Property || track.type === TrackType.AnimFrames) continue;
+
+ const target = resolveChild(root, track.childPath);
+ if (target == null) continue;
+
+ switch (track.type) {
+ case TrackType.Spine: {
+ let currentClip = -1;
+ for (let ci = track.clips.length - 1; ci >= 0; ci--) {
+ const c = track.clips[ci];
+ if (time >= c.start && time < c.start + c.duration) { currentClip = ci; break; }
+ }
+ const prevClip = state.spineClipIndices[i] ?? -1;
+ if (currentClip !== prevClip) {
+ state.spineClipIndices[i] = currentClip;
+ if (currentClip === -1) {
+ if (prevClip >= 0) out.push({ kind: TimelineEventType.SpineStop, entity: target, intParam: 0, floatParam: 0, str: '' });
+ } else {
+ const c = track.clips[currentClip];
+ out.push({ kind: TimelineEventType.SpinePlay, entity: target, intParam: c.loop ? 1 : 0, floatParam: c.speed, str: c.animation });
+ }
+ }
+ break;
+ }
+ case TrackType.SpriteAnim: {
+ if (prevTime <= track.startTime && time >= track.startTime && time > prevTime) {
+ out.push({ kind: TimelineEventType.SpriteAnimPlay, entity: target, intParam: 0, floatParam: 0, str: track.clip });
+ }
+ break;
+ }
+ case TrackType.Audio: {
+ for (const e of track.events) {
+ if (e.time > prevTime && e.time <= time) {
+ out.push({ kind: TimelineEventType.AudioPlay, entity: target, intParam: 0, floatParam: e.volume, str: e.clip });
+ }
+ }
+ break;
+ }
+ case TrackType.Activation: {
+ let active = false;
+ for (const r of track.ranges) {
+ if (time >= r.start && time < r.end) { active = true; break; }
+ }
+ out.push({ kind: TimelineEventType.ActivationSet, entity: target, intParam: active ? 1 : 0, floatParam: 0, str: '' });
+ break;
+ }
+ }
+ }
+ return out;
+}
+
+export interface AdvanceContext {
+ deps: SampleDeps;
+ audio?: AudioAPI | null;
+ /** Skip-channel filter (editor mute); forwarded to the sampler. */
+ sampleOpts?: SampleOptions;
+ /** Side-effect hook after a property field is applied (e.g. UIRect anim flags). */
+ onPropertyApplied?: (entity: Entity, asset: TimelineAsset) => void;
+}
+
+/**
+ * Advance one entity's timeline by `dt`. Mirrors TimelineSystem::advance: clock +
+ * wrap, sample property tracks, edge-detect + dispatch events. Returns true when
+ * the clip just stopped (Once reached its end), so the caller can flip `playing`.
+ */
+export function advanceTimelineTS(
+ asset: TimelineAsset, root: Entity, state: TimelineState, dt: number, ctx: AdvanceContext,
+): boolean {
+ if (!state.playing) return false;
+
+ state.prevTime = state.time;
+ const advanced = state.time + dt * state.speed;
+ const wrapped = applyWrapMode(advanced, asset.duration, state.wrapMode);
+ state.time = wrapped.time;
+
+ sampleTimeline(asset, state.time, root, ctx.deps, ctx.sampleOpts);
+ ctx.onPropertyApplied?.(root, asset);
+
+ for (const e of detectTimelineEvents(asset, state, ctx.deps.resolveChild, root)) {
+ applyTimelineEvent(ctx.deps.world, ctx.audio ?? null, e.kind, e.entity, e.intParam, e.floatParam, e.str);
+ }
+
+ if (wrapped.stopped) state.playing = false;
+ return wrapped.stopped;
+}
diff --git a/sdk/src/timeline/TimelineRuntime.ts b/sdk/src/timeline/TimelineRuntime.ts
index d132d1ffc..b680cd6df 100644
--- a/sdk/src/timeline/TimelineRuntime.ts
+++ b/sdk/src/timeline/TimelineRuntime.ts
@@ -106,75 +106,84 @@ function decodeEventString(module: ESEngineModule, index: number): string {
return sharedTextDecoder.decode(bytes);
}
-export function processTimelineEvents(world: any, module: ESEngineModule, audio: AudioAPI | null = null): void {
- const count = module._tl_getEventCount();
- for (let i = 0; i < count; i++) {
- const type = module._tl_getEventType(i);
- const entity = module._tl_getEventEntity(i);
-
- switch (type) {
- case TimelineEventType.SpinePlay: {
- const animName = decodeEventString(module, i);
- const loop = module._tl_getEventIntParam(i) !== 0;
- if (world.has(entity, SpineAnimation)) {
- const current = world.get(entity, SpineAnimation);
- current.animation = animName;
- current.playing = true;
- current.loop = loop;
- world.set(entity, SpineAnimation, current);
- }
- break;
+/**
+ * Apply ONE decoded timeline event to the world (component mutations / audio).
+ * Shared by the legacy C++-poll path ({@link processTimelineEvents}) and the
+ * pure-TS runtime (TimelineDrive) so the dispatch lives in one place
+ * (docs/REARCH_ANIMATION.md P4c).
+ */
+export function applyTimelineEvent(
+ world: any, audio: AudioAPI | null,
+ type: number, entity: Entity,
+ intParam: number, floatParam: number, str: string,
+): void {
+ switch (type) {
+ case TimelineEventType.SpinePlay: {
+ if (world.has(entity, SpineAnimation)) {
+ const current = world.get(entity, SpineAnimation);
+ current.animation = str;
+ current.playing = true;
+ current.loop = intParam !== 0;
+ world.set(entity, SpineAnimation, current);
}
- case TimelineEventType.SpineStop: {
- if (world.has(entity, SpineAnimation)) {
- const current = world.get(entity, SpineAnimation);
- current.playing = false;
- world.set(entity, SpineAnimation, current);
- }
- break;
+ break;
+ }
+ case TimelineEventType.SpineStop: {
+ if (world.has(entity, SpineAnimation)) {
+ const current = world.get(entity, SpineAnimation);
+ current.playing = false;
+ world.set(entity, SpineAnimation, current);
}
- case TimelineEventType.SpriteAnimPlay: {
- const clipName = decodeEventString(module, i);
- if (world.has(entity, SpriteAnimator)) {
- const current = world.get(entity, SpriteAnimator);
- world.insert(entity, SpriteAnimator, {
- ...current,
- clip: clipName,
- playing: true,
- });
- }
- break;
+ break;
+ }
+ case TimelineEventType.SpriteAnimPlay: {
+ if (world.has(entity, SpriteAnimator)) {
+ const current = world.get(entity, SpriteAnimator);
+ world.insert(entity, SpriteAnimator, { ...current, clip: str, playing: true });
}
- case TimelineEventType.AudioPlay: {
- const clipPath = decodeEventString(module, i);
- const volume = module._tl_getEventFloatParam(i);
- if (clipPath && audio) {
- audio.playSFX(clipPath, { volume });
- }
- break;
+ break;
+ }
+ case TimelineEventType.AudioPlay: {
+ if (str && audio) audio.playSFX(str, { volume: floatParam });
+ break;
+ }
+ case TimelineEventType.ActivationSet: {
+ const active = intParam !== 0;
+ if (world.has(entity, SpineAnimation)) {
+ const current = world.get(entity, SpineAnimation);
+ current.enabled = active;
+ world.set(entity, SpineAnimation, current);
}
- case TimelineEventType.ActivationSet: {
- const active = module._tl_getEventIntParam(i) !== 0;
- if (world.has(entity, SpineAnimation)) {
- const current = world.get(entity, SpineAnimation);
- current.enabled = active;
- world.set(entity, SpineAnimation, current);
- }
- if (world.has(entity, SpriteAnimator)) {
- const current = world.get(entity, SpriteAnimator);
- world.insert(entity, SpriteAnimator, { ...current, enabled: active });
- }
- const Sprite = getComponent('Sprite');
- if (Sprite && world.has(entity, Sprite)) {
- const current = world.get(entity, Sprite);
- world.set(entity, Sprite, { ...current, enabled: active });
- }
- break;
+ if (world.has(entity, SpriteAnimator)) {
+ const current = world.get(entity, SpriteAnimator);
+ world.insert(entity, SpriteAnimator, { ...current, enabled: active });
+ }
+ const Sprite = getComponent('Sprite');
+ if (Sprite && world.has(entity, Sprite)) {
+ const current = world.get(entity, Sprite);
+ world.set(entity, Sprite, { ...current, enabled: active });
}
+ break;
}
}
}
+export { TimelineEventType };
+
+export function processTimelineEvents(world: any, module: ESEngineModule, audio: AudioAPI | null = null): void {
+ const count = module._tl_getEventCount();
+ for (let i = 0; i < count; i++) {
+ applyTimelineEvent(
+ world, audio,
+ module._tl_getEventType(i),
+ module._tl_getEventEntity(i) as Entity,
+ module._tl_getEventIntParam(i),
+ module._tl_getEventFloatParam(i),
+ decodeEventString(module, i),
+ );
+ }
+}
+
export function processCustomProperties(
world: any, module: ESEngineModule, uploadResult: UploadResult,
): void {
diff --git a/sdk/src/timeline/index.ts b/sdk/src/timeline/index.ts
index b9fad4abc..db04567e5 100644
--- a/sdk/src/timeline/index.ts
+++ b/sdk/src/timeline/index.ts
@@ -70,6 +70,15 @@ export {
parseAnimationClip,
} from './AnimationClip';
+export {
+ advanceTimelineTS,
+ detectTimelineEvents,
+ createTimelineState,
+ type TimelineState,
+ type FiredEvent,
+ type AdvanceContext,
+} from './TimelineDrive';
+
export {
TimelinePlugin,
timelinePlugin,
diff --git a/sdk/tests/timeline-drive.test.ts b/sdk/tests/timeline-drive.test.ts
new file mode 100644
index 000000000..486cf3f6a
--- /dev/null
+++ b/sdk/tests/timeline-drive.test.ts
@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest';
+import {
+ detectTimelineEvents,
+ advanceTimelineTS,
+ createTimelineState,
+ type TimelineState,
+} from '../src/timeline/TimelineDrive';
+import { TimelineEventType } from '../src/timeline/TimelineRuntime';
+import { WrapMode, TrackType, InterpType, type TimelineAsset } from '../src/timeline/TimelineTypes';
+import type { SampleDeps } from '../src/timeline/TimelineEvaluator';
+
+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('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
+ });
+});