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 change rebuilds what was built from it, deepest first
esenginea5b03b0583dd
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 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. Isolatesdiff --git a/sdk/src/asset/dependencies.ts b/sdk/src/asset/dependencies.tsindex 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 cachediff --git a/sdk/tests/asset-dependencies.test.ts b/sdk/tests/asset-dependencies.test.tsindex 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']);+ });+});