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.

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.md
index ec9ca84e3..32ebcbbef 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -4438,6 +4438,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | null
group: (name: string) => AddressableManifestGroup | null
groupNames: () => string[]
groupsByMode: (mode: BundleMode) => string[]
+remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 | null
group: (name: string) => AddressableManifestGroup | null
groupNames: () => string[]
groupsByMode: (mode: BundleMode) => string[]
+remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | null
group: (name: string) => AddressableManifestGroup | null
groupNames: () => string[]
groupsByMode: (mode: BundleMode) => string[]
+remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 2348cb53e..2161671f4 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -4433,6 +4433,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | null
group: (name: string) => AddressableManifestGroup | null
groupNames: () => string[]
groupsByMode: (mode: BundleMode) => string[]
+remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b3ac0938e..52d29efd7 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4440,6 +4440,7 @@ findAsset: (pathOrAddress: string) => AddressableManifestAsset | null
group: (name: string) => AddressableManifestGroup | null
groupNames: () => string[]
groupsByMode: (mode: BundleMode) => string[]
+remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
diff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.ts
index 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.ts
index 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.ts
index 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