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): 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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);
+ });
+});