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
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.mdindex 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: stringbuild: (app: App) => voidcleanup: () => voidclearHandles: () => void-getAsset: (path: string) => TimelineAsset | undefined-getTextureHandle: (timelinePath: string, textureUuid: string) => numbername: string-registerAsset: (path: string, asset: TimelineAsset) => void-registerTextureHandles: (path: string, handles: Map<string, number>) => void-unregisterAsset: (path: string) => voidstatic new (): TimelinePluginstatic 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>): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: stringbuild: (app: App) => voidcleanup: () => voidclearHandles: () => void-getAsset: (path: string) => TimelineAsset | undefined-getTextureHandle: (timelinePath: string, textureUuid: string) => numbername: string-registerAsset: (path: string, asset: TimelineAsset) => void-registerTextureHandles: (path: string, handles: Map<string, number>) => void-unregisterAsset: (path: string) => voidstatic new (): TimelinePluginstatic 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>): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: stringbuild: (app: App) => voidcleanup: () => voidclearHandles: () => void-getAsset: (path: string) => TimelineAsset | undefined-getTextureHandle: (timelinePath: string, textureUuid: string) => numbername: string-registerAsset: (path: string, asset: TimelineAsset) => void-registerTextureHandles: (path: string, handles: Map<string, number>) => void-unregisterAsset: (path: string) => voidstatic new (): TimelinePluginstatic 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>): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: stringbuild: (app: App) => voidcleanup: () => voidclearHandles: () => void-getAsset: (path: string) => TimelineAsset | undefined-getTextureHandle: (timelinePath: string, textureUuid: string) => numbername: string-registerAsset: (path: string, asset: TimelineAsset) => void-registerTextureHandles: (path: string, handles: Map<string, number>) => void-unregisterAsset: (path: string) => voidstatic new (): TimelinePluginstatic 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>): voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: stringbuild: (app: App) => voidcleanup: () => voidclearHandles: () => void-getAsset: (path: string) => TimelineAsset | undefined-getTextureHandle: (timelinePath: string, textureUuid: string) => numbername: string-registerAsset: (path: string, asset: TimelineAsset) => void-registerTextureHandles: (path: string, handles: Map<string, number>) => void-unregisterAsset: (path: string) => voidstatic new (): TimelinePluginstatic 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>): voiddiff --git a/sdk/src/asset/loaders/TimelineAssetLoader.ts b/sdk/src/asset/loaders/TimelineAssetLoader.tsindex 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 } frimport 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.tsindex 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.tsdeleted file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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');