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
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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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+ });+});