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 type { Entity } from '../types';
import { defineResource } from '../ecs/resource';
import { createTimelineState, type TimelineState } from './TimelineDrive';
import { WrapMode, type TimelineAsset } from './TimelineTypes';
/**
* @internal How the api reaches the `TimelinePlayer` component flags. Injected
* by `TimelinePlugin` (which owns both sides, avoiding a module cycle). The
* component flags are the authoritative playback channel — the per-frame system
* reconciles them into {@link TimelineState} — so play/pause/stop must write
* through to them or they would be overwritten on the next tick.
*/
export interface PlayerFlagChannel {
/** Raise `playing` (replays from the top when the clip is finished). */
raise(entity: Entity): void;
/** Lower `playing`, keeping the clock (pause). */
lower(entity: Entity): void;
/** Lower `playing` and clear `finished` (a stopped clip is rewound, not completed). */
reset(entity: Entity): void;
}
/**
* Per-App timeline playback control. Holds this App's per-entity playback state
* and is published as the {@link Timeline} resource; game code drives playback via
* `app.getResource(Timeline)`.
*
* The timeline runtime is pure TS now — there is no
* C++ handle or wasm module here. `TimelinePlugin` advances each entity's
* {@link TimelineState} every frame; these methods flip/seek that state and
* write the play flags through to the entity's `TimelinePlayer` component.
*/
export class TimelineAPI {
private readonly states_ = new Map<Entity, TimelineState>();
private readonly codeAssets_ = new Map<string, TimelineAsset>();
private assetTimelines_: ((ref: string) => TimelineAsset | undefined) | null = null;
constructor(private readonly flags_: PlayerFlagChannel | null = null) {}
/**
* Register a timeline built in code under `name`, so a `TimelinePlayer`
* whose `timeline` is that name plays it like an authored one.
*
* Per app, like every other code registration: a name registered here is
* this app's, and it wins over an asset of the same name.
*/
registerAsset(name: string, asset: TimelineAsset): void {
this.codeAssets_.set(name, asset);
}
unregisterAsset(name: string): void {
this.codeAssets_.delete(name);
}
/** @internal Where a loaded `.estimeline` comes from: this app's realm. */
useAssetTimelines(source: (ref: string) => TimelineAsset | undefined): void {
this.assetTimelines_ = source;
}
/** What `name` plays: a code registration first, then this realm's asset. */
getAsset(name: string): TimelineAsset | undefined {
return this.codeAssets_.get(name) ?? this.assetTimelines_?.(name);
}
/** @internal Plugin ensures (creating if needed) the per-entity playback state. */
ensureState(entity: Entity, wrapMode: WrapMode, speed: number): TimelineState {
let s = this.states_.get(entity);
if (!s) {
s = createTimelineState(wrapMode, speed);
this.states_.set(entity, s);
}
return s;
}
getState(entity: Entity): TimelineState | undefined {
return this.states_.get(entity);
}
/** @internal Forget an entity's state (on despawn). */
removeState(entity: Entity): void {
this.states_.delete(entity);
}
/** @internal */
clearStates(): void {
this.states_.clear();
}
play(entity: Entity): void {
const s = this.states_.get(entity);
if (s) s.playing = true;
this.flags_?.raise(entity);
}
pause(entity: Entity): void {
const s = this.states_.get(entity);
if (s) s.playing = false;
this.flags_?.lower(entity);
}
stop(entity: Entity): void {
const s = this.states_.get(entity);
if (s) {
s.playing = false;
s.time = 0;
s.prevTime = 0;
s.phase = 0;
s.started = false;
s.spineClipIndices = {};
s.nested = {};
}
this.flags_?.reset(entity);
}
setTime(entity: Entity, time: number): void {
const s = this.states_.get(entity);
if (s) {
s.prevTime = s.time;
s.time = time;
s.phase = time;
s.started = true;
}
}
isPlaying(entity: Entity): boolean {
return this.states_.get(entity)?.playing ?? false;
}
getCurrentTime(entity: Entity): number {
return this.states_.get(entity)?.time ?? 0;
}
}
/**
* Per-App timeline control resource, published by `TimelinePlugin`. Drive
* playback as `app.getResource(Timeline).play(entity)`.
*/
export const Timeline = /* @__PURE__ */ defineResource<TimelineAPI>(null!, 'Timeline');