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.

fix(timeline): a timeline is its realm's, not whichever plugin built last

esenginef0bc57c16082
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 49d760793..564e9db7d 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 82 beta · 1505 experimental · 3 deprecated
+Symbols: 113 public · 82 beta · 1504 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -8461,12 +8461,7 @@ wrapMode: string
build: (app: App) => void
cleanup: () => void
clearHandles: () => void
-getAsset: (path: string) => TimelineAsset | undefined
-getTextureHandle: (timelinePath: string, textureUuid: string) => number
name: string
-registerAsset: (path: string, asset: TimelineAsset) => void
-registerTextureHandles: (path: string, handles: Map<string, number>) => void
-unregisterAsset: (path: string) => void
static new (): TimelinePlugin
static prototype: TimelinePlugin
```
@@ -11679,11 +11674,6 @@ PrefabsPlugin
(path: string, data: LoadedTilemapSource): void
```
-## registerTimelineAsset — function @experimental
-```
-(path: string, asset: TimelineAsset): void
-```
-
## remapComponentEntityRefs — function @experimental
```
(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index b080e8376..32b57e436 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 87 beta · 1524 experimental · 3 deprecated
+Symbols: 113 public · 87 beta · 1523 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -8654,12 +8654,7 @@ wrapMode: string
build: (app: App) => void
cleanup: () => void
clearHandles: () => void
-getAsset: (path: string) => TimelineAsset | undefined
-getTextureHandle: (timelinePath: string, textureUuid: string) => number
name: string
-registerAsset: (path: string, asset: TimelineAsset) => void
-registerTextureHandles: (path: string, handles: Map<string, number>) => void
-unregisterAsset: (path: string) => void
static new (): TimelinePlugin
static prototype: TimelinePlugin
```
@@ -11922,11 +11917,6 @@ PrefabsPlugin
(path: string, data: LoadedTilemapSource): void
```
-## registerTimelineAsset — function @experimental
-```
-(path: string, asset: TimelineAsset): void
-```
-
## remapComponentEntityRefs — function @experimental
```
(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index e4911872c..7468448aa 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1504 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1503 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -8456,12 +8456,7 @@ wrapMode: string
build: (app: App) => void
cleanup: () => void
clearHandles: () => void
-getAsset: (path: string) => TimelineAsset | undefined
-getTextureHandle: (timelinePath: string, textureUuid: string) => number
name: string
-registerAsset: (path: string, asset: TimelineAsset) => void
-registerTextureHandles: (path: string, handles: Map<string, number>) => void
-unregisterAsset: (path: string) => void
static new (): TimelinePlugin
static prototype: TimelinePlugin
```
@@ -11684,11 +11679,6 @@ PrefabsPlugin
(path: string, data: LoadedTilemapSource): void
```
-## registerTimelineAsset — function @experimental
-```
-(path: string, asset: TimelineAsset): void
-```
-
## remapComponentEntityRefs — function @experimental
```
(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 8bf4de29e..c17c4f49e 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 82 beta · 1526 experimental · 3 deprecated
+Symbols: 113 public · 82 beta · 1525 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -8702,12 +8702,7 @@ wrapMode: string
build: (app: App) => void
cleanup: () => void
clearHandles: () => void
-getAsset: (path: string) => TimelineAsset | undefined
-getTextureHandle: (timelinePath: string, textureUuid: string) => number
name: string
-registerAsset: (path: string, asset: TimelineAsset) => void
-registerTextureHandles: (path: string, handles: Map<string, number>) => void
-unregisterAsset: (path: string) => void
static new (): TimelinePlugin
static prototype: TimelinePlugin
```
@@ -11941,11 +11936,6 @@ PrefabsPlugin
(path: string, data: LoadedTilemapSource): void
```
-## registerTimelineAsset — function @experimental
-```
-(path: string, asset: TimelineAsset): void
-```
-
## remapComponentEntityRefs — function @experimental
```
(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d49a60409..e017abaa9 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 82 beta · 1516 experimental · 3 deprecated
+Symbols: 113 public · 82 beta · 1515 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -8463,12 +8463,7 @@ wrapMode: string
build: (app: App) => void
cleanup: () => void
clearHandles: () => void
-getAsset: (path: string) => TimelineAsset | undefined
-getTextureHandle: (timelinePath: string, textureUuid: string) => number
name: string
-registerAsset: (path: string, asset: TimelineAsset) => void
-registerTextureHandles: (path: string, handles: Map<string, number>) => void
-unregisterAsset: (path: string) => void
static new (): TimelinePlugin
static prototype: TimelinePlugin
```
@@ -11707,11 +11702,6 @@ PrefabsPlugin
(path: string, data: LoadedTilemapSource): void
```
-## registerTimelineAsset — function @experimental
-```
-(path: string, asset: TimelineAsset): void
-```
-
## remapComponentEntityRefs — function @experimental
```
(components: ComponentData[], idMapping: Map<PrefabEntityId, number>): void
diff --git a/sdk/src/asset/loaders/TimelineAssetLoader.ts b/sdk/src/asset/loaders/TimelineAssetLoader.ts
index 06780526c..92dce96fe 100644
--- a/sdk/src/asset/loaders/TimelineAssetLoader.ts
+++ b/sdk/src/asset/loaders/TimelineAssetLoader.ts
@@ -10,18 +10,9 @@ import type { AssetLoader, LoadContext, TimelineResult, RegistryAssetLoader } fr
import type { RegistryEra } from '../registryAssets';
import { AssetScope } from '../AssetLease';
import { parseTimelineAsset, extractTimelineAssetPaths } from '../../timeline/TimelineLoader';
-import type { TimelineAsset } from '../../timeline/TimelineTypes';
-import {
- registerTimelineAsset, registerTimelineTextureHandles, unregisterTimelineAsset, getTimelineAsset,
-} from '../../timeline/TimelineAssetRegistry';
+import type { PublishedTimeline } from '../../timeline/TimelineTypes';
import { log } from '../../util/logger';
-/** What one era publishes: the parsed asset and the handles it resolved. */
-interface PublishedTimeline {
- asset: TimelineAsset;
- textureHandles: Map<string, number>;
-}
-
export class TimelineAssetLoader implements AssetLoader<TimelineResult> {
readonly type = 'timeline';
readonly extensions = ['.estimeline'];
@@ -43,20 +34,13 @@ export class TimelineAssetLoader implements AssetLoader<TimelineResult> {
textureHandles.set(texPath, 0);
}
}
- return { published: { asset, textureHandles }, value: { timelineId: path }, dependencies };
- },
- publish: (names, published) => {
- const { asset, textureHandles } = published as PublishedTimeline;
- for (const name of names) {
- registerTimelineAsset(name, asset);
- if (textureHandles.size > 0) registerTimelineTextureHandles(name, textureHandles);
- }
- },
- unpublish: (names, published) => {
- const { asset } = published as PublishedTimeline;
- for (const name of names) {
- if (getTimelineAsset(name) === asset) unregisterTimelineAsset(name);
- }
+ const published: PublishedTimeline = { asset, textureHandles };
+ return { published, value: { timelineId: path }, dependencies };
},
+ // Nothing: the slot holds the era, and the timeline system reads it
+ // there. A module-level "active registry" answered with whichever app
+ // built its plugin last.
+ publish: () => {},
+ unpublish: () => {},
};
}
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 9882489f4..9eb24b069 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -839,7 +839,6 @@ export {
export {
TimelinePlugin,
timelinePlugin,
- registerTimelineAsset,
parseTimelineAsset,
Timeline,
TimelineAPI,
diff --git a/sdk/src/timeline/TimelineAssetRegistry.ts b/sdk/src/timeline/TimelineAssetRegistry.ts
deleted file mode 100644
index 4f237cc1c..000000000
--- a/sdk/src/timeline/TimelineAssetRegistry.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * @file TimelineAssetRegistry.ts
- * @brief Leaf seam between the timeline asset loader and TimelinePlugin.
- *
- * The loader writes parsed assets through these free functions without
- * importing TimelinePlugin — importing it would close a module cycle through
- * AssetPlugin/Assets. TimelinePlugin implements the registry and binds itself
- * active on build.
- */
-import type { TimelineAsset } from './TimelineTypes';
-
-export interface TimelineAssetRegistry {
- registerAsset(path: string, asset: TimelineAsset): void;
- /** Take a name back out — the slot that published it has no holders left. */
- unregisterAsset(path: string): void;
- getAsset(path: string): TimelineAsset | undefined;
- registerTextureHandles(path: string, handles: Map<string, number>): void;
- getTextureHandle(timelinePath: string, textureUuid: string): number;
-}
-
-let active: TimelineAssetRegistry | null = null;
-
-/** @internal TimelinePlugin binds itself on build and unbinds on cleanup. */
-export function setActiveTimelineAssetRegistry(registry: TimelineAssetRegistry | null): void {
- active = registry;
-}
-
-export function registerTimelineAsset(path: string, asset: TimelineAsset): void {
- active?.registerAsset(path, asset);
-}
-
-export function unregisterTimelineAsset(path: string): void {
- active?.unregisterAsset(path);
-}
-
-export function getTimelineAsset(path: string): TimelineAsset | undefined {
- return active?.getAsset(path);
-}
-
-export function registerTimelineTextureHandles(path: string, handles: Map<string, number>): void {
- active?.registerTextureHandles(path, handles);
-}
-
-export function getTimelineTextureHandle(timelinePath: string, textureUuid: string): number {
- return active?.getTextureHandle(timelinePath, textureUuid) ?? 0;
-}
diff --git a/sdk/src/timeline/TimelinePlugin.ts b/sdk/src/timeline/TimelinePlugin.ts
index 0c52bc3eb..7428ab13f 100644
--- a/sdk/src/timeline/TimelinePlugin.ts
+++ b/sdk/src/timeline/TimelinePlugin.ts
@@ -7,18 +7,13 @@ import { Time, type TimeData } from '../ecs/resource';
import { defineComponent, getComponent } from '../ecs/component';
import { playModeOnly } from '../ecs/env';
import { Assets } from '../asset/AssetPlugin';
-import { resolveAssetKey } from '../asset/resolveAssetKey';
import { Audio, type AudioAPI } from '../audio/Audio';
-import { wrapModeFromName, isWrapModeName, TrackType, WrapMode, type TimelineAsset, type AnimFramesTrack } from './TimelineTypes';
+import { wrapModeFromName, isWrapModeName, TrackType, WrapMode, type TimelineAsset,
+ type AnimFramesTrack, type PublishedTimeline } from './TimelineTypes';
import { Timeline, TimelineAPI } from './TimelineControl';
import { resolveChildEntity } from './TimelineRuntime';
import { advanceTimelineTS, applyPlayerFlags, latchPlayerFinish } from './TimelineDrive';
import type { SampleDeps } from './TimelineEvaluator';
-import {
- setActiveTimelineAssetRegistry,
- getTimelineTextureHandle,
- type TimelineAssetRegistry,
-} from './TimelineAssetRegistry';
import type { Entity } from '../types';
export { setNestedProperty } from './TimelineRuntime';
@@ -64,37 +59,13 @@ interface AnimFramesState {
lastFrameIndices: number[];
}
-export class TimelinePlugin implements Plugin, TimelineAssetRegistry {
+export class TimelinePlugin implements Plugin {
name = 'timeline';
- private loadedAssets_ = new Map<string, TimelineAsset>();
- private textureHandles_ = new Map<string, Map<string, number>>();
private animFramesStates_ = new Map<number, AnimFramesState>();
private offDespawn_: (() => void) | null = null;
- registerAsset(path: string, asset: TimelineAsset): void {
- this.loadedAssets_.set(path, asset);
- }
-
- unregisterAsset(path: string): void {
- this.loadedAssets_.delete(path);
- this.textureHandles_.delete(path);
- }
-
- getAsset(path: string): TimelineAsset | undefined {
- return this.loadedAssets_.get(path);
- }
-
- registerTextureHandles(path: string, handles: Map<string, number>): void {
- this.textureHandles_.set(path, handles);
- }
-
- getTextureHandle(timelinePath: string, textureUuid: string): number {
- return this.textureHandles_.get(timelinePath)?.get(textureUuid) ?? 0;
- }
-
build(app: App): void {
- setActiveTimelineAssetRegistry(this);
const world = app.world;
// The api's play/pause/stop write through to the component flags (the
@@ -137,11 +108,14 @@ export class TimelinePlugin implements Plugin, TimelineAssetRegistry {
for (const entity of world.getEntitiesWithComponents([TimelinePlayer])) {
const player = world.get(entity, TimelinePlayer) as TimelinePlayerData;
if (!player.timeline) continue;
- // The loader keys loadedAssets_/textureHandles_ by the RESOLVED
- // path; the component holds the authored ref (see resolveAssetKey).
- const timelineKey = resolveAssetKey(assets, player.timeline);
- const asset = this.loadedAssets_.get(timelineKey) ?? this.loadedAssets_.get(player.timeline);
- if (!asset) continue;
+ // This app's realm, by the ref the component carries: the
+ // slot answers to that spelling and to the path it resolved
+ // to, so nothing here re-derives a load key.
+ const published = assets?.resolveRegistryAsset<PublishedTimeline>(
+ 'timeline', player.timeline,
+ );
+ if (!published) continue;
+ const asset = published.asset;
const wrapMode = resolveWrapMode(player.wrapMode, asset.wrapMode);
const state = tl.ensureState(entity, wrapMode, player.speed);
@@ -152,7 +126,7 @@ export class TimelinePlugin implements Plugin, TimelineAssetRegistry {
this.ensureAnimFrames(entity, asset);
const justFinished = advanceTimelineTS(asset, entity, state, time.delta, { deps, audio });
- this.processAnimFrames(world, entity, state.time, timelineKey);
+ this.processAnimFrames(world, entity, state.time, published.textureHandles);
if (latchPlayerFinish(player, state, justFinished) || rewound) {
world.insert(entity, TimelinePlayer, player);
@@ -171,9 +145,6 @@ export class TimelinePlugin implements Plugin, TimelineAssetRegistry {
this.offDespawn_?.();
this.offDespawn_ = null;
this.animFramesStates_.clear();
- this.loadedAssets_.clear();
- this.textureHandles_.clear();
- setActiveTimelineAssetRegistry(null);
}
private ensureAnimFrames(entity: Entity, asset: TimelineAsset): void {
@@ -190,7 +161,8 @@ export class TimelinePlugin implements Plugin, TimelineAssetRegistry {
}
private processAnimFrames(
- world: any, entity: Entity, currentTime: number, timelinePath: string,
+ world: any, entity: Entity, currentTime: number,
+ textureHandles: ReadonlyMap<string, number>,
): void {
const state = this.animFramesStates_.get(entity);
if (!state) return;
@@ -220,7 +192,7 @@ export class TimelinePlugin implements Plugin, TimelineAssetRegistry {
if (frameIndex !== state.lastFrameIndices[t]) {
state.lastFrameIndices[t] = frameIndex;
- const textureHandle = getTimelineTextureHandle(timelinePath, frames[frameIndex].texture);
+ const textureHandle = textureHandles.get(frames[frameIndex].texture) ?? 0;
if (textureHandle) {
const sprite = world.get(entity, Sprite);
sprite.texture = textureHandle;
diff --git a/sdk/src/timeline/TimelineTypes.ts b/sdk/src/timeline/TimelineTypes.ts
index e3dfa59cc..e90df885b 100644
--- a/sdk/src/timeline/TimelineTypes.ts
+++ b/sdk/src/timeline/TimelineTypes.ts
@@ -176,3 +176,13 @@ export interface TimelineAsset {
wrapMode: WrapMode;
tracks: Track[];
}
+
+/**
+ * One era of a `.estimeline` as its realm publishes it: the parsed asset and the
+ * texture handles it resolved. Both belong to the era — a hot update prepares a
+ * new one rather than editing this in place.
+ */
+export interface PublishedTimeline {
+ asset: TimelineAsset;
+ textureHandles: Map<string, number>;
+}
diff --git a/sdk/src/timeline/index.ts b/sdk/src/timeline/index.ts
index 1faf6fab8..f8ef88cc7 100644
--- a/sdk/src/timeline/index.ts
+++ b/sdk/src/timeline/index.ts
@@ -82,10 +82,3 @@ export {
type TimelinePlayerData,
} from './TimelinePlugin';
-export {
- registerTimelineAsset,
- getTimelineAsset,
- registerTimelineTextureHandles,
- getTimelineTextureHandle,
- type TimelineAssetRegistry,
-} from './TimelineAssetRegistry';
diff --git a/sdk/tests/realm-registry-isolation.test.ts b/sdk/tests/realm-registry-isolation.test.ts
index 93eb1ffe1..ff4bf61b6 100644
--- a/sdk/tests/realm-registry-isolation.test.ts
+++ b/sdk/tests/realm-registry-isolation.test.ts
@@ -105,6 +105,31 @@ describe('two realms in one process do not share an asset', () => {
expect(btTouches(b.app).writes).not.toContain('Sprite');
});
+ it('a timeline plays its own realm\'s asset, and one app\'s cleanup leaves the other', async () => {
+ // The worst of the three: the timeline registry was a module-level
+ // pointer at whichever plugin built LAST, and the plugin object itself
+ // is a shared singleton.
+ const timeline = (duration: number, texture: string): string => JSON.stringify({
+ version: 1, duration, tracks: [{
+ type: 'animFrames', target: '', frames: [{ texture, duration: 1 }],
+ }],
+ });
+ const a = realm(() => timeline(1, 'a.png'));
+ const b = realm(() => timeline(9, 'b.png'));
+ await a.assets.acquireTyped('timeline', 'cut/intro.estimeline');
+ await b.assets.acquireTyped('timeline', 'cut/intro.estimeline');
+
+ const inA = a.assets.resolveRegistryAsset<{ asset: { duration: number } }>('timeline', 'cut/intro.estimeline');
+ const inB = b.assets.resolveRegistryAsset<{ asset: { duration: number } }>('timeline', 'cut/intro.estimeline');
+ expect(inA?.asset.duration).toBe(1);
+ expect(inB?.asset.duration, 'both apps read whichever built its plugin last').toBe(9);
+
+ // B goes away; A is still playing.
+ b.assets.releaseAll();
+ expect(a.assets.resolveRegistryAsset('timeline', 'cut/intro.estimeline')).toBeDefined();
+ expect(b.assets.resolveRegistryAsset('timeline', 'cut/intro.estimeline')).toBeUndefined();
+ });
+
it('a code registration has no realm, and every app still sees it', async () => {
// The other half of the rule: `registerFsm('patrol', …)` is not an asset.
const { registerFsm } = await import('../src/ai/fsm/StateMachineAgent');