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.

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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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([]);
+ });
+});