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 ref-bound asset is owned as a slot, not as a generation
esengined2174652122c
diff --git a/sdk/src/asset/registryAssets.ts b/sdk/src/asset/registryAssets.tsnew file mode 100644index 000000000..21765dc50--- /dev/null+++ b/sdk/src/asset/registryAssets.ts@@ -0,0 +1,213 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file registryAssets.ts+ * @brief The identity of an asset a component names by REF rather than by handle.+ *+ * @details Two asset models had one ownership vocabulary between them. A sprite+ * holds `texture = 17`: the field names an exact instance, so its owner+ * holds a receipt for that generation. A `SpriteAnimator` holds+ * `clip = "walk.esanim"`: the field names an asset, and every lookup+ * asks a registry which object that name means NOW. Such a holder never+ * had a generation to own — give it one and the moment a hot update+ * republishes, ownership says one era while the component uses another.+ *+ * So what it owns is the SLOT: the stable name, however many eras pass+ * 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.+ */+import type { AssetLease } from './AssetLease';+import { AssetScope } from './AssetLease';++/** One era of a registry-backed asset. */+export interface RegistryEra<T> {+ /** The runtime object a lookup returns while this era is the published one. */+ readonly published: unknown;+ /** The logical identity a holder keeps — the same across every era. */+ readonly value: T;+ /** What this era acquired for itself; released when it retires. */+ readonly dependencies: AssetScope;+}++/**+ * How one kind of registry-backed asset is prepared and published.+ *+ * `prepare` must NOT publish: an era that could write the registry could also+ * take a newer era's entry out of it.+ */+export interface RegistryAssetKind<T> {+ prepare(path: string): Promise<RegistryEra<T>>;+ publish(names: readonly string[], published: unknown): void;+ unpublish(names: readonly string[]): void;+}++/** A holder's claim on a slot. Its `generation` names the SLOT, not an era —+ * which era is current is the slot's business and changes under the holder. */+export interface RegistrySlotLease<T> extends AssetLease<T> {+ /** Every name that resolves to this slot: the load path and its aliases. */+ readonly names: readonly string[];+}++export function isRegistrySlotLease(lease: AssetLease): lease is RegistrySlotLease<unknown> {+ return Array.isArray((lease as { names?: unknown }).names);+}++class Slot<T> {+ readonly names: string[] = [];+ refs = 0;+ era: RegistryEra<T> | null = null;+ loading: Promise<RegistryEra<T>> | null = null;++ constructor(readonly key: string, readonly id: number) {}+}++/**+ * Every registry-backed asset this Assets has published, by every name that+ * resolves to it.+ */+export class RegistryAssetSlots {+ private byName_ = new Map<string, Slot<unknown>>();+ private nextId_ = 1;++ /**+ * A claim on the slot for `key`, publishing its first era if there is none.+ *+ * `aliases` are further names the same asset answers to. They resolve to the+ * SAME slot rather than to a copy of the object, so a republish is seen+ * through every one of them.+ */+ async acquire<T>(+ kind: RegistryAssetKind<T>, key: string, aliases: readonly string[] = [],+ ): Promise<RegistrySlotLease<T>> {+ const slot = this.slotFor_(key) as Slot<T>;+ for (const alias of aliases) this.alias_(slot as Slot<unknown>, alias);++ if (!slot.era) {+ slot.loading ??= kind.prepare(key);+ let era: RegistryEra<T>;+ try {+ era = await slot.loading;+ } catch (e) {+ slot.loading = null;+ if (slot.refs === 0) this.forget_(slot as Slot<unknown>);+ throw e;+ }+ slot.loading = null;+ // Another acquire may have published while this one awaited; joining+ // it is a cache hit, and publishing twice would retire what is live.+ if (!slot.era) {+ slot.era = era;+ kind.publish(slot.names, era.published);+ } else if (era !== slot.era) {+ era.dependencies.releaseAll();+ }+ }+ return this.lease_(kind, slot);+ }++ /**+ * Replace the current era with a freshly prepared one, atomically.+ *+ * A failed prepare leaves the slot exactly as it was — holders keep working+ * 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;+ if (!slot?.era) return false;+ const era = await kind.prepare(slot.key);+ const previous = slot.era;+ slot.era = era;+ kind.publish(slot.names, era.published);+ // Its dependencies only. The registry entry it was under already names+ // the era published above, and is not this one's to take away.+ previous.dependencies.releaseAll();+ return true;+ }++ /** Whether this name is one a slot answers to. */+ has(name: string): boolean {+ return this.byName_.has(name);+ }++ /** The runtime object published for `name`, if any. Diagnostics and tests. */+ published(name: string): unknown {+ return this.byName_.get(name)?.era?.published;+ }++ /** Live slots — one per asset, however many names it answers to. */+ get size(): number {+ return new Set(this.byName_.values()).size;+ }++ /** Give up every slot. For a wholesale teardown. */+ releaseAll(kinds: (key: string) => RegistryAssetKind<unknown> | undefined): void {+ for (const slot of new Set(this.byName_.values())) {+ kinds(slot.key)?.unpublish(slot.names);+ slot.era?.dependencies.releaseAll();+ slot.era = null;+ slot.refs = 0;+ }+ this.byName_.clear();+ }++ /** 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);+ if (!slot || slot.refs === 0) return false;+ this.drop_(kind, slot);+ return true;+ }++ private lease_<T>(kind: RegistryAssetKind<T>, slot: Slot<T>): RegistrySlotLease<T> {+ slot.refs++;+ let spent = false;+ const lease: RegistrySlotLease<T> = {+ key: slot.key,+ generation: slot.id,+ value: slot.era!.value,+ names: slot.names,+ release: () => {+ if (spent) return;+ spent = true;+ this.drop_(kind as RegistryAssetKind<unknown>, slot as Slot<unknown>);+ },+ retain: () => (this.byName_.get(slot.key) === (slot as Slot<unknown>) && slot.era+ ? this.lease_(kind, slot)+ : null),+ };+ return lease;+ }++ private drop_(kind: RegistryAssetKind<unknown>, slot: Slot<unknown>): void {+ if (--slot.refs > 0) return;+ kind.unpublish(slot.names);+ slot.era?.dependencies.releaseAll();+ slot.era = null;+ this.forget_(slot);+ }++ private slotFor_(key: string): Slot<unknown> {+ let slot = this.byName_.get(key);+ if (!slot) {+ slot = new Slot<unknown>(key, this.nextId_++);+ slot.names.push(key);+ this.byName_.set(key, slot);+ }+ return slot;+ }++ private alias_(slot: Slot<unknown>, alias: string): void {+ if (this.byName_.get(alias) === slot) return;+ slot.names.push(alias);+ this.byName_.set(alias, slot);+ }++ private forget_(slot: Slot<unknown>): void {+ for (const name of slot.names) {+ if (this.byName_.get(name) === slot) this.byName_.delete(name);+ }+ }+}diff --git a/sdk/tests/registry-asset-slots.test.ts b/sdk/tests/registry-asset-slots.test.tsnew file mode 100644index 000000000..64521914b--- /dev/null+++ b/sdk/tests/registry-asset-slots.test.ts@@ -0,0 +1,158 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file registry-asset-slots.test.ts+ * @brief What a holder of a ref-bound asset owns: the slot, not an era.+ *+ * @details A component holding `clip = "walk.esanim"` asks the registry what+ * that name means on every lookup, so it follows a republish without+ * being told. Owning an era instead would put ownership one generation+ * behind what is actually on screen the moment a hot update landed.+ */+import { describe, it, expect } from 'vitest';+import { RegistryAssetSlots, type RegistryAssetKind, type RegistryEra } from '../src/asset/registryAssets';+import { AssetScope, type AssetLease } from '../src/asset/AssetLease';++/** A registry, and a kind that publishes into it — the two halves a loader has. */+function fixture() {+ const registry = new Map<string, unknown>();+ const released: string[] = [];+ let era = 0;+ const kind: RegistryAssetKind<{ id: string }> = {+ prepare: async (path: string): Promise<RegistryEra<{ id: string }>> => {+ const name = `${path}#${++era}`;+ const dependencies = new AssetScope();+ dependencies.add(fakeLease(`${name}:texture`, released));+ return { published: { name }, value: { id: path }, dependencies };+ },+ publish: (names, published) => { for (const n of names) registry.set(n, published); },+ unpublish: (names) => { for (const n of names) registry.delete(n); },+ };+ return { registry, released, kind };+}++function fakeLease(key: string, released: string[]): AssetLease {+ const lease: AssetLease = {+ key, generation: 1, value: null,+ release: () => released.push(key),+ retain: () => fakeLease(key, released),+ };+ return lease;+}++describe('a ref-bound asset is owned as a slot', () => {+ it('the last holder takes the publication and its dependencies with it', async () => {+ // The permanent pin this replaces: nothing released a registry-backed+ // asset, so what it had baked in stayed loaded for the life of the app.+ const { registry, released, kind } = fixture();+ const slots = new RegistryAssetSlots();++ const a = await slots.acquire(kind, 'walk.esanim');+ const b = await slots.acquire(kind, 'walk.esanim');+ expect(slots.size).toBe(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);+ expect(released).toEqual([]);++ b.release();+ expect(registry.has('walk.esanim'), 'the last holder left it published').toBe(false);+ 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, 'walk.esanim', ['assets/walk.esanim']);++ expect(await slots.republish(kind, 'assets/walk.esanim')).toBe(true);+ // Both names, one slot, one era.+ 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(['walk.esanim#1:texture', 'walk.esanim#2:texture']);+ });++ it('a retiring era cannot unpublish the era that replaced it', async () => {+ // The bug a per-loader `unregister(path)` on unload would have written:+ // gen1's cleanup deleting the entry gen2 had just published under the+ // 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, 'walk.esanim');+ const second = await slots.acquire(kind, 'walk.esanim');+ await slots.republish(kind, 'walk.esanim');++ first.release();+ expect(registry.get('walk.esanim'), 'gen1 leaving took gen2 out').toEqual({ name: 'walk.esanim#2' });+ second.release();+ expect(registry.has('walk.esanim')).toBe(false);+ });++ 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, 'http://cdn/walk.esanim', ['assets/walk.esanim', '@uuid:1']);++ expect(slots.size, 'three names, one asset').toBe(1);+ const published = registry.get('http://cdn/walk.esanim');+ expect(registry.get('assets/walk.esanim')).toBe(published);+ expect(registry.get('@uuid:1')).toBe(published);++ await slots.republish(kind, '@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.+ expect(registry.get('assets/walk.esanim')).toBe(next);+ expect(registry.get('http://cdn/walk.esanim')).toBe(next);+ });++ 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, '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: '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(['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, 'walk.esanim');+ const entity = scene.retain()!;+ expect(entity.generation).toBe(scene.generation); // the same slot++ scene.release();+ expect(registry.has('walk.esanim'), 'the entity still uses it').toBe(true);+ entity.release();+ expect(registry.has('walk.esanim')).toBe(false);+ });++ 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, 'walk.esanim'),+ slots.acquire(kind, 'walk.esanim'),+ ]);+ expect(registry.get('walk.esanim')).toEqual({ name: 'walk.esanim#1' });+ expect(released, 'a second era was prepared and stranded').toEqual([]);+ a.release();+ b.release();+ expect(slots.size).toBe(0);+ });+});