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.

perf(editor): cache-first asset registry — the disk scan no longer gates boot

yhh7350303db92b
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.ts
index 76b4e3433..d1ce20866 100644
--- a/desktop/electron/assetDb.ts
+++ b/desktop/electron/assetDb.ts
@@ -204,6 +204,30 @@ async function mapLimit<T, R>(
/** Reads in flight during the scan's meta-walk and dependency-graph passes. */
const SCAN_IO_CONCURRENCY = 48;
+/**
+ * Read the cached asset index (assets.json) WITHOUT walking the tree. The boot
+ * path uses this to build the registry immediately — the full O(files) scan
+ * (~1.5s cold on an 800-file project, dominated by per-file disk reads) then
+ * runs off the critical path to catch anything changed while the project was
+ * closed. Returns null when the cache is absent/unparseable/malformed, so the
+ * caller falls back to a full scan (first-ever open of a project).
+ */
+export async function readCachedAssetIndex(root: string): Promise<AssetIndex | null> {
+ try {
+ const raw = JSON.parse(await readFile(path.join(root, CACHE_DIR, OUTPUT), 'utf8'));
+ if (raw && Array.isArray(raw.entries)) {
+ return {
+ version: typeof raw.version === 'string' ? raw.version : '1.0',
+ entries: raw.entries as AssetEntry[],
+ deps: (raw.deps as Record<string, string[]>) ?? {},
+ };
+ }
+ } catch {
+ // missing or malformed — caller falls back to a full scan
+ }
+ return null;
+}
+
/**
* Scan `root` for `.meta` sidecars → build the asset index (registry + dep
* graph) and (unless `write: false`) write `.esengine/cache/assets.json`.
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index e05313906..c51af5718 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -23,7 +23,7 @@ import {
import { listRecents, addRecent, removeRecent, listTemplates, createFromTemplate } from './launcher';
import { buildProjectScripts } from './buildScripts';
import { extractProjectSchemas } from './extractSchemas';
-import { scanAssetDatabase } from './assetDb';
+import { scanAssetDatabase, readCachedAssetIndex } from './assetDb';
import { cookAssets } from './cookAssets';
import { startProjectWatch, stopProjectWatch } from './projectWatcher';
import { importAssets, createAsset, IMPORT_EXTENSIONS } from './importAssets';
@@ -587,6 +587,9 @@ ipcMain.handle('project:extractSchemas', async () => {
// this into the engine Assets registry (one resolution path) and the Content
// Browser; the cook walks `deps` (REARCH_ASSETS.md A2).
ipcMain.handle('project:scanAssets', async () => scanAssetDatabase(requireRoot()));
+// Fast boot path: the cached index without a tree walk (renderer revalidates via
+// scanAssets off the critical path). See ProjectStore.buildAssetRegistry.
+ipcMain.handle('project:cachedAssetIndex', async () => readCachedAssetIndex(requireRoot()));
// Cook the project's assets for shipping: from the entry scene, walk the
// dependency graph to the reachable assets, stage them into `outDir`, and emit
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index 01799eb40..a3e15e8cc 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -4,7 +4,7 @@ import { contextBridge, ipcRenderer, webUtils } from 'electron';
import type { OpenedProject, WorkspaceState, DirEntry, RecentEntry, TemplateEntry } from '../src/project/format';
import type { BuildScriptsResult } from './buildScripts';
import type { ExtractSchemasResult } from './extractSchemas';
-import type { ScanAssetsResult } from './assetDb';
+import type { ScanAssetsResult, AssetIndex } from './assetDb';
import type { CookResult } from './cookAssets';
import type { ExportGameResult } from './exportGame';
import type { PlayRealmResult } from './buildPlayRealm';
@@ -84,6 +84,9 @@ const api = {
extractSchemas: (): Promise<ExtractSchemasResult> => ipcRenderer.invoke('project:extractSchemas'),
/** Scan the project's .meta sidecars → the asset index (registry + dep graph). */
scanAssets: (): Promise<ScanAssetsResult> => ipcRenderer.invoke('project:scanAssets'),
+ /** The cached asset index (assets.json) without a tree walk, or null — the fast
+ * boot registry, revalidated by a full scanAssets off the critical path. */
+ cachedAssetIndex: (): Promise<AssetIndex | null> => ipcRenderer.invoke('project:cachedAssetIndex'),
/** Cook reachable assets for shipping → staged files + runtime manifest in `outDir`. */
cookAssets: (outDir?: string): Promise<CookResult> => ipcRenderer.invoke('project:cookAssets', outDir),
/** Export a runnable web build (play==ship) → self-contained `outDir` (default dist-game/). */
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index e766acecf..2091ac755 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -149,6 +149,10 @@ function unknownComponentTypes(data: SceneData): string[] {
return [...unknown];
}
+/** An asset index entry as the registry consumes it (from scanAssets or the
+ * cached assets.json — same shape). */
+type AssetEntryLite = { uuid: string; path: string; type?: string; importer?: Record<string, unknown> };
+
class ProjectStoreImpl {
private readonly store = createStore<{ project: ProjectState | null }>(() => ({ project: null }));
/** uuid → project-relative path, scanned from `.meta` sidecars — the editor's
@@ -172,6 +176,8 @@ class ProjectStoreImpl {
/** Resolved path → error message for live loads that FAILED — diagnostics
* surfaces these (the model looks fine; only the load knows it's broken). */
private readonly assetLoadFailures = new Map<string, string>();
+ /** Guards the off-critical-path asset revalidation after a cache-first boot. */
+ private revalidating = false;
/** The latest scene preload result; the Reconciler resolver reads handles from
* it for entities recreated incrementally (duplicate / undo / play-stop). */
private lastAssetResult: PreloadResult | null = null;
@@ -348,9 +354,9 @@ class ProjectStoreImpl {
);
}
// Build the uuid→path registry first (prefab + texture refs resolve through it).
- // This runs the full project-wide asset scan (O(files)) on every open — the
- // usual boot-time hot spot on asset-heavy projects, so it gets its own phase.
- await bootProfiler.phase('scanAssets', () => this.buildAssetRegistry());
+ // Cache-first so the full O(files) disk scan doesn't gate engine-ready — it
+ // revalidates in the background (see buildAssetRegistry).
+ await bootProfiler.phase('scanAssets', () => this.buildAssetRegistry({ preferCache: true }));
// Expand prefab-instance entries into ordinary tagged entities (the model is
// always expanded; the file stores deltas). Internal
@@ -476,26 +482,47 @@ class ProjectStoreImpl {
* asset-resolution path: `Assets.resolveRef` turns `@uuid:` → path, the backend
* fetches `estella://project/<path>`.
*/
- private async buildAssetRegistry(): Promise<void> {
+ private async buildAssetRegistry(opts?: { preferCache?: boolean }): Promise<void> {
if (!this.state) return;
- let entries: { uuid: string; path: string; type?: string; importer?: Record<string, unknown> }[];
- let adopted: string[] = [];
+ // Cache-first (boot): the O(files) disk scan is ~1.5s cold on an asset-heavy
+ // project and gates the "engine ready" overlay. The cached assets.json is
+ // almost always current (the fs watcher keeps it live while open), so build
+ // the registry from it immediately and revalidate with the authoritative
+ // scan OFF the critical path — only re-projecting if something changed while
+ // the project was closed.
+ if (opts?.preferCache) {
+ const cached = await window.estella.project.cachedAssetIndex().catch(() => null);
+ if (cached) {
+ this.populateRegistry(cached.entries);
+ void this.revalidateAssets();
+ return;
+ }
+ // No cache (first-ever open) → fall through to a full, blocking scan.
+ }
+ const entries = await this.scanAssetsReporting();
+ if (entries) this.populateRegistry(entries);
+ }
+
+ /** Run the authoritative scan; report its boot timing + any adopted orphans. */
+ private async scanAssetsReporting(): Promise<AssetEntryLite[] | null> {
try {
const scan = await window.estella.project.scanAssets();
- ({ entries } = scan.index);
- adopted = scan.adopted ?? [];
- // Fold the main-process scan's sub-phase split into the 'scanAssets' boot phase.
if (scan.timingMs) bootProfiler.detail('scanAssets', scan.timingMs);
+ if ((scan.adopted?.length ?? 0) > 0) {
+ console.info(
+ `[assets] adopted ${scan.adopted.length} file(s) that had no .meta — they are now registered assets`,
+ scan.adopted,
+ );
+ }
+ return scan.index.entries;
} catch (err) {
console.warn('[project] asset scan failed', err);
- return;
- }
- if (adopted.length > 0) {
- console.info(
- `[assets] adopted ${adopted.length} file(s) that had no .meta — they are now registered assets`,
- adopted,
- );
+ return null;
}
+ }
+
+ /** Rebuild the uuid↔path registry + Assets resolvers from an index's entries. */
+ private populateRegistry(entries: readonly AssetEntryLite[]): void {
this.uuidToPath.clear();
this.pathToUuid.clear();
this.uuidToImporter.clear();
@@ -521,6 +548,29 @@ class ProjectStoreImpl {
}
}
+ /** Off-critical-path authoritative scan after a cache-first boot: repopulate +
+ * re-project only the paths that changed while the project was closed (the
+ * common case is zero changes → a pure no-op). */
+ private async revalidateAssets(): Promise<void> {
+ if (this.revalidating) return;
+ this.revalidating = true;
+ try {
+ const entries = await this.scanAssetsReporting();
+ if (!entries) return;
+ const fresh = new Map<string, string>();
+ for (const e of entries) fresh.set(e.path, e.uuid.toLowerCase());
+ const changed: string[] = [];
+ for (const [p, u] of fresh) if (this.pathToUuid.get(p) !== u) changed.push(p);
+ for (const p of this.pathToUuid.keys()) if (!fresh.has(p)) changed.push(p); // removed
+ if (changed.length === 0) return; // the cache was authoritative — nothing to do
+ console.info(`[assets] revalidation: ${changed.length} asset change(s) since the project was last open`);
+ this.populateRegistry(entries);
+ this.hotSyncChangedPaths(changed);
+ } finally {
+ this.revalidating = false;
+ }
+ }
+
/** The texture filter/wrap for a ref (`@uuid:` or path), from its `.meta`
* importer — the shape `Assets`'s TextureLoader consumes. Undefined ⇒ defaults. */
private textureImportFor(ref: string): ReturnType<typeof readTextureImportSettings> {