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
fix(assets): a rebuild plan's vertices are assets, not the paths they carry
esengine7f24e3526306
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 32ebcbbef..1e98e0707 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -766,7 +766,7 @@ ResourceDef<AssetsClass>@internal appScope: AssetScope@internal assetGraphSettled: () => Promise<void>@internal dependenciesOf: (type: string, ref: string) => readonly DependencyReceipt[]-@internal dependentsOf: (ref: string) => AssetIdentity[]+@internal dependentsOf: (ref: string, type?: string) => AssetIdentity[]@internal entityScopes: EntityAssetScopes@internal handleBoundTypes: () => string[]@internal publishedRegistryAssets: <T>(type: string) => T[]diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 6a51294c8..64dbc552a 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -766,7 +766,7 @@ ResourceDef<AssetsClass>@internal appScope: AssetScope@internal assetGraphSettled: () => Promise<void>@internal dependenciesOf: (type: string, ref: string) => readonly DependencyReceipt[]-@internal dependentsOf: (ref: string) => AssetIdentity[]+@internal dependentsOf: (ref: string, type?: string) => AssetIdentity[]@internal entityScopes: EntityAssetScopes@internal handleBoundTypes: () => string[]@internal publishedRegistryAssets: <T>(type: string) => T[]diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 40db2e553..3e438c9e8 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -761,7 +761,7 @@ ResourceDef<AssetsClass>@internal appScope: AssetScope@internal assetGraphSettled: () => Promise<void>@internal dependenciesOf: (type: string, ref: string) => readonly DependencyReceipt[]-@internal dependentsOf: (ref: string) => AssetIdentity[]+@internal dependentsOf: (ref: string, type?: string) => AssetIdentity[]@internal entityScopes: EntityAssetScopes@internal handleBoundTypes: () => string[]@internal publishedRegistryAssets: <T>(type: string) => T[]diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 2161671f4..9b756a378 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -761,7 +761,7 @@ ResourceDef<AssetsClass>@internal appScope: AssetScope@internal assetGraphSettled: () => Promise<void>@internal dependenciesOf: (type: string, ref: string) => readonly DependencyReceipt[]-@internal dependentsOf: (ref: string) => AssetIdentity[]+@internal dependentsOf: (ref: string, type?: string) => AssetIdentity[]@internal entityScopes: EntityAssetScopes@internal handleBoundTypes: () => string[]@internal publishedRegistryAssets: <T>(type: string) => T[]diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 52d29efd7..dd7f10a65 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -761,7 +761,7 @@ ResourceDef<AssetsClass>@internal appScope: AssetScope@internal assetGraphSettled: () => Promise<void>@internal dependenciesOf: (type: string, ref: string) => readonly DependencyReceipt[]-@internal dependentsOf: (ref: string) => AssetIdentity[]+@internal dependentsOf: (ref: string, type?: string) => AssetIdentity[]@internal entityScopes: EntityAssetScopes@internal handleBoundTypes: () => string[]@internal publishedRegistryAssets: <T>(type: string) => T[]diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex fdc639ce7..7e600a723 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -1690,11 +1690,12 @@ export class Assets {}}- /** What a change to `ref` reaches, after `ref` itself. */- private rebuildPlan_(ref: string): string[][] {+ /** What a change to `ref` reaches, after `ref` itself: this call ends its own+ * era, and a cycle back to it must not end it twice. */+ private rebuildPlan_(ref: string): AssetIdentity[][] {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);+ const plan = rebuildPlan(root, (path, type) => this.dependentsOf(path, type));+ return plan.map((group) => group.filter((v) => v.path !== root)).filter((g) => g.length > 0);}/** Count one propagation as in flight until it lands. It answers to nobody@@ -1709,9 +1710,9 @@ export class Assets {}/** Each group only once everything it was built from has landed. */- private async rebuildAssetGraph_(plan: string[][]): Promise<void> {+ private async rebuildAssetGraph_(plan: AssetIdentity[][]): Promise<void> {for (const group of plan) {- await Promise.all(group.map((path) => this.invalidateOne_(path).rebuilt));+ await Promise.all(group.map((vertex) => this.invalidateOne_(vertex.path).rebuilt));}}@@ -2205,7 +2206,7 @@ export class Assets {** @internal*/- dependentsOf(ref: string): AssetIdentity[] {+ dependentsOf(ref: string, type?: string): AssetIdentity[] {const canonical = new Map<string, string>();const identify = (path: string): string => {let known = canonical.get(path);@@ -2216,10 +2217,14 @@ export class Assets {return known;};const target = identify(ref);+ // An acquisition names an ASSET, so a type narrows it; a source read+ // names CONTENT, which is the same file whatever else lives at it.+ const names = (e: DependencyReceipt): boolean =>+ isInvalidatable(e) && identify(e.path) === target+ && (type === undefined || e.kind === 'source' || e.type === type);const out: AssetIdentity[] = [];for (const era of this.eras_()) {- const took = era.edges.some((e) => isInvalidatable(e) && identify(e.path) === target);- if (took) out.push({ type: era.type, path: era.path });+ if (era.edges.some(names)) out.push({ type: era.type, path: era.path });}return out;}diff --git a/sdk/src/asset/dependencies.ts b/sdk/src/asset/dependencies.tsindex dcd7a0e76..33bf8ad7f 100644--- a/sdk/src/asset/dependencies.ts+++ b/sdk/src/asset/dependencies.ts@@ -73,46 +73,54 @@ export interface Preparation {/*** 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.+ * one group. The root is a PATH (a change names a file, which need not be an+ * asset); every vertex after it keeps its TYPE, since flattening two assets that+ * share a path invents a cycle between them. Tarjan emits last-reached first.*/export function rebuildPlan(- changed: string, dependents: (path: string) => readonly string[],-): string[][] {+ changed: string,+ dependents: (path: string, type?: string) => readonly AssetIdentity[],+): AssetIdentity[][] {const index = new Map<string, number>();const low = new Map<string, number>();const open = new Set<string>();- const stack: string[] = [];- const groups: string[][] = [];+ const stack: AssetIdentity[] = [];+ const groups: AssetIdentity[][] = [];let next = 0;+ const keyOf = (id: AssetIdentity): string => `${id.type}\0${id.path}`;- const visit = (node: string): void => {- index.set(node, next);- low.set(node, next);+ const visit = (node: AssetIdentity): void => {+ const key = keyOf(node);+ index.set(key, next);+ low.set(key, next);next++;stack.push(node);- open.add(node);- for (const parent of dependents(node)) {- if (!index.has(parent)) {+ open.add(key);+ for (const parent of dependents(node.path, node.type)) {+ const above = keyOf(parent);+ if (!index.has(above)) {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)!));+ low.set(key, Math.min(low.get(key)!, low.get(above)!));+ } else if (open.has(above)) {+ low.set(key, Math.min(low.get(key)!, index.get(above)!));}}- if (low.get(node) !== index.get(node)) return;- const group: string[] = [];+ if (low.get(key) !== index.get(key)) return;+ const group: AssetIdentity[] = [];for (;;) {const member = stack.pop()!;- open.delete(member);+ open.delete(keyOf(member));group.push(member);- if (member === node) break;+ if (keyOf(member) === key) break;}groups.push(group);};- visit(changed);+ // A forest, not a tree: the changed file can be read by several assets, and+ // one already visited through another root is not visited again.+ for (const root of dependents(changed)) {+ if (!index.has(keyOf(root))) visit(root);+ }return groups.reverse();}diff --git a/sdk/tests/rebuild-plan.test.ts b/sdk/tests/rebuild-plan.test.tsnew file mode 100644index 000000000..314da3052--- /dev/null+++ b/sdk/tests/rebuild-plan.test.ts@@ -0,0 +1,81 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file rebuild-plan.test.ts+ * @brief The order to rebuild in, over ASSETS rather than over paths.+ *+ * @details A change names a file; everything that follows from it is an asset,+ * and an asset is (type, path). Flattening the vertices to the paths+ * they carry looks harmless while every path means one asset — and+ * silently invents cycles the moment two of them share a file.+ */+import { describe, it, expect } from 'vitest';+import { rebuildPlan } from '../src/asset/dependencies';+import type { AssetIdentity } from '../src/asset/dependencies';++/** A reverse graph as a table: what depends on (path, type). */+function graph(edges: Record<string, AssetIdentity[]>) {+ return (path: string, type?: string): readonly AssetIdentity[] =>+ edges[type === undefined ? path : `${type}:${path}`] ?? [];+}++describe('a rebuild plan is over assets, not over paths', () => {+ it('the deepest dependency comes first, each cycle one group', () => {+ const plan = rebuildPlan('terrain.png', graph({+ 'terrain.png': [{ type: 'tileset', path: 'terrain.estileset' }],+ 'tileset:terrain.estileset': [{ type: 'tilemap', path: 'level.tmj' }],+ }));++ expect(plan).toEqual([+ [{ type: 'tileset', path: 'terrain.estileset' }],+ [{ type: 'tilemap', path: 'level.tmj' }],+ ]);+ });++ it('two assets under one path stay two vertices', () => {+ // The chain is a→b→a', where a and a' share a path and nothing else. As+ // paths it reads as a cycle between two of them, which collapses three+ // rebuilds into one group and loses the order between them.+ const plan = rebuildPlan('x', graph({+ x: [{ type: 'aa', path: 'p' }],+ 'aa:p': [{ type: 'bb', path: 'q' }],+ 'bb:q': [{ type: 'cc', path: 'p' }],+ }));++ expect(plan).toEqual([+ [{ type: 'aa', path: 'p' }],+ [{ type: 'bb', path: 'q' }],+ [{ type: 'cc', path: 'p' }],+ ]);+ });++ it('a real cycle is one group, not a hang', () => {+ const plan = rebuildPlan('x', graph({+ x: [{ type: 'aa', path: 'a' }],+ 'aa:a': [{ type: 'bb', path: 'b' }],+ 'bb:b': [{ type: 'aa', path: 'a' }],+ }));++ expect(plan).toHaveLength(1);+ expect(plan[0]).toEqual(expect.arrayContaining([+ { type: 'aa', path: 'a' }, { type: 'bb', path: 'b' },+ ]));+ });++ it('a file two assets read fans out to both, and each is visited once', () => {+ const plan = rebuildPlan('shared.tsj', graph({+ 'shared.tsj': [{ type: 'tilemap', path: 'a.tmj' }, { type: 'tilemap', path: 'b.tmj' }],+ 'tilemap:a.tmj': [{ type: 'scene', path: 'level.esscene' }],+ 'tilemap:b.tmj': [{ type: 'scene', path: 'level.esscene' }],+ }));++ expect(plan.flat().filter((v) => v.path === 'level.esscene')).toHaveLength(1);+ const order = plan.flat().map((v) => v.path);+ expect(order.indexOf('level.esscene'), 'a scene rebuilt before the maps it holds')+ .toBeGreaterThan(order.indexOf('b.tmj'));+ });++ it('nothing depends on it, so there is nothing to do', () => {+ expect(rebuildPlan('lonely.png', graph({}))).toEqual([]);+ });+});