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
feat(assets): @uuid scene refs to remote assets hot-update (model-2)
yhha18e998b4526
diff --git a/examples/hot-update-demo/README.md b/examples/hot-update-demo/README.mdindex eea4d164c..cffb2d82d 100644--- a/examples/hot-update-demo/README.md+++ b/examples/hot-update-demo/README.md@@ -29,10 +29,13 @@ Nothing is ever overwritten, so a cache can never go stale.```(The legacy `remote/<name>/` / `subpackages/<name>/` folder names still work as azero-config default when there is no `asset-groups.json`.)-- **`src/systems/hotUpdate.ts`** — on start, calls `Assets.loadGroup('cdn')` to- fetch the remote texture and stamps its handle onto the display sprite. It also- subscribes to `Assets.onInvalidate` so that when an update lands, it reloads the- group and the sprite follows.+- **`assets/scenes/main.esscene`** — the Display sprite references the texture by+ an ordinary `@uuid`. The asset lives in a `remote` group, so the runtime routes+ that `@uuid` to the CDN automatically — the scene author does nothing special.+- **`src/systems/hotUpdate.ts`** — subscribes to `Assets.onInvalidate`, so when an+ update lands the changed asset is reloaded (now resolved to the CDN) and the+ sprite follows. (A game can also `Assets.loadGroup(name)` to pull a whole remote+ group on demand — the DLC pattern.)- **The update** — call `Assets.checkForUpdate({ manifestUrl, remoteRoot })` todiff the CDN's manifest against the running one, then `Assets.applyUpdate()` todownload the changed assets and swap the manifest. Existing handles bound to adiff --git a/examples/hot-update-demo/assets/scenes/main.esscene b/examples/hot-update-demo/assets/scenes/main.essceneindex dfa9356ac..4abc0126d 100644--- a/examples/hot-update-demo/assets/scenes/main.esscene+++ b/examples/hot-update-demo/assets/scenes/main.esscene@@ -21,7 +21,7 @@"visible": true,"components": [{ "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },- { "type": "Sprite", "data": { "size": { "x": 4000, "y": 4000 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 } } },+ { "type": "Sprite", "data": { "size": { "x": 4000, "y": 4000 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "texture": "@uuid:a1b2c3d4-0002-4002-8002-000000000002" } },{ "type": "HotDisplay", "data": {} }]}diff --git a/examples/hot-update-demo/src/systems/hotUpdate.ts b/examples/hot-update-demo/src/systems/hotUpdate.tsindex 4ee5e0bee..d981755ec 100644--- a/examples/hot-update-demo/src/systems/hotUpdate.ts+++ b/examples/hot-update-demo/src/systems/hotUpdate.ts@@ -1,10 +1,8 @@import { defineSystem, Query, Mut, Res, Assets, Sprite } from 'esengine';import { HotDisplay } from '../components';-// The texture handle currently loaded from the `cdn` remote group. The system-// stamps it onto the display sprite every frame, so when a hot update reloads-// the group into a NEW handle, the sprite follows automatically.-let cdnHandle = 0;+// The texture handle to stamp onto the display sprite after a hot update.+let handle = 0;let started = false;export const hotDisplaySystem = defineSystem(@@ -12,21 +10,17 @@ export const hotDisplaySystem = defineSystem((query, assets) => {if (!started) {started = true;- // Load the single texture in the `cdn` remote group. Re-run on every- // hot update: after applyUpdate the manifest points `cdn` at the new- // content-addressed url, so this fetches the fresh bytes.- const load = (): void => {- void assets.loadGroup('cdn').then((bundle) => {- const tex = [...bundle.textures.values()][0];- if (tex) cdnHandle = tex.handle;- });- };- load();- // A hot update (checkForUpdate → applyUpdate) fires onInvalidate.- assets.onInvalidate(load);+ // The Display sprite references its texture by @uuid in the scene, so it+ // shows the shipped (green) art immediately — the texture lives in a+ // `remote` group but the reference is an ordinary @uuid. On a hot update,+ // applyUpdate invalidates the changed asset by that ref; reload it — now+ // the manifest routes the @uuid to the CDN — and the sprite follows.+ assets.onInvalidate((ref) => {+ void assets.loadTexture(ref).then((tex) => { handle = tex.handle; });+ });}- if (cdnHandle !== 0) {- for (const [, sprite] of query) sprite.texture = cdnHandle;+ if (handle !== 0) {+ for (const [, sprite] of query) sprite.texture = handle;}},{ name: 'HotDisplaySystem' },diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 537f97428..06cf851f6 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -3645,6 +3645,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | nullgroup: (name: string) => AddressableManifestGroup | nullgroupNames: () => string[]groupsByMode: (mode: BundleMode) => string[]+remoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | nullstatic empty: () => ManifestModeldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 22d0afd9d..50f74c36b 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -3640,6 +3640,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | nullgroup: (name: string) => AddressableManifestGroup | nullgroupNames: () => string[]groupsByMode: (mode: BundleMode) => string[]+remoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | nullstatic empty: () => ManifestModeldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 3cf74883f..e5099f7c7 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -3647,6 +3647,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | nullgroup: (name: string) => AddressableManifestGroup | nullgroupNames: () => string[]groupsByMode: (mode: BundleMode) => string[]+remoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | nullstatic empty: () => ManifestModeldiff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.tsindex 709b35c42..518ec87a4 100644--- a/sdk/src/asset/AddressableManifest.ts+++ b/sdk/src/asset/AddressableManifest.ts@@ -196,6 +196,7 @@ export class ManifestModel {private keyIndex_: Map<string, AddressableManifestAsset> | null = null;private pathIndex_: Map<string, AddressableManifestAsset> | null = null;+ private remoteIndex_: Map<string, string> | null = null;private indexes(): { byKey: Map<string, AddressableManifestAsset>; byPath: Map<string, AddressableManifestAsset> } {if (!this.keyIndex_ || !this.pathIndex_) {@@ -234,6 +235,32 @@ export class ManifestModel {return this.indexes().byPath.get(path) ?? null;}+ /**+ * Build path of a `remote`-group asset by ANY of its keys — record key (uuid),+ * address (logical source path, bare and `/`-rooted), or build path — or null+ * when the ref is not a remote-delivered asset. Lets a resolver route scene+ * `@uuid` refs to remote assets through the CDN (so they hot-update with the+ * manifest), while local / lazy assets keep their normal resolution.+ */+ remoteAssetPath(ref: string): string | null {+ if (!this.remoteIndex_) {+ const idx = new Map<string, string>();+ for (const group of Object.values(this.manifest.groups)) {+ if (normalizeBundleMode(group.bundleMode) !== 'remote') continue;+ for (const [key, asset] of Object.entries(group.assets)) {+ idx.set(key, asset.path);+ idx.set(asset.path, asset.path);+ if (asset.address) {+ idx.set(asset.address, asset.path);+ idx.set(`/${asset.address}`, asset.path);+ }+ }+ }+ this.remoteIndex_ = idx;+ }+ return this.remoteIndex_.get(ref) ?? null;+ }+/*** Resolve a serialized asset ref (a uuid, an address, or a path) to its* build path. `normalize` maps a ref to its expected build path (e.g.diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex a3c7163ca..08152c6de 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -1365,10 +1365,28 @@ export class Assets {* time — textures silently rendered white. This helper closes that gap.*/private resolveLoadPath_(ref: string): string {+ // A `remote`-group asset (per the active addressable manifest) resolves to+ // its CDN url — so a scene @uuid ref to a remote asset loads from, and+ // hot-updates with, the CDN, not just loadGroup'd DLC assets. Gated on a+ // remote root being set, so same-origin realms (editor Play, a build with+ // no CDN) keep their normal resolver + base-prefixing untouched.+ const remote = this.remoteAssetPath_(ref);+ if (remote != null) return remote;const resolved = this.assetRefResolver_?.(ref) ?? ref;return this.catalog.resolve(resolved);}+ /** CDN url of `ref` when it names a `remote`-group asset AND a remote root is+ * set; null otherwise (caller falls back to the normal resolver). */+ private remoteAssetPath_(ref: string): string | null {+ if (!this.remoteRoot_) return null;+ const model = this.manifestModel_;+ if (!model) return null;+ const key = ref.startsWith('@uuid:') ? ref.slice(6).toLowerCase() : ref;+ const path = model.remoteAssetPath(key) ?? model.remoteAssetPath(ref);+ return path != null ? this.remoteUrlFor_(path) : null;+ }+// =========================================================================// Private// =========================================================================diff --git a/sdk/tests/hot-update-runtime.test.ts b/sdk/tests/hot-update-runtime.test.tsindex 194b8a541..d51e96aa6 100644--- a/sdk/tests/hot-update-runtime.test.ts+++ b/sdk/tests/hot-update-runtime.test.ts@@ -184,6 +184,48 @@ describe('Assets.checkForUpdate / applyUpdate', () => {});});+describe('Assets.resolveLoadPath — @uuid refs to remote assets (model-2)', () => {+ it('resolves a remote-group asset (by @uuid / uuid / address) to the CDN url when a root is set', () => {+ const assets = createAssets(backendServing());+ assets.setManifest(cdnManifest('aaaa', 'rev-1')); // cdn remote; uuid-1 → assets/aaaa.png, address assets/hero.png+ assets.setRemoteRoot('https://cdn.example.com/v1');+ expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe('https://cdn.example.com/v1/assets/aaaa.png');+ expect(assets.resolveLoadPath('uuid-1')).toBe('https://cdn.example.com/v1/assets/aaaa.png');+ expect(assets.resolveLoadPath('assets/hero.png')).toBe('https://cdn.example.com/v1/assets/aaaa.png');+ });++ it('falls through to the normal resolver with no remote root (same-origin realms)', () => {+ const assets = createAssets(backendServing());+ assets.setManifest(cdnManifest('aaaa', 'rev-1'));+ assets.setAssetRefResolver((r) => (r === '@uuid:uuid-1' ? 'estella://project/assets/hero.png' : r));+ // No remoteRoot → the addressable manifest does not hijack resolution.+ expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe('estella://project/assets/hero.png');+ });++ it('leaves local / lazy assets to the normal resolver (only remote groups are routed)', () => {+ const assets = createAssets(backendServing());+ assets.setManifest({+ version: '2.0',+ groups: { main: { bundleMode: 'local', labels: [], assets: { 'uuid-x': { path: 'a.png', type: 'texture', size: 1, labels: [] } } } },+ } as any);+ assets.setRemoteRoot('https://cdn');+ assets.setAssetRefResolver((r) => (r === '@uuid:uuid-x' ? 'a.png' : r));+ expect(assets.resolveLoadPath('@uuid:uuid-x')).toBe('a.png');+ });++ it('after applyUpdate, an @uuid ref resolves to the NEW remote path (scene assets hot-update)', async () => {+ const assets = createAssets(backendServing(cdnManifest(REMOTE_HASH, 'rev-2')));+ assets.setManifest(cdnManifest('aaaa', 'rev-1'));+ assets.setRemoteRoot('https://cdn/v1');+ expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe('https://cdn/v1/assets/aaaa.png');++ await assets.checkForUpdate({ manifestUrl: 'm.json', remoteRoot: 'https://cdn/v2' });+ expect((await assets.applyUpdate()).ok).toBe(true);++ expect(assets.resolveLoadPath('@uuid:uuid-1')).toBe(`https://cdn/v2/assets/${REMOTE_HASH}.png`);+ });+});+describe('Assets.restorePersistedUpdate', () => {it('persists an applied update and restores it into a fresh Assets', async () => {const backend = backendServing(cdnManifest(REMOTE_HASH, 'rev-2'));