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
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.tsindex 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.tsindex 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 emitdiff --git a/desktop/electron/preload.ts b/desktop/electron/preload.tsindex 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.tsindex 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> {