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 change rebuilds what was built from it, deepest first

esenginea5b03b0583dd
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 8209bd943..490480801 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -22,8 +22,8 @@ import { AssetRefLedger, type AssetRefLease } from './AssetRefLedger';
import { AssetScope, type AssetLease } from './AssetLease';
import { EntityAssetScopes } from './entityAssetScopes';
import { RegistryAssetSlots, type RegistryAssetKind } from './registryAssets';
-import { DependencyRecorder, isInvalidatable, type AssetIdentity, type DependencyReceipt,
- type Preparation, type PreparedLoad } from './dependencies';
+import { DependencyRecorder, isInvalidatable, rebuildPlan, type AssetIdentity,
+ type DependencyReceipt, type Preparation, type PreparedLoad } from './dependencies';
import { SpineAssetLoader } from './loaders/SpineAssetLoader';
import { MaterialAssetLoader } from './loaders/MaterialAssetLoader';
import { MeshAssetLoader } from './loaders/MeshAssetLoader';
@@ -1640,10 +1640,38 @@ export class Assets {
* caught and logged — one bad subscriber can't prevent other
* subscribers from observing the invalidation.
*
- * Returns true if any cache held `ref`.
+ * What was BUILT from `ref` ends too. The plan is read BEFORE anything is
+ * dropped, and walked deepest-first with each group awaiting the one before
+ * it: a parent re-prepared too early acquires the era it already had.
+ *
+ * Returns true if any cache held `ref` itself.
*/
invalidate(ref: string): boolean {
- const path = this.resolveRef(ref) ?? ref;
+ const plan = this.rebuildPlan_(ref);
+ const { hit, rebuilt } = this.invalidateOne_(ref);
+ if (plan.length > 0) void rebuilt.then(() => this.rebuild_(plan));
+ return hit;
+ }
+
+ /** What a change to `ref` reaches, after `ref` itself. */
+ private rebuildPlan_(ref: string): string[][] {
+ const root = this.resolveLoadPath_(ref);
+ const plan = rebuildPlan(root, (path) => this.dependentsOf(path).map((d) => d.path));
+ return plan.map((group) => group.filter((p) => p !== root)).filter((g) => g.length > 0);
+ }
+
+ /** Each group only once everything it was built from has landed. */
+ private async rebuild_(plan: string[][]): Promise<void> {
+ for (const group of plan) {
+ await Promise.all(group.map((path) => this.invalidateOne_(path).rebuilt));
+ }
+ }
+
+ /** End one asset's era: drop every record of it, re-publish what is
+ * published by name, and say which kind ended. `rebuilt` settles when its
+ * own re-preparation has landed. */
+ private invalidateOne_(ref: string): { hit: boolean; rebuilt: Promise<void> } {
+ const path = this.resolveLoadPath_(ref);
// The texture handle bound to this path, captured BEFORE the caches drop
// it, so a rebind listener can swap it in live components (hot update).
const oldTextureHandle = this.textureCache_.get(this.textureCacheKey_(path, true))?.handle ?? 0;
@@ -1682,13 +1710,14 @@ 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;
- void this.registrySlots_.republish(kind, type, path).catch((e: unknown) => {
+ 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);
- });
+ }));
}
// Loader-owned residency (e.g. the AudioAPI warm cache) can outlive
@@ -1708,7 +1737,7 @@ export class Assets {
for (const [type, oldValue] of dropped) this.fireInvalidate_({ ref, type, oldValue });
- return hit;
+ return { hit, rebuilt: Promise.all(republished).then(() => undefined) };
}
/** Fire every onInvalidate listener with one generation's ending. Isolates
diff --git a/sdk/src/asset/dependencies.ts b/sdk/src/asset/dependencies.ts
index 32a65d572..dcd7a0e76 100644
--- a/sdk/src/asset/dependencies.ts
+++ b/sdk/src/asset/dependencies.ts
@@ -71,6 +71,51 @@ export interface Preparation {
readonly edges: readonly DependencyReceipt[];
}
+/**
+ * What to rebuild after `changed` changed, deepest dependency first, each cycle
+ * one group. `A takes B` while B read A is a real shape: what has to be acyclic
+ * is the plan, which is this graph's condensation. Tarjan emits a group after
+ * everything it reaches, so the list is reversed at the end.
+ */
+export function rebuildPlan(
+ changed: string, dependents: (path: string) => readonly string[],
+): string[][] {
+ const index = new Map<string, number>();
+ const low = new Map<string, number>();
+ const open = new Set<string>();
+ const stack: string[] = [];
+ const groups: string[][] = [];
+ let next = 0;
+
+ const visit = (node: string): void => {
+ index.set(node, next);
+ low.set(node, next);
+ next++;
+ stack.push(node);
+ open.add(node);
+ for (const parent of dependents(node)) {
+ if (!index.has(parent)) {
+ visit(parent);
+ low.set(node, Math.min(low.get(node)!, low.get(parent)!));
+ } else if (open.has(parent)) {
+ low.set(node, Math.min(low.get(node)!, index.get(parent)!));
+ }
+ }
+ if (low.get(node) !== index.get(node)) return;
+ const group: string[] = [];
+ for (;;) {
+ const member = stack.pop()!;
+ open.delete(member);
+ group.push(member);
+ if (member === node) break;
+ }
+ groups.push(group);
+ };
+
+ visit(changed);
+ return groups.reverse();
+}
+
/**
* What a handle-bound load produced, and what its preparation took — the same
* sealing an era gets, for the asset kind whose current value lives in a cache
diff --git a/sdk/tests/asset-dependencies.test.ts b/sdk/tests/asset-dependencies.test.ts
index 9c360374e..b0386da01 100644
--- a/sdk/tests/asset-dependencies.test.ts
+++ b/sdk/tests/asset-dependencies.test.ts
@@ -447,3 +447,112 @@ describe('what must be rebuilt when this changes', () => {
expect(assets.dependentsOf('maps/terrain.tsj')).toEqual([]);
});
});
+
+/** Let every pending load, republish and image decode settle. */
+async function settled(): Promise<void> {
+ for (let i = 0; i < 8; i++) await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+describe('a change reaches what was built from it', () => {
+ beforeEach(() => { pool = createPoolFake(); materialFake.reset(); });
+
+ it('a map rebuilds when the tileset it folded in changes', async () => {
+ // Nothing of the .tsj is held — it is not an asset, it is content the map
+ // READ. Without the source edge a change to it could never reach anyone.
+ const docs: Record<string, string> = {
+ 'level.tmj': MAP_WITH_EXTERNAL, 'terrain.tsj': EXTERNAL_TILESET,
+ };
+ const assets = realm(docs);
+ await assets.acquireTyped('tilemap', 'maps/level.tmj');
+ expect(assets.dependenciesOf('tilemap', 'maps/level.tmj'))
+ .toContainEqual({ kind: 'owned', type: 'texture', path: 'maps/terrain.png' });
+
+ docs['terrain.tsj'] = JSON.stringify({
+ name: 'terrain', image: 'winter.png', columns: 2, tilecount: 4,
+ tilewidth: 4, tileheight: 4,
+ });
+ assets.invalidate('maps/terrain.tsj');
+ await settled();
+
+ expect(assets.dependenciesOf('tilemap', 'maps/level.tmj'))
+ .toContainEqual({ kind: 'owned', type: 'texture', path: 'maps/winter.png' });
+ expect(pool.liveTextures(), 'the era it replaced gave its texture back').toBe(1);
+ });
+
+ /** A chain: a texture, the asset that takes it, and the asset that takes that. */
+ function chain(assets: Assets, events: string[]): void {
+ assets.register({
+ type: 'child', extensions: ['.child'],
+ registry: {
+ prepare: async (path, ctx) => {
+ events.push('child:start');
+ await ctx.acquireTexture('skin.png');
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ events.push('child:end');
+ return { published: { path }, value: { id: path } };
+ },
+ },
+ });
+ assets.register({
+ type: 'parent', extensions: ['.parent'],
+ registry: {
+ prepare: async (path, ctx) => {
+ events.push('parent:start');
+ await ctx.acquireAsset('child', 'c.child');
+ events.push('parent:end');
+ return { published: { path }, value: { id: path } };
+ },
+ },
+ });
+ }
+
+ it('the child rebuilds before the parent that took it', async () => {
+ // A parent re-prepared first would acquire the era it already had. The
+ // order is the plan's, and the plan is the graph read backwards.
+ const events: string[] = [];
+ const assets = realm({});
+ chain(assets, events);
+ await assets.acquireTyped('parent', 'p.parent');
+ events.length = 0;
+
+ assets.invalidate('skin.png');
+ await settled();
+
+ expect(events).toEqual(['child:start', 'child:end', 'parent:start', 'parent:end']);
+ });
+
+ it('a cycle is a plan of one group, not a hang', async () => {
+ // `A takes B` while B READ A is a real shape. What must be acyclic is the
+ // plan, which is this graph's condensation — so each of them rebuilds
+ // once and the walk terminates.
+ const prepared: string[] = [];
+ const assets = realm({ 'a.aa': '{}', 'b.bb': '{}' });
+ assets.register({
+ type: 'aa', extensions: ['.aa'],
+ registry: {
+ prepare: async (path, ctx) => {
+ prepared.push('aa');
+ await ctx.acquireAsset('bb', 'b.bb');
+ return { published: { path }, value: { id: path } };
+ },
+ },
+ });
+ assets.register({
+ type: 'bb', extensions: ['.bb'],
+ registry: {
+ prepare: async (path, ctx) => {
+ prepared.push('bb');
+ await ctx.readSource!('a.aa');
+ return { published: { path }, value: { id: path } };
+ },
+ },
+ });
+ await assets.acquireTyped('aa', 'a.aa');
+ prepared.length = 0;
+
+ assets.invalidate('a.aa');
+ await settled();
+
+ expect(prepared).toEqual(['aa', 'bb']);
+ });
+});