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.

refactor(assets): an invalidation says what kind of asset ended

esengineafc370c55213
diff --git a/docs/astro/src/content/docs/publishing/hot-update.mdx b/docs/astro/src/content/docs/publishing/hot-update.mdx
index c7f307c42..21e3e5e84 100644
--- a/docs/astro/src/content/docs/publishing/hot-update.mdx
+++ b/docs/astro/src/content/docs/publishing/hot-update.mdx
@@ -208,17 +208,24 @@ the download and swap.
When a scene references an asset by `@uuid` and that asset lives in a remote
group, `applyUpdate` does **everything** — it downloads the new bytes, swaps the
-manifest, and the built-in rebinder replaces the old texture in every live
-`Sprite` and `MeshRenderer` on screen. The picture changes on its own; the scene author
-writes nothing. (The `hot-update-demo` example's game code is literally empty.)
+manifest, and the built-in rebinder replaces the old texture in **every live field
+that declares one** — built-in (`Sprite.texture`, `MeshRenderer.texture` /
+`.normalMap`, `UIVisual.texture`, `TilemapLayer.tileset`,
+`ParticleEmitter.texture`, `TrailRenderer.texture`) and your own components
+alike, as long as the field is declared in `assetFields`. The picture changes on
+its own; the scene author writes nothing. (The `hot-update-demo` example's game
+code is literally empty.)
For anything the built-in rebinder doesn't cover — a texture you bound manually, a
sound, a custom system — subscribe to `onInvalidate` and rebind yourself:
```ts
-const unsub = assets.onInvalidate((ref) => {
- // `ref` was just invalidated by an update — reload it and rebind wherever you use it.
- void assets.loadTexture(ref).then((tex) => { /* assign tex.handle */ });
+const unsub = assets.onInvalidate((event) => {
+ // `event.ref` was just invalidated by an update. `event.type` says what kind of
+ // asset it was ('texture', 'audio', 'material', …) and `event.oldValue` what live
+ // holders were bound to before the drop (a texture's handle).
+ if (event.type !== 'texture') return;
+ void assets.loadTexture(event.ref).then((tex) => { /* assign tex.handle */ });
});
```
@@ -233,7 +240,7 @@ The hot-update surface lives on the `Assets` resource (`Res(Assets)`):
| `restorePersistedUpdate(key)` | `boolean` | At boot, restore the manifest a prior `applyUpdate` persisted under `key`. The runtime calls this for you when `persistUpdateKey` is set. |
| `setRemoteRoot(url?)` | `void` | Point remote-group resolution at a CDN root (`undefined` clears it → same-origin). The runtime sets this from the build's `remoteRoot`. |
| `remoteRoot` | `string \| undefined` | The active CDN root (getter). |
-| `onInvalidate(listener)` | `() => void` | Subscribe to per-ref invalidations (for custom rebinding). Returns an unsubscribe function. |
+| `onInvalidate(listener)` | `() => void` | Subscribe to invalidations. The listener receives `{ ref, type, oldValue }` (for custom rebinding); returns an unsubscribe function. |
| `loadGroup(name, onProgress?)` | `Promise<AssetBundle>` | Load a whole group on demand (the DLC pattern — see below). |
| `releaseGroup(name)` | `void` | Release everything `loadGroup(name)` acquired. |
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx
index 4051285dc..0df46e646 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx
@@ -164,14 +164,17 @@ const checkForUpdates = defineSystem([Res(Assets)], (assets) => {
### 零代码重绑
-当场景以 `@uuid` 引用某个资产、而该资产位于远端组时,`applyUpdate` 会**全部搞定**——它下载新字节、切换清单,内建重绑器随即把旧贴图换进屏幕上每一个运行中的 `Sprite` 与 `MeshRenderer`。画面自行改变,场景作者什么都不用写。(`hot-update-demo` 示例的游戏代码字面上是空的。)
+当场景以 `@uuid` 引用某个资产、而该资产位于远端组时,`applyUpdate` 会**全部搞定**——它下载新字节、切换清单,内建重绑器随即把旧贴图换进**每一个声明了该资产的运行中字段**:内建的(`Sprite.texture`、`MeshRenderer.texture` / `.normalMap`、`UIVisual.texture`、`TilemapLayer.tileset`、`ParticleEmitter.texture`、`TrailRenderer.texture`)与你自己的组件一视同仁,只要字段写在 `assetFields` 里。画面自行改变,场景作者什么都不用写。(`hot-update-demo` 示例的游戏代码字面上是空的。)
对于内建重绑器覆盖不到的东西——你手动绑定的贴图、一段音效、一个自定义系统——订阅 `onInvalidate` 自行重绑:
```ts
-const unsub = assets.onInvalidate((ref) => {
- // `ref` 刚被一次更新失效——重新加载它,并在你用到它的地方重绑。
- void assets.loadTexture(ref).then((tex) => { /* 赋值 tex.handle */ });
+const unsub = assets.onInvalidate((event) => {
+ // `event.ref` 刚被一次更新失效。`event.type` 说明它是哪一类资产
+ // ('texture'、'audio'、'material' …),`event.oldValue` 是丢弃前运行中的持有者
+ // 所绑定的值(贴图即句柄)。
+ if (event.type !== 'texture') return;
+ void assets.loadTexture(event.ref).then((tex) => { /* 赋值 tex.handle */ });
});
```
@@ -186,7 +189,7 @@ const unsub = assets.onInvalidate((ref) => {
| `restorePersistedUpdate(key)` | `boolean` | 在启动时,恢复上一次 `applyUpdate` 以 `key` 持久化的清单。设了 `persistUpdateKey` 时运行时会替你调用。 |
| `setRemoteRoot(url?)` | `void` | 把远端组解析指向某个 CDN 根地址(`undefined` 清除 → 同源)。运行时会从构建的 `remoteRoot` 设置它。 |
| `remoteRoot` | `string \| undefined` | 当前 CDN 根地址(getter)。 |
-| `onInvalidate(listener)` | `() => void` | 订阅逐引用的失效(用于自定义重绑)。返回一个取消订阅的函数。 |
+| `onInvalidate(listener)` | `() => void` | 订阅失效事件。监听器收到 `{ ref, type, oldValue }`(用于自定义重绑);返回一个取消订阅的函数。 |
| `loadGroup(name, onProgress?)` | `Promise<AssetBundle>` | 按需加载整个组(DLC 模式——见下文)。 |
| `releaseGroup(name)` | `void` | 释放 `loadGroup(name)` 获取的一切。 |
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index dc9ee2208..c21815fd7 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { Backend } from './Backend';
import { Catalog, type AtlasFrameInfo } from './Catalog';
-import { ManifestModel, normalizeBundleMode, type AddressableManifest } from './AddressableManifest';
+import { ManifestModel, normalizeBundleMode, type AddressableManifest, type AddressableAssetType } from './AddressableManifest';
import { diffManifests, type UpdatePlan, type AssetChange } from './hotUpdate';
import { contentHashHex } from './contentHash';
import { platformLoadSubpackage, platformGetStorageItem, platformSetStorageItem, platformWriteCacheFile } from '../platform';
@@ -43,7 +43,7 @@ import { getComponentDefaults } from '../ecs/component';
import { getComponentAssetFieldDescriptors } from '../scene/scene';
import { discoverSceneAssets } from './discoverAssets';
import { fetchDecodePixels } from './imageDecode';
-import type { SceneData } from '../scene/scene';
+import type { SceneData, AssetFieldType } from '../scene/scene';
import { SceneHandle, type ReleaseCallback } from './SceneHandle';
import type { AssetRegistry } from './AssetRegistry';
import { UUID_REF_PREFIX } from './AssetRegistry';
@@ -51,10 +51,27 @@ import type { AssetRefCounter } from './AssetRefCounter';
import { log } from '../util/logger';
import { recoverDevice, finishDeviceRecovery } from '../render/renderer';
-/** Callback fired when `Assets.invalidate(ref)` actually dropped cache entries.
- * `oldTextureHandle` is the texture handle that was bound before the drop (0 when
- * none / not a texture) — the built-in rebinder swaps it to the reloaded handle. */
-export type InvalidateListener = (ref: string, oldTextureHandle?: number) => void;
+/**
+ * One asset generation ending: which ref, what kind of asset it was, and what
+ * live holders were bound to just before the drop.
+ *
+ * The kind travels because every source of one knows it, and a listener that
+ * has to guess can only serve the kind somebody had in mind.
+ */
+export interface AssetInvalidation {
+ /** As the caller spelled it, not the resolved path. */
+ readonly ref: string;
+ /** In whichever vocabulary the source knew: a loader/field type, or the
+ * manifest's type for an applied update. */
+ readonly type: AssetFieldType | AddressableAssetType;
+ /** What holders were bound to: a texture's handle, a loader's value.
+ * Undefined when nothing was cached to report. */
+ readonly oldValue?: unknown;
+}
+
+/** Callback fired when an asset generation ends — `Assets.invalidate(ref)`
+ * dropped cache entries, or `applyUpdate` replaced the content behind a ref. */
+export type InvalidateListener = (event: AssetInvalidation) => void;
/** Input to {@link Assets.checkForUpdate}. */
export interface CheckForUpdateOptions {
@@ -926,7 +943,9 @@ export class Assets {
}
if (pending.remoteRoot != null) this.setRemoteRoot(pending.remoteRoot);
this.setManifest(pending.model);
- for (const c of changed) this.fireInvalidate_(c.key, oldHandles.get(c.key) ?? 0);
+ // The manifest record already says what kind each changed asset is; the
+ // notification carries it rather than collapsing to "maybe a texture".
+ for (const c of changed) this.fireInvalidate_({ ref: c.key, type: c.type, oldValue: oldHandles.get(c.key) });
this.persistActiveManifest_(pending.manifestJson);
this.pendingUpdate_ = null;
return { ok: true, updated: changed.length, failed: [] };
@@ -1539,6 +1558,9 @@ export class Assets {
// it, so a rebind listener can swap it in live components (hot update).
const oldTextureHandle = this.textureCache_.get(this.textureCacheKey_(path, true))?.handle ?? 0;
let hit = false;
+ // What each kind of cache was holding for this path, so the event says
+ // which kind ended rather than leaving a listener to infer it.
+ const dropped = new Map<AssetFieldType | AddressableAssetType, unknown>();
// Textures: cache_key has a flip flag suffix, so check both. The C++
// pool's residency identity is severed too — an evictable entry under
@@ -1546,7 +1568,7 @@ export class Assets {
const rm = getResourceManager();
for (const flip of [true, false]) {
const key = this.textureCacheKey_(path, flip);
- if (this.textureCache_.invalidate(key)) hit = true;
+ if (this.textureCache_.invalidate(key)) { hit = true; dropped.set('texture', oldTextureHandle); }
// The ledger is NOT dropped: holders of the outgoing generation
// still owe a release, and forgetting them is what stranded their
// texture with nobody able to free it. Its era ends here, though —
@@ -1554,13 +1576,14 @@ export class Assets {
// hands back a numerically equal handle.
this.textureRefs_.supersede(key);
if (typeof rm?.invalidateTexturePath === 'function') {
- if (rm.invalidateTexturePath(key)) hit = true;
+ if (rm.invalidateTexturePath(key)) { hit = true; dropped.set('texture', oldTextureHandle); }
}
}
// Generic caches: material / font / anim-clip / tilemap / timeline / audio / prefab.
for (const [type, cache] of this.genericCache_.entries()) {
- if (cache.invalidate(path)) hit = true;
+ const bound = cache.get(path);
+ if (cache.invalidate(path)) { hit = true; dropped.set(type as AssetFieldType, bound); }
// The ledger stays: the outgoing generation's holders still owe a
// release. Its era is closed so the next acquire cannot join it.
this.genericRefs_.supersede(`${type}:${path}`);
@@ -1569,8 +1592,10 @@ export class Assets {
// Loader-owned residency (e.g. the AudioAPI warm cache) can outlive
// the Assets-level entry — sever it unconditionally so a warm-cache
// revive can never serve stale bytes after a hot reload.
- for (const loader of this.loaders_.values()) {
- if (loader.invalidate?.(path)) hit = true;
+ for (const [type, loader] of this.loaders_) {
+ if (!loader.invalidate?.(path)) continue;
+ hit = true;
+ if (!dropped.has(type as AssetFieldType)) dropped.set(type as AssetFieldType, undefined);
}
// The reverse handle→path records for this path are stale now too — a
@@ -1579,18 +1604,17 @@ export class Assets {
if (p === path) this.handleToPath_.delete(key);
}
- if (hit) this.fireInvalidate_(ref, oldTextureHandle);
+ for (const [type, oldValue] of dropped) this.fireInvalidate_({ ref, type, oldValue });
return hit;
}
- /** Fire every onInvalidate listener with `ref` (and the pre-drop texture
- * handle, when known, so a rebinder can swap it in live components). Isolates
+ /** Fire every onInvalidate listener with one generation's ending. Isolates
* throws. Shared by {@link invalidate} and {@link applyUpdate}. */
- private fireInvalidate_(ref: string, oldTextureHandle = 0): void {
+ private fireInvalidate_(event: AssetInvalidation): void {
for (const listener of this.invalidateListeners_) {
try {
- listener(ref, oldTextureHandle);
+ listener(event);
} catch (e) {
log.warn('asset', 'onInvalidate listener threw', e);
}
diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.ts
index b0046ec65..afafce364 100644
--- a/sdk/src/asset/index.ts
+++ b/sdk/src/asset/index.ts
@@ -38,7 +38,7 @@ export { Assets, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin
export { decodeImageBitmap, decodeImagePixels, imageBitmapOptions, type DecodedPixels, fetchDecodePixels } from './imageDecode';
export { AssetRefCounter, type AssetRefInfo } from './AssetRefCounter';
-export { Assets as AssetsImpl, type AssetsOptions, type AssetBundle, type SceneAssetResult, type MissingAsset, type CheckForUpdateOptions, type ApplyUpdateResult, type AssetDownloadFailure, type InvalidateListener } from './Assets';
+export { Assets as AssetsImpl, type AssetsOptions, type AssetBundle, type SceneAssetResult, type MissingAsset, type CheckForUpdateOptions, type ApplyUpdateResult, type AssetDownloadFailure, type InvalidateListener, type AssetInvalidation } from './Assets';
export { type Backend, HttpBackend, EmbeddedBackend, type HttpBackendOptions } from './Backend';
export { Catalog, atlasCatalogFields, type CatalogData, type CatalogEntry, type AtlasFrameInfo, type CookedAtlasInfo } from './Catalog';
export {
diff --git a/sdk/src/hotUpdateRebind.ts b/sdk/src/hotUpdateRebind.ts
index e9c713338..bbc2e4b30 100644
--- a/sdk/src/hotUpdateRebind.ts
+++ b/sdk/src/hotUpdateRebind.ts
@@ -28,8 +28,12 @@ export function installHotUpdateRebind(app: App, assets: Assets): void {
const pending: Array<{ ref: string; oldHandle: number }> = [];
const swaps: Array<{ oldHandle: number; newHandle: number }> = [];
- assets.onInvalidate((ref, oldTextureHandle) => {
- if (oldTextureHandle) pending.push({ ref, oldHandle: oldTextureHandle });
+ assets.onInvalidate((event) => {
+ // Textures only for now, said by reading the kind rather than by the event
+ // being unable to describe anything else.
+ if (event.type !== 'texture') return;
+ const oldHandle = typeof event.oldValue === 'number' ? event.oldValue : 0;
+ if (oldHandle) pending.push({ ref: event.ref, oldHandle });
});
app.addSystemToSchedule(Schedule.Update, defineSystem(
diff --git a/sdk/tests/assets-invalidate-event.test.ts b/sdk/tests/assets-invalidate-event.test.ts
index 653c053fc..6a6096a87 100644
--- a/sdk/tests/assets-invalidate-event.test.ts
+++ b/sdk/tests/assets-invalidate-event.test.ts
@@ -3,8 +3,8 @@
/**
* @file assets-invalidate-event.test.ts
* @brief Assets.onInvalidate subscription contract: listeners fire on
- * successful invalidations, unsubscribe works, and a throwing
- * listener doesn't starve others.
+ * successful invalidations carrying WHICH KIND of asset ended,
+ * unsubscribe works, and a throwing listener doesn't starve others.
*/
import { describe, expect, it, vi } from 'vitest';
import { Assets } from '../src/asset/Assets';
@@ -53,9 +53,12 @@ describe('Assets.onInvalidate', () => {
const hit = assets.invalidate('tex/hot.png');
expect(hit).toBe(true);
- // Fires with the original ref + the pre-drop texture handle (0 here — the
- // seeded entry is the unflipped variant; the rebinder reads flip=true).
- expect(listener).toHaveBeenCalledWith('tex/hot.png', expect.any(Number));
+ // Fires with the original ref, the KIND of asset that ended, and the value
+ // holders were bound to (0 here — the seeded entry is the unflipped
+ // variant; the rebinder reads flip=true).
+ expect(listener).toHaveBeenCalledWith({
+ ref: 'tex/hot.png', type: 'texture', oldValue: expect.any(Number),
+ });
});
it('unsubscribe function prevents further notifications', () => {
@@ -124,8 +127,9 @@ describe('Assets.onInvalidate', () => {
assets.onInvalidate(c);
assets.invalidate('tex/a.png');
- expect(a).toHaveBeenCalledWith('tex/a.png', expect.any(Number));
- expect(b).toHaveBeenCalledWith('tex/a.png', expect.any(Number));
- expect(c).toHaveBeenCalledWith('tex/a.png', expect.any(Number));
+ const event = { ref: 'tex/a.png', type: 'texture', oldValue: expect.any(Number) };
+ expect(a).toHaveBeenCalledWith(event);
+ expect(b).toHaveBeenCalledWith(event);
+ expect(c).toHaveBeenCalledWith(event);
});
});
diff --git a/sdk/tests/hot-update-rebind.test.ts b/sdk/tests/hot-update-rebind.test.ts
index ee937d916..b803fd26b 100644
--- a/sdk/tests/hot-update-rebind.test.ts
+++ b/sdk/tests/hot-update-rebind.test.ts
@@ -21,8 +21,7 @@ import { Assets } from '../src/asset/Assets';
import type { Backend } from '../src/asset/Backend';
import type { CppRegistry } from '../src/wasm';
import type { Entity } from '../src/types';
-import { registerComponent } from '../src/ecs/component';
-import { UIVisual } from '../src/ui/core/ui-visual';
+import { ensureBuiltinComponentsRegistered } from '../src/ecs/component';
import { installHotUpdateRebind } from '../src/hotUpdateRebind';
import { findLiveAssetBindings } from '../src/asset/liveAssetBindings';
@@ -108,10 +107,10 @@ function buildAssets(): Assets {
});
}
-/** UIVisual is registered by the UI plugin, whose build() this test does not run.
- * Registering it by hand is what that plugin does, and the completeness check
- * below refuses to pass while any C++-declared texture field is missing. */
-registerComponent('UIVisual', UIVisual);
+// What every SDK entry does at load: register the engine's whole component
+// catalogue. Without it the registry holds only what this test file happened to
+// import, and the completeness check below would be measuring the imports.
+ensureBuiltinComponentsRegistered();
/** Every (component, field) in the live registry that binds a texture. */
function declaredTextureFields(): Array<{ component: AnyComponentDef; field: string }> {
diff --git a/sdk/tests/hot-update-runtime.test.ts b/sdk/tests/hot-update-runtime.test.ts
index abc6f592b..05501bae4 100644
--- a/sdk/tests/hot-update-runtime.test.ts
+++ b/sdk/tests/hot-update-runtime.test.ts
@@ -130,8 +130,8 @@ describe('Assets.checkForUpdate / applyUpdate', () => {
const assets = createAssets(backend);
assets.setManifest(cdnManifest('aaaa', 'rev-1'));
assets.setRemoteRoot('https://cdn/v1');
- const rebinds: string[] = [];
- assets.onInvalidate((ref) => rebinds.push(ref));
+ const rebinds: Array<{ ref: string; type: string }> = [];
+ assets.onInvalidate((e) => rebinds.push({ ref: e.ref, type: e.type }));
await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });
const progress: [number, number][] = [];
@@ -149,7 +149,8 @@ describe('Assets.checkForUpdate / applyUpdate', () => {
expect((platform as unknown as { __cache: Map<string, ArrayBuffer> })
.__cache.get(`https://cdn/v2/assets/${REMOTE_HASH}.png`)?.byteLength).toBe(8);
// A renderer bound to the changed asset's stable key is told to rebind.
- expect(rebinds).toEqual(['uuid-1']);
+ // The manifest knew the kind; the notification carries it.
+ expect(rebinds).toEqual([{ ref: 'uuid-1', type: 'texture' }]);
expect(progress[0]).toEqual([0, 1]);
expect(progress[progress.length - 1]).toEqual([1, 1]);
});
@@ -159,8 +160,8 @@ describe('Assets.checkForUpdate / applyUpdate', () => {
const assets = createAssets(backendServing(cdnManifest('deadbeefdeadbeef', 'rev-2')));
assets.setManifest(cdnManifest('aaaa', 'rev-1'));
assets.setRemoteRoot('https://cdn/v1');
- const rebinds: string[] = [];
- assets.onInvalidate((ref) => rebinds.push(ref));
+ const rebinds: Array<{ ref: string; type: string }> = [];
+ assets.onInvalidate((e) => rebinds.push({ ref: e.ref, type: e.type }));
await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });
const result = await assets.applyUpdate();