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(assets): a slot is keyed by what the asset IS, not by where a revision serves it
esengine98204efd33ad
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex ec9ca84e3..32ebcbbef 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -4438,6 +4438,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | nullgroup: (name: string) => AddressableManifestGroup | nullgroupNames: () => string[]groupsByMode: (mode: BundleMode) => string[]+remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | nulldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 3859119e8..6a51294c8 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -4446,6 +4446,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | nullgroup: (name: string) => AddressableManifestGroup | nullgroupNames: () => string[]groupsByMode: (mode: BundleMode) => string[]+remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | nulldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 3f3487de5..40db2e553 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -4433,6 +4433,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | nullgroup: (name: string) => AddressableManifestGroup | nullgroupNames: () => string[]groupsByMode: (mode: BundleMode) => string[]+remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | nulldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 2348cb53e..2161671f4 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -4433,6 +4433,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | nullgroup: (name: string) => AddressableManifestGroup | nullgroupNames: () => string[]groupsByMode: (mode: BundleMode) => string[]+remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | nulldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex b3ac0938e..52d29efd7 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -4440,6 +4440,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | nullgroup: (name: string) => AddressableManifestGroup | nullgroupNames: () => string[]groupsByMode: (mode: BundleMode) => string[]+remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | nulldiff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.tsindex b65e1801d..c7549c580 100644--- a/sdk/src/asset/AddressableManifest.ts+++ b/sdk/src/asset/AddressableManifest.ts@@ -221,7 +221,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 remoteIndex_: { byRef: Map<string, string>; identity: Map<string, string> } | null = null;private indexes(): { byKey: Map<string, AddressableManifestAsset>; byPath: Map<string, AddressableManifestAsset> } {if (!this.keyIndex_ || !this.pathIndex_) {@@ -268,22 +268,37 @@ export class ManifestModel {* manifest), while local / lazy assets keep their normal resolution.*/remoteAssetPath(ref: string): string | null {+ return this.remoteIndexes_().byRef.get(ref) ?? null;+ }++ /**+ * The stable name of the `remote`-group asset a ref names — its address,+ * else the key it is filed under. NOT interchangeable with+ * {@link remoteAssetPath}: a build path is content-addressed, so it names+ * one revision, while this is what every revision agrees on.+ */+ remoteAssetIdentity(ref: string): string | null {+ return this.remoteIndexes_().identity.get(ref) ?? null;+ }++ /** Both remote indexes, built together from one walk. */+ private remoteIndexes_(): { byRef: Map<string, string>; identity: Map<string, string> } {if (!this.remoteIndex_) {- const idx = new Map<string, string>();+ const byRef = new Map<string, string>();+ const identity = 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);+ const name = asset.address ?? key;+ for (const ref of [key, asset.path, ...(asset.address ? [asset.address, `/${asset.address}`] : [])]) {+ byRef.set(ref, asset.path);+ identity.set(ref, name);}}}- this.remoteIndex_ = idx;+ this.remoteIndex_ = { byRef, identity };}- return this.remoteIndex_.get(ref) ?? null;+ return this.remoteIndex_;}/**diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 0dcb39909..fdc639ce7 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -951,7 +951,13 @@ export class Assets {// A changed asset is content-addressed, so its next load finds the update// on its own. An era already BUILT from one cannot: it holds what it read// at the revision it was prepared in, and only the walk ends it.- for (const c of changed) this.track_(this.rebuildAssetGraph_(this.rebuildPlan_(c.key)));+ for (const c of changed) {+ // Read the plan before anything is re-prepared, then the changed+ // asset's own slot: it is keyed by its identity, so the update+ // reaches it by preparing an era from the new revision's locator.+ const plan = this.rebuildPlan_(c.key);+ this.track_(this.republishSlots_(c.key).rebuilt.then(() => this.rebuildAssetGraph_(plan)));+ }// The update is applied when the asset graph agrees with the manifest —// not when the manifest was swapped. Bindings converge on a frame, which// an app that is not ticking would never reach from here.@@ -1424,12 +1430,14 @@ export class Assets {private async acquireSlot_<T>(type: string, ref: string): Promise<AssetLease<T> | null> {const kind = this.registryKind_<T>(type);if (!kind) return null;- const path = this.resolveLoadPath_(ref);- // The load path and the ref as the caller spelled it: a component looks- // the asset up by the spelling a scene serialized, which in a realm whose- // resolver returns URLs is not the path the loader was handed.- const names = ref === path ? [path] : [path, ref];- return this.registrySlots_.acquire(kind, type, path, names);+ // Keyed by identity, never by the locator: a content-addressed url is+ // revision-specific, so a slot keyed by one is a slot PER REVISION and+ // an update publishes into a new one while every holder reads the old.+ const identity = this.assetIdentity_(ref);+ // Answering to the ref as the caller spelled it too: a component looks+ // the asset up by the spelling a scene serialized.+ const names = ref === identity ? [identity] : [identity, ref];+ return this.registrySlots_.acquire(kind, type, identity, names);}/**@@ -1590,7 +1598,7 @@ export class Assets {const path = this.resolveLoadPath_(ref);const kind = this.registryKind_(type);if (kind) {- this.registrySlots_.releaseByName(type, path);+ this.registrySlots_.releaseByName(type, this.assetIdentity_(ref));return;}// NOT gated on a live cache entry: a generation superseded by@@ -1748,17 +1756,9 @@ export class Assets {}// A registry-backed asset has no cache entry to drop and no handle to- // swap: the update IS a new era published under the same names. Awaited- // by nobody — a failed prepare leaves holders the era they have.- const republished: Array<Promise<unknown>> = [];- for (const [type] of this.loaders_) {- const kind = this.registryKind_(type);- if (!kind || !this.registrySlots_.has(type, path)) continue;- hit = true;- republished.push(this.registrySlots_.republish(kind, type, path).catch((e: unknown) => {- log.warn('asset', `hot update: re-publishing "${ref}" failed; holders keep the era they have`, e);- }));- }+ // swap: the update IS a new era published under the same names.+ const slots = this.republishSlots_(ref);+ if (slots.found) hit = true;// Loader-owned residency (e.g. the AudioAPI warm cache) can outlive// the Assets-level entry — sever it unconditionally so a warm-cache@@ -1777,7 +1777,25 @@ export class Assets {for (const [type, oldValue] of dropped) this.fireInvalidate_({ ref, type, oldValue });- return { hit, rebuilt: Promise.all(republished).then(() => undefined) };+ return { hit, rebuilt: slots.rebuilt };+ }++ /**+ * Prepare a new era for every registry slot this ref names, and publish each+ * atomically. By IDENTITY: the slot is keyed by what the asset is, and this+ * preparation resolves where the current revision serves it.+ */+ private republishSlots_(ref: string): { found: boolean; rebuilt: Promise<void> } {+ const identity = this.assetIdentity_(ref);+ const work: Array<Promise<unknown>> = [];+ for (const [type] of this.loaders_) {+ const kind = this.registryKind_(type);+ if (!kind || !this.registrySlots_.has(type, identity)) continue;+ work.push(this.registrySlots_.republish(kind, type, identity).catch((e: unknown) => {+ log.warn('asset', `hot update: re-publishing "${ref}" failed; holders keep the era they have`, e);+ }));+ }+ return { found: work.length > 0, rebuilt: Promise.all(work).then(() => undefined) };}/** Fire every onInvalidate listener with one generation's ending. Isolates@@ -2012,9 +2030,28 @@ export class Assets {// 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.+ // no CDN) keep their normal resolver + base-prefixing untouched. It is+ // the one step that carries a REVISION, which is why identity stops+ // short of it.const remote = this.remoteAssetPath_(ref);if (remote != null) return remote;+ return this.assetIdentity_(ref);+ }++ /**+ * What a ref MEANS in this realm, with no revision in it.+ *+ * Distinct from {@link resolveLoadPath_}, which goes on to where that asset+ * is served from NOW. Identity is what a slot is keyed by and what two+ * spellings agree on; a locator is what one preparation reads.+ */+ private assetIdentity_(ref: string): string {+ if (isBuiltinMeshRef(ref)) return ref;+ // A manifest names one asset three ways — record key, address, build+ // path — and only it knows they are the same asset. Folding them here is+ // what keeps a uuid ref and a path ref on ONE slot.+ const named = this.manifestModel_?.remoteAssetIdentity(ref);+ if (named != null) return named;const resolved = this.assetRefResolver_?.(ref) ?? ref;return this.catalog.resolve(resolved);}@@ -2128,7 +2165,7 @@ export class Assets {*/resolveRegistryAsset<T>(type: string, ref: string): T | undefined {return (this.registrySlots_.published(type, ref)- ?? this.registrySlots_.published(type, this.resolveLoadPath_(ref))) as T | undefined;+ ?? this.registrySlots_.published(type, this.assetIdentity_(ref))) as T | undefined;}/**@@ -2140,10 +2177,9 @@ export class Assets {dependenciesOf(type: string, ref: string): readonly DependencyReceipt[] {const own = this.registrySlots_.dependenciesOf(type, ref);if (own.length > 0) return own;- const path = this.resolveLoadPath_(ref);- const byPath = this.registrySlots_.dependenciesOf(type, path);- if (byPath.length > 0) return byPath;- return this.genericCache_.get(type)?.get(path)?.edges ?? [];+ const byIdentity = this.registrySlots_.dependenciesOf(type, this.assetIdentity_(ref));+ if (byIdentity.length > 0) return byIdentity;+ return this.genericCache_.get(type)?.get(this.resolveLoadPath_(ref))?.edges ?? [];}/**@@ -2217,7 +2253,14 @@ export class Assets {const loader = this.loaders_.get(type) as AssetLoader<T> | undefined;const registry = loader?.registry;if (!registry) return null;- return { prepare: (path) => this.prepared_((ctx) => registry.prepare(path, ctx)) };+ // The locator is resolved HERE, once per era: the slot holds an identity,+ // and where that asset is served from is a property of the revision the+ // preparation runs in.+ return {+ prepare: (identity) => this.prepared_(+ (ctx) => registry.prepare(this.resolveLoadPath_(identity), ctx),+ ),+ };}/**diff --git a/sdk/tests/hot-update-runtime.test.ts b/sdk/tests/hot-update-runtime.test.tsindex c00b6b5f3..ce57d7140 100644--- a/sdk/tests/hot-update-runtime.test.ts+++ b/sdk/tests/hot-update-runtime.test.ts@@ -107,6 +107,61 @@ describe('Assets.loadGroup — remote group', () => {});});+/** A cdn manifest whose one asset is REF-BOUND — a slot, not a handle. */+function cdnSlotManifest(hash: string, revision: string): AddressableManifest {+ return {+ version: '2.0',+ revision,+ groups: {+ cdn: {+ bundleMode: 'remote',+ labels: [],+ assets: {+ 'uuid-w': {+ path: `assets/${hash}.widget`, address: 'assets/hero.widget',+ type: 'json', size: 10, labels: [], contentHash: hash,+ },+ },+ },+ },+ };+}++describe('a slot is keyed by what the asset IS, not by where this revision serves it', () => {+ it('the same slot re-prepares from the new revision\'s url', async () => {+ // Keyed by the resolved url, a slot is revision-specific: the update+ // publishes nothing into it, and every holder — components look their+ // ref up on each frame — reads the old era for the life of the app.+ const backend = backendServing(cdnSlotManifest(REMOTE_HASH, 'rev-2'));+ const assets = createAssets(backend);+ assets.setManifest(cdnSlotManifest('aaaa', 'rev-1'));+ assets.setRemoteRoot('https://cdn/v1');+ const loadedFrom: string[] = [];+ assets.register({+ type: 'widget', extensions: ['.widget'],+ registry: {+ prepare: async (path) => {+ loadedFrom.push(path);+ return { published: { from: path }, value: { id: 'assets/hero.widget' } };+ },+ },+ });++ const held = await assets.acquireTyped('widget', 'assets/hero.widget');+ expect(loadedFrom).toEqual(['https://cdn/v1/assets/aaaa.widget']);++ await assets.checkForUpdate({ manifestUrl: 'asset-manifest.json', remoteRoot: 'https://cdn/v2' });+ await assets.applyUpdate();++ expect(loadedFrom[1], 'the update published nothing into the slot')+ .toBe(`https://cdn/v2/assets/${REMOTE_HASH}.widget`);+ expect(assets.sizes().registrySlots, 'the update opened a second slot for one asset').toBe(1);+ expect(assets.resolveRegistryAsset('widget', 'assets/hero.widget'))+ .toEqual({ from: `https://cdn/v2/assets/${REMOTE_HASH}.widget` });+ held.release();+ });+});+describe('a hot update reaches what was built from what it changed', () => {it('re-prepares the asset that read a changed one, against the new content', async () => {// The changed asset itself is content-addressed, so the next load of it