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.

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.md
index 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 a
zero-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 })` to
diff the CDN's manifest against the running one, then `Assets.applyUpdate()` to
download the changed assets and swap the manifest. Existing handles bound to a
diff --git a/examples/hot-update-demo/assets/scenes/main.esscene b/examples/hot-update-demo/assets/scenes/main.esscene
index 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.ts
index 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.md
index 537f97428..06cf851f6 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -3645,6 +3645,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | null
group: (name: string) => AddressableManifestGroup | null
groupNames: () => string[]
groupsByMode: (mode: BundleMode) => string[]
+remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
static empty: () => ManifestModel
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | null
group: (name: string) => AddressableManifestGroup | null
groupNames: () => string[]
groupsByMode: (mode: BundleMode) => string[]
+remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
static empty: () => ManifestModel
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 3cf74883f..e5099f7c7 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -3647,6 +3647,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | null
group: (name: string) => AddressableManifestGroup | null
groupNames: () => string[]
groupsByMode: (mode: BundleMode) => string[]
+remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
static empty: () => ManifestModel
diff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.ts
index 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.ts
index 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.ts
index 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'));