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
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.mdxindex 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 remotegroup, `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, asound, 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.mdxindex 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.tsindex 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 Teamimport 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.tsindex 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 './AssetPluginexport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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();