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): a registry lookup is (asset type, name), and the realm can answer it
esengineb70f46157268
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 1ed63bc3b..49d760793 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -769,9 +769,11 @@ ResourceDef<AssetsClass>```@internal appScope: AssetScope@internal entityScopes: EntityAssetScopes+@internal publishedRegistryAssets: <T>(type: string) => T[]@internal releaseTextureLease: (lease: AssetRefLease<number>) => void@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<unknown>) => void+@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 3fdf784b8..b080e8376 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -769,9 +769,11 @@ ResourceDef<AssetsClass>```@internal appScope: AssetScope@internal entityScopes: EntityAssetScopes+@internal publishedRegistryAssets: <T>(type: string) => T[]@internal releaseTextureLease: (lease: AssetRefLease<number>) => void@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<unknown>) => void+@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d790877ce..e4911872c 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -764,9 +764,11 @@ ResourceDef<AssetsClass>```@internal appScope: AssetScope@internal entityScopes: EntityAssetScopes+@internal publishedRegistryAssets: <T>(type: string) => T[]@internal releaseTextureLease: (lease: AssetRefLease<number>) => void@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<unknown>) => void+@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex cecbdb959..8bf4de29e 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -764,9 +764,11 @@ ResourceDef<AssetsClass>```@internal appScope: AssetScope@internal entityScopes: EntityAssetScopes+@internal publishedRegistryAssets: <T>(type: string) => T[]@internal releaseTextureLease: (lease: AssetRefLease<number>) => void@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<unknown>) => void+@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex cfa6d2651..d49a60409 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -764,9 +764,11 @@ ResourceDef<AssetsClass>```@internal appScope: AssetScope@internal entityScopes: EntityAssetScopes+@internal publishedRegistryAssets: <T>(type: string) => T[]@internal releaseTextureLease: (lease: AssetRefLease<number>) => void@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<unknown>) => void+@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 5705f279b..2ef89113c 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -1414,7 +1414,7 @@ export class Assets {// 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);+ return this.registrySlots_.acquire(kind, type, path, names);}/**@@ -1550,7 +1550,7 @@ export class Assets {const path = this.resolveLoadPath_(ref);const kind = this.registryKind_(type);if (kind) {- this.registrySlots_.releaseByName(kind, `${type}:${path}`);+ this.registrySlots_.releaseByName(kind, type, path);return;}// NOT gated on a live cache entry: a generation superseded by@@ -1641,9 +1641,9 @@ export class Assets {// by nobody — a failed prepare leaves holders the era they have.for (const [type] of this.loaders_) {const kind = this.registryKind_(type);- if (!kind || !this.registrySlots_.has(`${type}:${path}`)) continue;+ if (!kind || !this.registrySlots_.has(type, path)) continue;hit = true;- void this.registrySlots_.republish(kind, `${type}:${path}`).catch((e: unknown) => {+ void 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);});}@@ -1766,7 +1766,7 @@ export class Assets {// Through the normal door first, so what the app owned is disposed the// way any other owner's is rather than by the wholesale drain below.this.appScope_.releaseAll();- this.registrySlots_.releaseAll((key) => this.registryKind_(key.slice(0, key.indexOf(':'))) ?? undefined);+ this.registrySlots_.releaseAll((type) => this.registryKind_(type) ?? undefined);const rm = requireResourceManager();this.resetEpoch_++;this.abandoned_.clear();@@ -1989,6 +1989,30 @@ export class Assets {return { value: result, lease };}+ /**+ * What THIS realm publishes for a ref-bound asset — the answer a runtime+ * lookup reads, and the only copy of it.+ *+ * By the ref as spelled or the path it resolves to: a slot answers to both,+ * so a lookup site need not know which spelling a scene serialized.+ *+ * @internal+ */+ resolveRegistryAsset<T>(type: string, ref: string): T | undefined {+ return (this.registrySlots_.published(type, ref)+ ?? this.registrySlots_.published(type, this.resolveLoadPath_(ref))) as T | undefined;+ }++ /**+ * Everything this realm publishes of one type. What a schedule analysis+ * reads to learn what the graphs THIS app loaded reach for.+ *+ * @internal+ */+ publishedRegistryAssets<T>(type: string): T[] {+ return this.registrySlots_.publishedOf(type) as T[];+ }+/*** The slot table's view of one registry-backed loader — the LoadContext* bound in, so the table stays about ownership and knows nothing about howdiff --git a/sdk/src/asset/registryAssets.ts b/sdk/src/asset/registryAssets.tsindex ac6868173..0a1121f8d 100644--- a/sdk/src/asset/registryAssets.ts+++ b/sdk/src/asset/registryAssets.ts@@ -16,6 +16,11 @@* under it. An era owns what it acquired for itself and nothing else —* publication belongs to the slot, which is what makes it impossible* for a retiring era to unpublish the newer one that replaced it.+ *+ * A lookup identity is (asset TYPE, logical name). Bare names would+ * have two kinds of asset sharing one entry the moment a project's own+ * registry-backed type answered to a name an engine one already used —+ * today that is only prevented by the file extensions differing.*/import type { AssetLease } from './AssetLease';import { AssetScope } from './AssetLease';@@ -61,14 +66,20 @@ class Slot<T> {era: RegistryEra<T> | null = null;loading: Promise<RegistryEra<T>> | null = null;- constructor(readonly key: string, readonly id: number) {}+ constructor(readonly type: string, readonly key: string, readonly id: number) {}}/*** Every registry-backed asset this Assets has published, by every name that* resolves to it.*/+/** One lookup identity. `\0` cannot occur in a path or a ref. */+function lookupKey(type: string, name: string): string {+ return `${type}\0${name}`;+}+export class RegistryAssetSlots {+ /** By (type, name) — see the note on lookup identity above. */private byName_ = new Map<string, Slot<unknown>>();private nextId_ = 1;@@ -79,10 +90,10 @@ export class RegistryAssetSlots {* than to a copy of the object.*/async acquire<T>(- kind: RegistryAssetKind<T>, key: string, names: readonly string[],+ kind: RegistryAssetKind<T>, type: string, key: string, names: readonly string[],): Promise<RegistrySlotLease<T>> {- const slot = this.slotFor_(key) as Slot<T>;- for (const name of names) this.name_(slot as Slot<unknown>, name);+ const slot = this.slotFor_(type, key) as Slot<T>;+ for (const name of names) this.name_(slot as Slot<unknown>, type, name);if (!slot.era) {slot.loading ??= kind.prepare(key);@@ -114,8 +125,8 @@ export class RegistryAssetSlots {* with the era they have rather than losing it to a bad download. Answers* false when nothing holds this name.*/- async republish<T>(kind: RegistryAssetKind<T>, name: string): Promise<boolean> {- const slot = this.byName_.get(name) as Slot<T> | undefined;+ async republish<T>(kind: RegistryAssetKind<T>, type: string, name: string): Promise<boolean> {+ const slot = this.byName_.get(lookupKey(type, name)) as Slot<T> | undefined;if (!slot?.era) return false;const era = await kind.prepare(slot.key);const previous = slot.era;@@ -127,14 +138,27 @@ export class RegistryAssetSlots {return true;}- /** Whether this name is one a slot answers to. */- has(name: string): boolean {- return this.byName_.has(name);+ /** Whether this name is one a slot of this type answers to. */+ has(type: string, name: string): boolean {+ return this.byName_.has(lookupKey(type, name));+ }++ /**+ * What this realm publishes for (type, name) right now — the answer a+ * runtime lookup reads, and the only copy of it.+ */+ published(type: string, name: string): unknown {+ return this.byName_.get(lookupKey(type, name))?.era?.published;}- /** The runtime object published for `name`, if any. Diagnostics and tests. */- published(name: string): unknown {- return this.byName_.get(name)?.era?.published;+ /** Everything published of one type. What a schedule analysis reads to learn+ * what the loaded graphs of this realm reach for. */+ publishedOf(type: string): unknown[] {+ const out: unknown[] = [];+ for (const slot of new Set(this.byName_.values())) {+ if (slot.type === type && slot.era) out.push(slot.era.published);+ }+ return out;}/** Live slots — one per asset, however many names it answers to. */@@ -143,9 +167,9 @@ export class RegistryAssetSlots {}/** Give up every slot. For a wholesale teardown. */- releaseAll(kinds: (key: string) => RegistryAssetKind<unknown> | undefined): void {+ releaseAll(kinds: (type: string) => RegistryAssetKind<unknown> | undefined): void {for (const slot of new Set(this.byName_.values())) {- kinds(slot.key)?.unpublish(slot.names, slot.era?.published);+ kinds(slot.type)?.unpublish(slot.names, slot.era?.published);slot.era?.dependencies.releaseAll();slot.era = null;slot.refs = 0;@@ -155,8 +179,8 @@ export class RegistryAssetSlots {/** Drop one claim on the slot `name` resolves to, without its receipt. The* compatibility door for a caller that only ever had a path. */- releaseByName(kind: RegistryAssetKind<unknown>, name: string): boolean {- const slot = this.byName_.get(name);+ releaseByName(kind: RegistryAssetKind<unknown>, type: string, name: string): boolean {+ const slot = this.byName_.get(lookupKey(type, name));if (!slot || slot.refs === 0) return false;this.drop_(kind, slot);return true;@@ -175,7 +199,7 @@ export class RegistryAssetSlots {spent = true;this.drop_(kind as RegistryAssetKind<unknown>, slot as Slot<unknown>);},- retain: () => (this.byName_.get(slot.key) === (slot as Slot<unknown>) && slot.era+ retain: () => (this.byName_.get(lookupKey(slot.type, slot.key)) === (slot as Slot<unknown>) && slot.era? this.lease_(kind, slot): null),};@@ -190,20 +214,26 @@ export class RegistryAssetSlots {this.forget_(slot);}- private slotFor_(key: string): Slot<unknown> {- let slot = this.byName_.get(key);+ private slotFor_(type: string, key: string): Slot<unknown> {+ const id = lookupKey(type, key);+ let slot = this.byName_.get(id);if (!slot) {- slot = new Slot<unknown>(key, this.nextId_++);- this.byName_.set(key, slot);+ slot = new Slot<unknown>(type, key, this.nextId_++);+ this.byName_.set(id, slot);}return slot;}- /** Index another lookup name onto this slot, and publish under it too. */- private name_(slot: Slot<unknown>, name: string): void {- if (this.byName_.get(name) === slot) return;- slot.names.push(name);- this.byName_.set(name, slot);+ /**+ * Index another lookup name onto this slot, and publish under it too.+ *+ * The dedupe is on the NAME list, not on the index: the slot's own key is+ * already indexed when it is created, and reading that back as "already+ * known" left the list — which is what gets published — empty.+ */+ private name_(slot: Slot<unknown>, type: string, name: string): void {+ if (!slot.names.includes(name)) slot.names.push(name);+ this.byName_.set(lookupKey(type, name), slot);}private forget_(slot: Slot<unknown>): void {diff --git a/sdk/tests/registry-asset-slots.test.ts b/sdk/tests/registry-asset-slots.test.tsindex 0dab3d12b..365fe2ea4 100644--- a/sdk/tests/registry-asset-slots.test.ts+++ b/sdk/tests/registry-asset-slots.test.ts@@ -47,10 +47,10 @@ describe('a ref-bound asset is owned as a slot', () => {const { registry, released, kind } = fixture();const slots = new RegistryAssetSlots();- const a = await slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim']);- const b = await slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim']);+ const a = await slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim']);+ const b = await slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim']);expect(slots.size).toBe(1);- expect(registry.get('walk.esanim')).toEqual({ name: 'anim-clip:walk.esanim#1' });+ expect(registry.get('walk.esanim')).toEqual({ name: 'walk.esanim#1' });a.release();expect(registry.has('walk.esanim'), 'published while B still holds it').toBe(true);@@ -58,25 +58,25 @@ describe('a ref-bound asset is owned as a slot', () => {b.release();expect(registry.has('walk.esanim'), 'the last holder left it published').toBe(false);- expect(released).toEqual(['anim-clip:walk.esanim#1:texture']);+ expect(released).toEqual(['walk.esanim#1:texture']);expect(slots.size).toBe(0);});it('a republish swaps what every name resolves to, and retires only the old era', async () => {const { registry, released, kind } = fixture();const slots = new RegistryAssetSlots();- const held = await slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim', 'assets/walk.esanim']);+ const held = await slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim', 'assets/walk.esanim']);- expect(await slots.republish(kind, 'assets/walk.esanim')).toBe(true);+ expect(await slots.republish(kind, 'anim-clip', 'assets/walk.esanim')).toBe(true);// Both names, one slot, one era.- expect(registry.get('walk.esanim')).toEqual({ name: 'anim-clip:walk.esanim#2' });- expect(registry.get('assets/walk.esanim')).toEqual({ name: 'anim-clip:walk.esanim#2' });- expect(released, 'the era it replaced gave back what it held').toEqual(['anim-clip:walk.esanim#1:texture']);+ expect(registry.get('walk.esanim')).toEqual({ name: 'walk.esanim#2' });+ expect(registry.get('assets/walk.esanim')).toEqual({ name: 'walk.esanim#2' });+ expect(released, 'the era it replaced gave back what it held').toEqual(['walk.esanim#1:texture']);// The holder never named an era, so it holds the slot exactly as before.held.release();expect(registry.size).toBe(0);- expect(released).toEqual(['anim-clip:walk.esanim#1:texture', 'anim-clip:walk.esanim#2:texture']);+ expect(released).toEqual(['walk.esanim#1:texture', 'walk.esanim#2:texture']);});it('a retiring era cannot unpublish the era that replaced it', async () => {@@ -85,12 +85,12 @@ describe('a ref-bound asset is owned as a slot', () => {// same name. Publication is the slot's, so an era has no way to.const { registry, kind } = fixture();const slots = new RegistryAssetSlots();- const first = await slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim']);- const second = await slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim']);- await slots.republish(kind, 'walk.esanim');+ const first = await slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim']);+ const second = await slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim']);+ await slots.republish(kind, 'anim-clip', 'walk.esanim');first.release();- expect(registry.get('walk.esanim'), 'gen1 leaving took gen2 out').toEqual({ name: 'anim-clip:walk.esanim#2' });+ expect(registry.get('walk.esanim'), 'gen1 leaving took gen2 out').toEqual({ name: 'walk.esanim#2' });second.release();expect(registry.has('walk.esanim')).toBe(false);});@@ -98,7 +98,7 @@ describe('a ref-bound asset is owned as a slot', () => {it('every alias resolves to one slot, not to a copy of the object', async () => {const { registry, kind } = fixture();const slots = new RegistryAssetSlots();- await slots.acquire(kind, 'anim-clip:http://cdn/walk.esanim',+ await slots.acquire(kind, 'anim-clip', 'http://cdn/walk.esanim',['http://cdn/walk.esanim', 'assets/walk.esanim', '@uuid:1']);expect(slots.size, 'three names, one asset').toBe(1);@@ -106,7 +106,7 @@ describe('a ref-bound asset is owned as a slot', () => {expect(registry.get('assets/walk.esanim')).toBe(published);expect(registry.get('@uuid:1')).toBe(published);- await slots.republish(kind, '@uuid:1');+ await slots.republish(kind, 'anim-clip', '@uuid:1');const next = registry.get('@uuid:1');expect(next).not.toBe(published);// The stale-alias split brain: one name still answering with the old era.@@ -117,23 +117,23 @@ describe('a ref-bound asset is owned as a slot', () => {it('a failed republish leaves the holders exactly what they had', async () => {const { registry, released, kind } = fixture();const slots = new RegistryAssetSlots();- const held = await slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim']);+ const held = await slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim']);const broken = { ...kind, prepare: async () => { throw new Error('no bytes'); } };- await expect(slots.republish(broken, 'walk.esanim')).rejects.toThrow('no bytes');- expect(registry.get('walk.esanim')).toEqual({ name: 'anim-clip:walk.esanim#1' });+ await expect(slots.republish(broken, 'anim-clip', 'walk.esanim')).rejects.toThrow('no bytes');+ expect(registry.get('walk.esanim')).toEqual({ name: 'walk.esanim#1' });expect(released, 'it gave back what a failed update never replaced').toEqual([]);// And the slot still knows WHICH era it is holding: a failure that left// it with none would strand that era's dependencies at the last release.held.release();- expect(released).toEqual(['anim-clip:walk.esanim#1:texture']);+ expect(released).toEqual(['walk.esanim#1:texture']);});it('a retained claim is on the same slot, and the last one still ends it', async () => {const { registry, kind } = fixture();const slots = new RegistryAssetSlots();- const scene = await slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim']);+ const scene = await slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim']);const entity = scene.retain()!;expect(entity.generation).toBe(scene.generation); // the same slot@@ -143,14 +143,34 @@ describe('a ref-bound asset is owned as a slot', () => {expect(registry.has('walk.esanim')).toBe(false);});+ it('one name under two asset types is two slots', async () => {+ // Lookup identity is (type, name). Bare names would have a project's own+ // registry-backed type share an entry with an engine one the moment they+ // answered to the same name — today only the extensions keep them apart.+ const { kind } = fixture();+ const slots = new RegistryAssetSlots();+ const clip = await slots.acquire(kind, 'anim-clip', 'same', ['same']);+ const timeline = await slots.acquire(kind, 'timeline', 'same', ['same']);++ expect(slots.size).toBe(2);+ expect(clip.generation).not.toBe(timeline.generation);+ expect(slots.published('anim-clip', 'same')).not.toBe(slots.published('timeline', 'same'));++ clip.release();+ expect(slots.published('anim-clip', 'same')).toBeUndefined();+ expect(slots.published('timeline', 'same'), 'one type took the other out').toBeDefined();+ timeline.release();+ expect(slots.size).toBe(0);+ });+it('two acquires racing the first load publish one era, not two', async () => {const { registry, released, kind } = fixture();const slots = new RegistryAssetSlots();const [a, b] = await Promise.all([- slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim']),- slots.acquire(kind, 'anim-clip:walk.esanim', ['walk.esanim']),+ slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim']),+ slots.acquire(kind, 'anim-clip', 'walk.esanim', ['walk.esanim']),]);- expect(registry.get('walk.esanim')).toEqual({ name: 'anim-clip:walk.esanim#1' });+ expect(registry.get('walk.esanim')).toEqual({ name: 'walk.esanim#1' });expect(released, 'a second era was prepared and stranded').toEqual([]);a.release();b.release();