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): incremental asset index, entity-ref reverse index, merged multi-select outline

esengine9352e8895406
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.ts
index d1ce20866..c4cf7c04c 100644
--- a/desktop/electron/assetDb.ts
+++ b/desktop/electron/assetDb.ts
@@ -16,9 +16,10 @@
* main.ts. The `.meta` files carry the authored `type`, so this needs no
* extension→type table — it reads the type each meta already declares.
*/
-import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
import path from 'node:path';
-import { META_EXT, isContentDir, isContentFile } from './contentPolicy';
+import { META_EXT, isContentDir, isContentFile, isNonContentPath } from './contentPolicy';
import { adoptOrphan } from './assetMeta';
// The runtime's tileset-path resolver (a dependency-free leaf) — shared so the dep scan
// discovers a tilemap's tileset images the same way the loader will later request them.
@@ -204,6 +205,92 @@ async function mapLimit<T, R>(
/** Reads in flight during the scan's meta-walk and dependency-graph passes. */
const SCAN_IO_CONCURRENCY = 48;
+/**
+ * Build the dependency edges for `targets` (default: every ref-carrying entry),
+ * resolving refs against the FULL `entries` set. Any JSON asset can reference
+ * others by uuid or by path (project-relative, or relative to the referencing
+ * document); only strings naming a real asset create edges — no false positives.
+ * Returns a partial deps map (`uuid → sorted ref uuids`, edge-bearing only) so the
+ * incremental path can recompute just the touched assets and merge over the rest.
+ */
+async function computeDeps(
+ root: string,
+ entries: readonly AssetEntry[],
+ targets?: readonly AssetEntry[],
+): Promise<{ deps: Record<string, string[]>; warnings: string[] }> {
+ const byPath = new Map(entries.map((e) => [e.path, e]));
+ const uuids = new Set(entries.map((e) => e.uuid));
+ const refEntries = (targets ?? entries).filter(
+ (e) => JSON_REF_TYPES.has(e.type) || getEditorType(e.path) === 'spine-atlas',
+ );
+ type DepResult = { uuid: string; refs: string[] } | { warning: string };
+ const depResults = await mapLimit(refEntries, SCAN_IO_CONCURRENCY, async (entry): Promise<DepResult> => {
+ // A spine `.atlas` is a TEXT manifest (not JSON): its page image names are
+ // texture deps — the same edge the SpineAssetLoader walks at runtime. Scan it
+ // apart from the JSON path so the cook embeds those textures (else the atlas
+ // ships but its .png is culled and the playable 404s it).
+ const isSpineAtlas = getEditorType(entry.path) === 'spine-atlas';
+ try {
+ const refs = new Set<string>();
+ if (isSpineAtlas) {
+ const content = await readFile(path.join(root, entry.path), 'utf8');
+ for (const page of parseSpineAtlasPages(content)) {
+ const dep = byPath.get(normalizeRefPath(resolveRelativePath(entry.path, page)));
+ if (dep) refs.add(dep.uuid);
+ }
+ } else {
+ const json = JSON.parse(await readFile(path.join(root, entry.path), 'utf8'));
+ collectRefs(json, refs, (ref) => {
+ if (ref.includes('://')) return null;
+ const direct = byPath.get(normalizeRefPath(ref));
+ if (direct) return direct.uuid;
+ // Fall back to a path RELATIVE to the referencing document, resolved the way
+ // the runtime loads it (collapsing ./ and ../) — so a Tiled tileset image
+ // "../textures/tileset.png" or a material's sibling "x.esshader" resolves to
+ // the same asset the loader will request. (The old join left "../" uncollapsed,
+ // so tilemap tileset images never linked and the cook culled them → the
+ // single-file playable 404'd them.)
+ const rel = byPath.get(normalizeRefPath(resolveRelativePath(entry.path, ref)));
+ return rel?.uuid ?? null;
+ }, (id) => uuids.has(id));
+ }
+ refs.delete(entry.uuid);
+ return { uuid: entry.uuid, refs: [...refs].sort() };
+ } catch (err) {
+ return { warning: `${entry.path}: ${err instanceof Error ? err.message : String(err)}` };
+ }
+ });
+ const deps: Record<string, string[]> = {};
+ const warnings: string[] = [];
+ for (const r of depResults) {
+ if ('warning' in r) warnings.push(r.warning);
+ else if (r.refs.length > 0) deps[r.uuid] = r.refs;
+ }
+ return { deps, warnings };
+}
+
+/**
+ * Write `.esengine/cache/assets.json` only when its bytes actually change. The
+ * watcher can't tell our cache write from a real edit, so an unconditional write
+ * would make every refresh re-trigger itself (scan → write → fsChanged → scan …).
+ * Returns the artifact path.
+ */
+async function writeIndexIfChanged(root: string, index: AssetIndex): Promise<string> {
+ const outputPath = path.join(root, CACHE_DIR, OUTPUT);
+ const text = JSON.stringify(index, null, 2) + '\n';
+ let previous: string | null = null;
+ try {
+ previous = await readFile(outputPath, 'utf8');
+ } catch {
+ previous = null;
+ }
+ if (previous !== text) {
+ await mkdir(path.dirname(outputPath), { recursive: true });
+ await writeFile(outputPath, text);
+ }
+ return outputPath;
+}
+
/**
* 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
@@ -284,81 +371,14 @@ export async function scanAssetDatabase(
t.walk = performance.now() - tWalk;
const tDeps = performance.now();
- // Dependency graph: any JSON asset can reference others — by uuid or by path
- // (project-relative like a scene's "assets/materials/x.esmaterial", or
- // relative to the referencing document's own directory like a material's
- // "shader": "x.esshader"). Path refs resolve against the index, so only
- // strings naming a real asset create edges — no false positives.
- const byPath = new Map(entries.map((e) => [e.path, e]));
- const uuids = new Set(entries.map((e) => e.uuid));
- const deps: Record<string, string[]> = {};
- // Only JSON-ref assets + spine atlases carry edges; read those (the cost) in
- // parallel and assemble in order so warnings/deps stay deterministic.
- const refEntries = entries.filter((e) => JSON_REF_TYPES.has(e.type) || getEditorType(e.path) === 'spine-atlas');
- type DepResult = { uuid: string; refs: string[] } | { warning: string };
- const depResults = await mapLimit(refEntries, SCAN_IO_CONCURRENCY, async (entry): Promise<DepResult> => {
- // A spine `.atlas` is a TEXT manifest (not JSON): its page image names are
- // texture deps — the same edge the SpineAssetLoader walks at runtime. Scan it
- // apart from the JSON path so the cook embeds those textures (else the atlas
- // ships but its .png is culled and the playable 404s it).
- const isSpineAtlas = getEditorType(entry.path) === 'spine-atlas';
- try {
- const refs = new Set<string>();
- if (isSpineAtlas) {
- const content = await readFile(path.join(root, entry.path), 'utf8');
- for (const page of parseSpineAtlasPages(content)) {
- const dep = byPath.get(normalizeRefPath(resolveRelativePath(entry.path, page)));
- if (dep) refs.add(dep.uuid);
- }
- } else {
- const json = JSON.parse(await readFile(path.join(root, entry.path), 'utf8'));
- collectRefs(json, refs, (ref) => {
- if (ref.includes('://')) return null;
- const direct = byPath.get(normalizeRefPath(ref));
- if (direct) return direct.uuid;
- // Fall back to a path RELATIVE to the referencing document, resolved the way
- // the runtime loads it (collapsing ./ and ../) — so a Tiled tileset image
- // "../textures/tileset.png" or a material's sibling "x.esshader" resolves to
- // the same asset the loader will request. (The old join left "../" uncollapsed,
- // so tilemap tileset images never linked and the cook culled them → the
- // single-file playable 404'd them.)
- const rel = byPath.get(normalizeRefPath(resolveRelativePath(entry.path, ref)));
- return rel?.uuid ?? null;
- }, (id) => uuids.has(id));
- }
- refs.delete(entry.uuid);
- return { uuid: entry.uuid, refs: [...refs].sort() };
- } catch (err) {
- return { warning: `${entry.path}: ${err instanceof Error ? err.message : String(err)}` };
- }
- });
- for (const r of depResults) {
- if ('warning' in r) warnings.push(r.warning);
- else if (r.refs.length > 0) deps[r.uuid] = r.refs;
- }
+ const { deps, warnings: depWarnings } = await computeDeps(root, entries);
+ warnings.push(...depWarnings);
t.deps = performance.now() - tDeps;
const index: AssetIndex = { version: '1.0', entries, deps };
const tWrite = performance.now();
- let outputPath: string | null = null;
- if (opts?.write !== false) {
- outputPath = path.join(root, CACHE_DIR, OUTPUT);
- const text = JSON.stringify(index, null, 2) + '\n';
- // Write-if-changed: the watcher can't tell our cache write from a real
- // change, so an unconditional write would make every refresh re-trigger
- // itself (scan → write → fsChanged → scan …). Unchanged index ⇒ no write.
- let previous: string | null = null;
- try {
- previous = await readFile(outputPath, 'utf8');
- } catch {
- previous = null;
- }
- if (previous !== text) {
- await mkdir(path.dirname(outputPath), { recursive: true });
- await writeFile(outputPath, text);
- }
- }
+ const outputPath = opts?.write !== false ? await writeIndexIfChanged(root, index) : null;
t.write = performance.now() - tWrite;
const round1 = (n: number): number => Math.round(n * 10) / 10;
@@ -373,3 +393,126 @@ export async function scanAssetDatabase(
return { ok: true, outputPath, index, warnings, adopted, timingMs };
}
+
+/** Above this many changed paths a full rescan is cheaper/safer than per-path
+ * work — a bulk edit (git checkout, a dropped asset folder) rather than a save. */
+export const INCREMENTAL_PATH_LIMIT = 100;
+
+/** A {@link ScanAssetsResult} plus whether the incremental path fell back to a
+ * full rescan (and why) — so the caller can log it and pick its cache strategy. */
+export type IncrementalScanResult = ScanAssetsResult & { fullRescan: boolean; reason?: string };
+
+/**
+ * Incrementally update a previous {@link AssetIndex} for exactly the `changed`
+ * paths the watcher delivered, instead of re-walking the whole tree (the full
+ * scan is ~1.5s cold, dominated by reading EVERY `.meta`). The result is what a
+ * full {@link scanAssetDatabase} of the same on-disk state would produce —
+ * identical `entries` AND `deps` — so Find Usages, delete warnings and the cook
+ * see the same graph.
+ *
+ * Falls back to a full rescan (returning `fullRescan: true` + a `reason`, never
+ * silently) for what a per-path update can't cover: an empty change set (watcher
+ * overflow, filename unknown), a bulk change above {@link INCREMENTAL_PATH_LIMIT},
+ * or a directory create/rename/move (the file moves under it aren't in `changed`).
+ */
+export async function updateAssetIndex(
+ root: string,
+ prev: AssetIndex,
+ changed: readonly string[],
+ opts?: { write?: boolean },
+): Promise<IncrementalScanResult> {
+ const full = async (reason: string): Promise<IncrementalScanResult> => ({
+ ...(await scanAssetDatabase(root, opts)),
+ fullRescan: true,
+ reason,
+ });
+
+ if (changed.length === 0) return full('watcher overflow (no paths)');
+ if (changed.length > INCREMENTAL_PATH_LIMIT) return full(`bulk change (${changed.length} paths)`);
+
+ // The content paths touched (strip `.meta` pairing; dedup — a texture edit fires
+ // both foo.png and foo.png.meta). Skip plumbing paths + the editor-managed cover.
+ const contentPaths = new Set<string>();
+ for (const raw of changed) {
+ const rel = raw.replace(/\\/g, '/');
+ if (isNonContentPath(rel)) continue;
+ const abs = path.join(root, rel);
+ let st: Awaited<ReturnType<typeof stat>> | null;
+ try { st = await stat(abs); } catch { st = null; }
+ if (st?.isDirectory()) return full(`directory changed (${rel})`);
+ const content = rel.endsWith(META_EXT) ? rel.slice(0, -META_EXT.length) : rel;
+ if (content === '' || content === 'thumbnail.png') continue;
+ // A vanished path that WAS a directory holding assets → its removed children
+ // aren't in `changed`, so only a full walk stays consistent.
+ if (!st && prev.entries.some((e) => e.path.startsWith(`${content}/`))) {
+ return full(`directory removed (${content})`);
+ }
+ contentPaths.add(content);
+ }
+ if (contentPaths.size === 0) {
+ return { ok: true, outputPath: null, index: prev, warnings: [], adopted: [], fullRescan: false };
+ }
+
+ const byPath = new Map(prev.entries.map((e) => [e.path, e] as const));
+ const adopted: string[] = [];
+ let setChanged = false; // an add/remove/uuid/type change — path resolution is global
+
+ for (const content of contentPaths) {
+ const abs = path.join(root, content);
+ const before = byPath.get(content);
+ // Reprocess the content path's CURRENT disk state — this one branch covers a
+ // content edit, a `.meta` edit, orphan adoption, and deletion (the same states
+ // a full scan resolves per file).
+ if (!existsSync(abs)) {
+ if (before) { byPath.delete(content); setChanged = true; }
+ continue;
+ }
+ if (!existsSync(abs + META_EXT)) {
+ // Orphan content with no sidecar: a full scan would mint one this pass
+ // (unknown extensions are left alone). Mirror that so it enters the index now.
+ if ((await adoptOrphan(abs)) === 'adopted') adopted.push(content);
+ else { if (before) { byPath.delete(content); setChanged = true; } continue; }
+ }
+ let meta: { uuid?: unknown; type?: unknown; importer?: unknown };
+ try {
+ meta = JSON.parse(await readFile(abs + META_EXT, 'utf8'));
+ } catch {
+ continue; // unreadable/partial .meta — a later event will settle it
+ }
+ if (typeof meta.uuid !== 'string' || typeof meta.type !== 'string') continue;
+ const entry: AssetEntry = {
+ uuid: meta.uuid.toLowerCase(),
+ path: content,
+ type: meta.type,
+ importer: (meta.importer as Record<string, unknown>) ?? {},
+ };
+ if (!before || before.uuid !== entry.uuid || before.type !== entry.type) setChanged = true;
+ byPath.set(content, entry);
+ }
+
+ const entries = [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+
+ // Deps: when the entry SET changed, path + bare-uuid resolution is global, so
+ // recompute the whole graph from the new entries (still bounded to ref-carrying
+ // assets — far fewer than every `.meta`). When only existing assets' CONTENT
+ // changed, other assets' edges can't have moved: patch just the touched
+ // ref-assets over the previous graph.
+ let deps: Record<string, string[]>;
+ const warnings: string[] = [];
+ if (setChanged) {
+ const r = await computeDeps(root, entries);
+ deps = r.deps;
+ warnings.push(...r.warnings);
+ } else {
+ deps = { ...prev.deps };
+ const touched = entries.filter((e) => contentPaths.has(e.path));
+ for (const e of touched) delete deps[e.uuid]; // clear stale before recompute
+ const r = await computeDeps(root, entries, touched);
+ Object.assign(deps, r.deps);
+ warnings.push(...r.warnings);
+ }
+
+ const index: AssetIndex = { version: '1.0', entries, deps };
+ const outputPath = opts?.write !== false ? await writeIndexIfChanged(root, index) : null;
+ return { ok: true, outputPath, index, warnings, adopted, fullRescan: false };
+}
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 062f0e0be..0672f78b3 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -26,7 +26,7 @@ import { syncAutosave, listAutosave, restoreAutosave, clearAutosave, type Autosa
import { listRecents, addRecent, removeRecent, listTemplates, createFromTemplate } from './launcher';
import { buildProjectScripts } from './buildScripts';
import { extractProjectSchemas } from './extractSchemas';
-import { scanAssetDatabase, readCachedAssetIndex } from './assetDb';
+import { scanAssetDatabase, readCachedAssetIndex, updateAssetIndex } from './assetDb';
import { cookAssets } from './cookAssets';
import { startProjectWatch, stopProjectWatch } from './projectWatcher';
import { importAssets, createAsset, IMPORT_EXTENSIONS } from './importAssets';
@@ -649,6 +649,16 @@ 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()));
+// Live sync: incrementally fold the watcher's precise changed paths into the
+// cached index instead of a full O(files) rescan on every disk touch. Falls back
+// to a full scan (fullRescan: true) when there's no cache yet or the change can't
+// be handled per-path (directory move / bulk). See ProjectStore.applyDiskChanges.
+ipcMain.handle('project:scanAssetsIncremental', async (_e, paths: string[]) => {
+ const root = requireRoot();
+ const prev = await readCachedAssetIndex(root);
+ if (!prev) return { ...(await scanAssetDatabase(root)), fullRescan: true, reason: 'no cached index' };
+ return updateAssetIndex(root, prev, paths);
+});
// 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 94116bd08..5e12432bc 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, AssetIndex } from './assetDb';
+import type { ScanAssetsResult, AssetIndex, IncrementalScanResult } from './assetDb';
import type { CookResult } from './cookAssets';
import type { ExportGameResult } from './exportGame';
import type { PlayRealmResult } from './buildPlayRealm';
@@ -87,6 +87,10 @@ const api = {
/** 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'),
+ /** Fold the watcher's precise changed paths into the cached index incrementally
+ * (no full tree walk); `fullRescan` marks a fallback to a full scan. */
+ scanAssetsIncremental: (paths: string[]): Promise<IncrementalScanResult> =>
+ ipcRenderer.invoke('project:scanAssetsIncremental', paths),
/** 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/engine/EntityRefIndex.ts b/desktop/src/engine/EntityRefIndex.ts
new file mode 100644
index 000000000..ca0a3f4e9
--- /dev/null
+++ b/desktop/src/engine/EntityRefIndex.ts
@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Reverse index of entity-reference fields: referenced source id → the
+ * components that point at it. The {@link ReconcilerImpl} consults it on
+ * spawn to re-project only the (few) components whose entity-ref field
+ * targets the just-spawned entity — undo-of-delete can restore a joint's
+ * connected body after the joint itself, and that component's World copy
+ * would otherwise keep a dead runtime id.
+ *
+ * This replaces an O(entities × components) full-model scan run on EVERY
+ * spawn (so a paste of K entities was O(K·N)). Maintained incrementally on
+ * the same mutation paths that used to trigger the scan: spawn/despawn and
+ * entity-ref field writes. Pure data (no engine/World coupling) so the
+ * maintenance logic is unit-testable in isolation.
+ */
+
+/** A component instance that points at some entity via an entity-ref field. */
+export interface Referrer {
+ entity: number;
+ comp: string;
+}
+
+const keyOf = (entity: number, comp: string): string => `${entity}|${comp}`;
+
+export class EntityRefIndex {
+ /** referrer entity → (component type → referenced source ids). The forward map
+ * is what lets a despawn drop the entity's edges without re-reading its (now
+ * gone) model components. */
+ private readonly out = new Map<number, Map<string, number[]>>();
+ /** referenced source id → set of `entity|comp` referrers — the consulted side. */
+ private readonly incoming = new Map<number, Set<string>>();
+
+ clear(): void {
+ this.out.clear();
+ this.incoming.clear();
+ }
+
+ /**
+ * Replace the entity-ref edges of one component. `refs` are the source ids its
+ * entity-ref fields currently point at; 0/negatives are the INVALID_ENTITY
+ * sentinel (mirrors the reconciler's `v > 0` projection guard) and carry no
+ * edge. An empty result drops the component from the index.
+ */
+ setReferrer(entity: number, comp: string, refs: readonly number[]): void {
+ const key = keyOf(entity, comp);
+ const entMap = this.out.get(entity);
+ const old = entMap?.get(comp);
+ if (old) for (const r of old) this.dropIncoming(r, key);
+
+ const next = refs.length ? [...new Set(refs)].filter((r) => r > 0) : [];
+ if (next.length === 0) {
+ entMap?.delete(comp);
+ if (entMap && entMap.size === 0) this.out.delete(entity);
+ return;
+ }
+ (entMap ?? this.ensureEnt(entity)).set(comp, next);
+ for (const r of next) {
+ let s = this.incoming.get(r);
+ if (!s) this.incoming.set(r, (s = new Set()));
+ s.add(key);
+ }
+ }
+
+ /** Drop every outgoing edge of an entity (its components are gone from the model). */
+ removeEntity(entity: number): void {
+ const entMap = this.out.get(entity);
+ if (!entMap) return;
+ for (const [comp, refs] of entMap) {
+ const key = keyOf(entity, comp);
+ for (const r of refs) this.dropIncoming(r, key);
+ }
+ this.out.delete(entity);
+ }
+
+ /** The components whose entity-ref field currently targets `sourceId`. */
+ referrersOf(sourceId: number): Referrer[] {
+ const s = this.incoming.get(sourceId);
+ if (!s) return [];
+ const out: Referrer[] = [];
+ for (const key of s) {
+ const sep = key.indexOf('|');
+ out.push({ entity: Number(key.slice(0, sep)), comp: key.slice(sep + 1) });
+ }
+ return out;
+ }
+
+ /** A normalized, order-independent snapshot (both directions) for equality
+ * checks — the incremental index must equal one rebuilt from scratch. */
+ snapshot(): { out: Record<number, Record<string, number[]>>; incoming: Record<number, string[]> } {
+ const out: Record<number, Record<string, number[]>> = {};
+ for (const [entity, comps] of this.out) {
+ const c: Record<string, number[]> = {};
+ for (const [comp, refs] of comps) c[comp] = [...refs].sort((a, b) => a - b);
+ out[entity] = c;
+ }
+ const incoming: Record<number, string[]> = {};
+ for (const [ref, keys] of this.incoming) incoming[ref] = [...keys].sort();
+ return { out, incoming };
+ }
+
+ private ensureEnt(entity: number): Map<string, number[]> {
+ let m = this.out.get(entity);
+ if (!m) this.out.set(entity, (m = new Map()));
+ return m;
+ }
+
+ private dropIncoming(ref: number, key: string): void {
+ const s = this.incoming.get(ref);
+ if (!s) return;
+ s.delete(key);
+ if (s.size === 0) this.incoming.delete(ref);
+ }
+}
diff --git a/desktop/src/engine/Reconciler.ts b/desktop/src/engine/Reconciler.ts
index f10629ba5..f7bba09ca 100644
--- a/desktop/src/engine/Reconciler.ts
+++ b/desktop/src/engine/Reconciler.ts
@@ -7,6 +7,7 @@ import { EngineHost } from './EngineHost';
import { PerfMonitor } from './PerfMonitor';
import { SceneModel, SceneModelImpl, type ModelEvent } from './SceneModel';
import { assetFieldType, spineSlotType, componentByName, componentDefaults, componentEntityFields, isRenderComponent, componentEnable, readonlyFieldsFor, type AnyComp, type WorldT } from './schema';
+import { EntityRefIndex } from './EntityRefIndex';
/**
* Projects the model into the World.
@@ -92,6 +93,9 @@ export class ReconcilerImpl {
private resolveAsset: AssetResolver = UNRESOLVED;
private resolveRefPath: RefPathResolver = UNRESOLVED_PATH;
private touchAsset: AssetTouchListener | null = null;
+ /** referenced source id → the components pointing at it, so a spawn re-projects
+ * its referrers in O(referrers) instead of scanning the whole model. */
+ private readonly refIndex = new EntityRefIndex();
constructor(private readonly model: SceneModelImpl) {}
@@ -195,15 +199,18 @@ export class ReconcilerImpl {
private onEvent(ev: ModelEvent): void {
switch (ev.kind) {
case 'reset':
- return; // bulk path already built the World
+ // Bulk path already built the World; only the reverse index rebuilds here.
+ return this.rebuildRefIndex();
case 'entityAdded':
return this.spawnEntity(ev.sourceId);
case 'entityRemoved':
return this.despawnEntity(ev.sourceId);
case 'componentAdded':
case 'componentChanged':
+ this.reindexComponent(ev.sourceId, ev.type);
return this.projectComponent(ev.sourceId, ev.type);
case 'componentRemoved':
+ this.refIndex.setReferrer(ev.sourceId, ev.type, []);
return this.removeComponent(ev.sourceId, ev.type);
case 'parentChanged':
return this.projectParent(ev.sourceId);
@@ -251,18 +258,16 @@ export class ReconcilerImpl {
const list = Array.isArray(refs) ? refs.filter((r): r is string => typeof r === 'string' && r !== '') : [];
if (list.length > 0) TilemapLiveSync.setLayerTilesets(rt, list);
}
- // …and re-project any spawned component whose entity-reference fields point at
- // THIS entity — undo-of-delete can restore a joint's connected body after the
- // joint itself, the same ordering the child re-link above repairs for the
- // hierarchy. Without this, that component's World copy keeps a dead runtime id.
- for (const other of this.model.allSourceEntities()) {
- if (other.id === sourceId || this.model.runtimeFor(other.id) == null) continue;
- for (const comp of other.components) {
- const refs = componentEntityFields(componentByName(comp.type));
- if (refs.some((f) => (comp.data as Record<string, unknown>)[f] === sourceId)) {
- this.projectComponent(other.id, comp.type);
- }
- }
+ // Index this entity's own entity-ref edges (so a sibling spawned later finds
+ // it), then re-project any ALREADY-SPAWNED component whose entity-ref field
+ // points at THIS entity — undo-of-delete can restore a joint's connected body
+ // after the joint itself, the same ordering the child re-link above repairs
+ // for the hierarchy. Without this, that component's World copy keeps a dead
+ // runtime id. The reverse index makes this O(referrers), not a full-model scan.
+ for (const comp of entity.components) this.indexComponent(sourceId, comp);
+ for (const { entity: refEntity, comp } of this.refIndex.referrersOf(sourceId)) {
+ if (refEntity === sourceId || this.model.runtimeFor(refEntity) == null) continue;
+ this.projectComponent(refEntity, comp);
}
}
@@ -271,6 +276,37 @@ export class ReconcilerImpl {
const rt = this.model.runtimeFor(sourceId);
if (world && rt != null && world.valid(rt)) world.despawn(rt);
this.model.unbindRuntime(sourceId);
+ this.refIndex.removeEntity(sourceId);
+ }
+
+ // ── Reverse entity-ref index ──────────────────────────────────────────────
+
+ /** Rebuild the reverse index from the whole model (bulk load / clear). */
+ private rebuildRefIndex(): void {
+ this.refIndex.clear();
+ for (const e of this.model.allSourceEntities()) {
+ for (const comp of e.components) this.indexComponent(e.id, comp);
+ }
+ }
+
+ /** Refresh the index edges for one component from its current model data. */
+ private reindexComponent(sourceId: number, type: string): void {
+ const comp = this.model.entityBySource(sourceId)?.components.find((c) => c.type === type);
+ if (comp) this.indexComponent(sourceId, comp);
+ else this.refIndex.setReferrer(sourceId, type, []);
+ }
+
+ /** Record (or clear) one component's entity-ref edges in the reverse index. */
+ private indexComponent(sourceId: number, comp: { type: string; data: unknown }): void {
+ const fields = componentEntityFields(componentByName(comp.type));
+ if (fields.length === 0) return;
+ const data = comp.data as Record<string, unknown>;
+ const refs: number[] = [];
+ for (const f of fields) {
+ const v = data[f];
+ if (typeof v === 'number') refs.push(v);
+ }
+ this.refIndex.setReferrer(sourceId, comp.type, refs);
}
private projectComponent(sourceId: number, type: string): void {
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index ab8813a11..820694542 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -430,6 +430,12 @@ function startJointAxisDrag(rt: number, type: JointGizmoType, e: ReactPointerEve
const GIZMO_SVG = 180;
const gizmoViewBox = `${-GIZMO_SVG / 2} ${-GIZMO_SVG / 2} ${GIZMO_SVG} ${GIZMO_SVG}`;
+// Above this many selected entities the per-entity outline (one wasm rect query +
+// one styled DOM div each, every rAF tick) collapses to a single merged bounding
+// box — a marquee over a large tilemap or particle scene used to select thousands
+// and thrash layout at N divs/frame. Below it the per-entity path is untouched.
+const SELECTION_OUTLINE_MERGE_THRESHOLD = 200;
+
function GizmoOverlay({ tool, active }: { tool: ToolMode; active: GizmoAxis | null }) {
const L = GIZMO.axisLen;
const B = GIZMO.boxSize;
@@ -746,6 +752,8 @@ export function Viewport() {
const designLabelRef = useRef<HTMLDivElement>(null);
// One outline div per selected entity, keyed by source id and positioned by the rAF.
const selRefs = useRef(new Map<number, HTMLDivElement | null>());
+ // The single merged-selection box shown instead, above the merge threshold.
+ const mergedSelRef = useRef<HTMLDivElement>(null);
const marqueeRef = useRef<HTMLDivElement>(null);
const tileSelRef = useRef<HTMLDivElement>(null);
const tilePreviewRef = useRef<HTMLDivElement>(null);
@@ -927,20 +935,53 @@ export function Viewport() {
const showG = useEditorStore.getState().showGizmos;
const toolMode = useEditorStore.getState().tool;
- // Per-entity selection outlines (one div per selected source id).
- const selIds: number[] = [];
- for (const [sid, el] of selRefs.current) {
- selIds.push(sid);
- if (!el) continue;
- const rt = ready ? SceneModel.runtimeFor(sid) : undefined;
- const rect = rt != null ? ViewportController.getEntityScreenRect(rt) : null;
- if (rect) {
- el.style.transform = `translate(${rect.x}px, ${rect.y}px)`;
- el.style.width = `${rect.w}px`;
- el.style.height = `${rect.h}px`;
- el.style.opacity = '1';
- } else {
- el.style.opacity = '0';
+ // Selection outlines. Below the merge threshold: one div per selected source
+ // id (crisp per-entity boxes). Above it: a single merged bounding box in one
+ // query pass + one div (the per-entity divs aren't rendered). `selIds` reads
+ // the selection store directly so the gizmo/pivot code below stays correct in
+ // both branches (above the threshold selRefs is empty).
+ const selIds = [...useSelection.getState().selectedIds];
+ const merged = mergedSelRef.current;
+ if (selIds.length > SELECTION_OUTLINE_MERGE_THRESHOLD) {
+ let minX = Infinity;
+ let minY = Infinity;
+ let maxX = -Infinity;
+ let maxY = -Infinity;
+ if (ready) {
+ for (const sid of selIds) {
+ const rt = SceneModel.runtimeFor(sid);
+ const rect = rt != null ? ViewportController.getEntityScreenRect(rt) : null;
+ if (!rect) continue;
+ minX = Math.min(minX, rect.x);
+ minY = Math.min(minY, rect.y);
+ maxX = Math.max(maxX, rect.x + rect.w);
+ maxY = Math.max(maxY, rect.y + rect.h);
+ }
+ }
+ if (merged) {
+ if (Number.isFinite(minX)) {
+ merged.style.transform = `translate(${minX}px, ${minY}px)`;
+ merged.style.width = `${maxX - minX}px`;
+ merged.style.height = `${maxY - minY}px`;
+ merged.style.opacity = '1';
+ } else {
+ merged.style.opacity = '0';
+ }
+ }
+ } else {
+ if (merged) merged.style.opacity = '0';
+ for (const [sid, el] of selRefs.current) {
+ if (!el) continue;
+ const rt = ready ? SceneModel.runtimeFor(sid) : undefined;
+ const rect = rt != null ? ViewportController.getEntityScreenRect(rt) : null;
+ if (rect) {
+ el.style.transform = `translate(${rect.x}px, ${rect.y}px)`;
+ el.style.width = `${rect.w}px`;
+ el.style.height = `${rect.h}px`;
+ el.style.opacity = '1';
+ } else {
+ el.style.opacity = '0';
+ }
}
}
@@ -2233,18 +2274,22 @@ export function Viewport() {
</div>
)}
- {/* One outline per selected entity (rAF-positioned); primary gets the accent. */}
- {selList.map((id) => (
- <div
- key={id}
- ref={(el) => {
- if (el) selRefs.current.set(id, el);
- else selRefs.current.delete(id);
- }}
- className={`viewport__selection${id === primaryId ? ' primary' : ''}`}
- aria-hidden="true"
- />
- ))}
+ {/* One outline per selected entity (rAF-positioned); primary gets the accent.
+ Above the merge threshold these collapse to the single merged box below. */}
+ {selList.length <= SELECTION_OUTLINE_MERGE_THRESHOLD &&
+ selList.map((id) => (
+ <div
+ key={id}
+ ref={(el) => {
+ if (el) selRefs.current.set(id, el);
+ else selRefs.current.delete(id);
+ }}
+ className={`viewport__selection${id === primaryId ? ' primary' : ''}`}
+ aria-hidden="true"
+ />
+ ))}
+ {/* The merged selection box (shown only above the threshold; rAF-positioned). */}
+ <div ref={mergedSelRef} className="viewport__selection" style={{ opacity: 0 }} aria-hidden="true" />
<div ref={marqueeRef} className="viewport__marquee" aria-hidden="true" />
<div ref={tileSelRef} className="viewport__tilesel" aria-hidden="true" />
<div ref={tilePreviewRef} className="viewport__tilepreview" aria-hidden="true" />
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 5cdf16ba4..d7c58a72f 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -571,15 +571,23 @@ class ProjectStoreImpl {
}
}
- /** Rebuild the uuid↔path registry + Assets resolvers from an index's entries. */
+ /** Rebuild the uuid↔path registry + Assets resolvers from an index's entries,
+ * dropping ALL caches — a full rescan (project open) can invalidate anything. */
private populateRegistry(entries: readonly AssetEntryLite[]): void {
+ this.prefabCache.clear();
+ this.hotLoadStarted.clear();
+ this.assetLoadFailures.clear();
+ this.rebuildLookups(entries);
+ }
+
+ /** Rebuild only the (cheap, in-memory) uuid↔path lookup maps + Assets resolvers
+ * from an index's entries. Leaves the disk-loaded prefab cache and live-load
+ * bookkeeping alone — the incremental path invalidates those selectively. */
+ private rebuildLookups(entries: readonly AssetEntryLite[]): void {
this.uuidToPath.clear();
this.pathToUuid.clear();
this.uuidToImporter.clear();
this.uuidToType.clear();
- this.prefabCache.clear();
- this.hotLoadStarted.clear();
- this.assetLoadFailures.clear();
for (const e of entries) {
const uuid = e.uuid.toLowerCase();
this.uuidToPath.set(uuid, e.path);
@@ -598,6 +606,47 @@ class ProjectStoreImpl {
}
}
+ /**
+ * Fold the fs watcher's precise changed paths into the registry incrementally
+ * (the watcher path — {@link fsWatch}), instead of a full O(files) rescan on
+ * every disk touch. The main process updates the cached index per-path and tells
+ * us whether it had to fall back to a full scan (directory move / bulk / no
+ * cache); on incremental success we rebuild only the lookup maps and invalidate
+ * only the changed prefabs. A full-scan fallback repopulates wholesale (a
+ * structural change can invalidate any cache), and is logged so it's never silent.
+ */
+ async applyDiskChanges(paths: readonly string[]): Promise<void> {
+ if (!this.state) return;
+ const result = await window.estella.project.scanAssetsIncremental([...paths]).catch(() => null);
+ if (!result) {
+ // IPC failed (e.g. project closing) — a full rescan is the safe recovery.
+ await this.buildAssetRegistry();
+ return;
+ }
+ if (result.fullRescan) {
+ console.info(`[assets] full rescan: ${result.reason ?? 'unspecified'}`);
+ this.populateRegistry(result.index.entries);
+ return;
+ }
+ this.applyIncrementalRegistry(result.index.entries, paths);
+ }
+
+ /** Apply an incrementally-updated index to the renderer registry: rebuild the
+ * lookup maps, but evict from the prefab cache ONLY the changed/removed prefab
+ * paths — a scene save must not drop every loaded `.esprefab`. */
+ private applyIncrementalRegistry(entries: readonly AssetEntryLite[], changedPaths: readonly string[]): void {
+ const changed = new Set(changedPaths.map((p) => p.replace(/\\/g, '/').replace(/\.meta$/, '')));
+ const kept = new Set(entries.map((e) => e.path));
+ // Resolve each cached prefab's path via the CURRENT (pre-rebuild) map, so this
+ // must run before rebuildLookups.
+ for (const ref of [...this.prefabCache.keys()]) {
+ const uuid = refUuid(ref);
+ const p = uuid !== null ? this.uuidToPath.get(uuid) : undefined;
+ if (!p || changed.has(p) || !kept.has(p)) this.prefabCache.delete(ref);
+ }
+ this.rebuildLookups(entries);
+ }
+
/** 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). */
diff --git a/desktop/src/project/fsWatch.ts b/desktop/src/project/fsWatch.ts
index 4a34005c6..0beefeec1 100644
--- a/desktop/src/project/fsWatch.ts
+++ b/desktop/src/project/fsWatch.ts
@@ -34,6 +34,12 @@ let debounce: ReturnType<typeof setTimeout> | null = null;
let schemaDebounce: ReturnType<typeof setTimeout> | null = null;
let scriptsDebounce: ReturnType<typeof setTimeout> | null = null;
let sceneDebounce: ReturnType<typeof setTimeout> | null = null;
+// Coalesce the changed paths across the debounce window (not just the last
+// burst): the incremental registry update needs EVERY changed path, or a change
+// two bursts back would be silently dropped. An empty burst (watcher overflow —
+// filename unknown) forces a full rescan for the window.
+let pendingPaths = new Set<string>();
+let sawOverflow = false;
// A project source module under src/ — a change here can alter a project
// component's field schema, so the inspector must re-extract (esbuild, ~100ms).
@@ -62,15 +68,21 @@ export function initFsWatch(): void {
if (inited || !window.estella?.fs?.onChange) return;
inited = true;
window.estella.fs.onChange((paths) => {
- // Coalesce back-to-back bursts; one scan + one bump per quiet window.
+ // Coalesce back-to-back bursts; one incremental update + one bump per quiet
+ // window. Accumulate the precise paths so none is lost across bursts.
+ if (paths.length === 0) sawOverflow = true;
+ else for (const p of paths) pendingPaths.add(p);
if (debounce) clearTimeout(debounce);
debounce = setTimeout(() => {
- void ProjectStore.refreshAssets().then(() => {
+ const batch = sawOverflow ? [] : [...pendingPaths];
+ pendingPaths = new Set();
+ sawOverflow = false;
+ void ProjectStore.applyDiskChanges(batch).then(() => {
// With the registry fresh, drop stale caches for the changed files and
// reload + re-project whatever the open scene still references — an
// externally rewritten texture/tilemap must not keep rendering old bytes
// (or fragments of whichever texture inherited its evicted handle).
- ProjectStore.hotSyncChangedPaths(paths);
+ ProjectStore.hotSyncChangedPaths(batch);
});
fsRefresh.bump();
}, 60);
diff --git a/desktop/tests/asset-db-incremental.test.ts b/desktop/tests/asset-db-incremental.test.ts
new file mode 100644
index 000000000..c5a74aaee
--- /dev/null
+++ b/desktop/tests/asset-db-incremental.test.ts
@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Incremental asset-index update (Task 1). The watcher delivers precise
+ * changed paths, so a disk touch folds into the cached index per-path
+ * instead of re-walking the whole tree. The correctness bar: the
+ * incremental result must be IDENTICAL to a full rescan of the same on-disk
+ * state — same `entries`, same dependency graph — so Find Usages, delete
+ * warnings and the cook can't disagree with what actually changed. Plus the
+ * explicit fallback cases (overflow / bulk / directory move → full rescan).
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { scanAssetDatabase, updateAssetIndex, INCREMENTAL_PATH_LIMIT } from '../electron/assetDb';
+
+let root: string;
+
+const TEX = '11111111-1111-4111-8111-111111111111';
+const TEX2 = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa';
+const FONT = '22222222-2222-4222-8222-222222222222';
+const MAT = '44444444-4444-4444-8444-444444444444';
+const SCENE = '33333333-3333-4333-8333-333333333333';
+
+function writeAsset(rel: string, type: string, uuid: string, body = ''): void {
+ const abs = path.join(root, rel);
+ mkdirSync(path.dirname(abs), { recursive: true });
+ writeFileSync(abs, body);
+ writeFileSync(`${abs}.meta`, JSON.stringify({ uuid, version: '2.0', type, importer: {} }));
+}
+
+function sceneBody(refs: { texture?: string; font?: string }): string {
+ return JSON.stringify({
+ version: '1.0',
+ name: 'main',
+ entities: [
+ {
+ id: 1, name: 'Hero', parent: null, children: [],
+ components: [
+ ...(refs.texture ? [{ type: 'Sprite', data: { texture: `@uuid:${refs.texture}` } }] : []),
+ ...(refs.font ? [{ type: 'BitmapText', data: { font: `@uuid:${refs.font}` } }] : []),
+ ],
+ },
+ ],
+ });
+}
+
+beforeEach(() => {
+ root = mkdtempSync(path.join(tmpdir(), 'estella-inc-'));
+ writeAsset('assets/textures/player.png', 'texture', TEX, 'PNGDATA');
+ writeAsset('assets/fonts/ui.fnt', 'font', FONT, 'FNTDATA');
+ writeAsset('assets/scenes/main.esscene', 'scene', SCENE, sceneBody({ texture: TEX, font: FONT }));
+});
+
+afterEach(() => {
+ if (root) rmSync(root, { recursive: true, force: true });
+});
+
+/** Assert an incremental update equals a full rescan of the same on-disk state. */
+async function expectIncrementalEqualsFull(prev: Awaited<ReturnType<typeof scanAssetDatabase>>['index'], changed: string[]): Promise<void> {
+ const inc = await updateAssetIndex(root, prev, changed, { write: false });
+ const full = await scanAssetDatabase(root, { write: false, adopt: false });
+ expect(inc.fullRescan).toBe(false);
+ expect(inc.index.entries).toEqual(full.index.entries);
+ expect(inc.index.deps).toEqual(full.index.deps);
+}
+
+describe('updateAssetIndex — incremental == full rescan', () => {
+ it('a content edit that DROPS a scene ref removes just that dependency edge', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ expect(prev.deps[SCENE]).toEqual([FONT, TEX].sort());
+
+ writeFileSync(path.join(root, 'assets/scenes/main.esscene'), sceneBody({ texture: TEX })); // font ref gone
+ await expectIncrementalEqualsFull(prev, ['assets/scenes/main.esscene']);
+
+ // And concretely: the edge to the font is gone, the texture edge stays.
+ const inc = await updateAssetIndex(root, prev, ['assets/scenes/main.esscene'], { write: false });
+ expect(inc.index.deps[SCENE]).toEqual([TEX]);
+ });
+
+ it('a .meta-only touch (paired to its content path) refreshes the entry', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ writeFileSync(
+ path.join(root, 'assets/textures/player.png.meta'),
+ JSON.stringify({ uuid: TEX, version: '2.0', type: 'texture', importer: { filter: 'nearest' } }),
+ );
+ await expectIncrementalEqualsFull(prev, ['assets/textures/player.png.meta']);
+ const inc = await updateAssetIndex(root, prev, ['assets/textures/player.png.meta'], { write: false });
+ expect(inc.index.entries.find((e) => e.uuid === TEX)?.importer).toEqual({ filter: 'nearest' });
+ });
+
+ it('ADDING an asset + a ref to it updates entries AND the dep graph', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ writeAsset('assets/textures/enemy.png', 'texture', TEX2, 'PNG2');
+ writeFileSync(path.join(root, 'assets/scenes/main.esscene'), sceneBody({ texture: TEX2, font: FONT }));
+ await expectIncrementalEqualsFull(prev, ['assets/textures/enemy.png', 'assets/scenes/main.esscene']);
+ });
+
+ it('a PATH-ref that only resolves once its target is added (reverse-dep) matches full', async () => {
+ // A material references a sibling texture by relative path; the texture is
+ // added AFTER the material — the edge must appear once both exist, exactly as a
+ // full rescan resolves it.
+ writeAsset('assets/materials/m.esmaterial', 'material', MAT, JSON.stringify({ texture: 'wall.png' }));
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ expect(prev.deps[MAT]).toBeUndefined(); // wall.png doesn't exist yet → no edge
+
+ writeAsset('assets/materials/wall.png', 'texture', TEX2, 'WALL');
+ await expectIncrementalEqualsFull(prev, ['assets/materials/wall.png']);
+ const inc = await updateAssetIndex(root, prev, ['assets/materials/wall.png'], { write: false });
+ expect(inc.index.deps[MAT]).toEqual([TEX2]); // the referrer's edge now resolves
+ });
+
+ it('DELETING an asset drops its entry (dep edges from @uuid: referrers persist, as in full)', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ rmSync(path.join(root, 'assets/fonts/ui.fnt'));
+ rmSync(path.join(root, 'assets/fonts/ui.fnt.meta'));
+ await expectIncrementalEqualsFull(prev, ['assets/fonts/ui.fnt', 'assets/fonts/ui.fnt.meta']);
+ const inc = await updateAssetIndex(root, prev, ['assets/fonts/ui.fnt.meta'], { write: false });
+ expect(inc.index.entries.some((e) => e.uuid === FONT)).toBe(false);
+ });
+
+ it('DELETING a .meta while the content file stays re-adopts it, like a full scan', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ rmSync(path.join(root, 'assets/textures/player.png.meta')); // orphan the png
+ const inc = await updateAssetIndex(root, prev, ['assets/textures/player.png.meta'], { write: false });
+ // Re-adopted → still an entry (a fresh uuid, so not identity-comparable to full).
+ expect(inc.adopted).toEqual(['assets/textures/player.png']);
+ expect(inc.index.entries.some((e) => e.path === 'assets/textures/player.png')).toBe(true);
+ });
+});
+
+describe('updateAssetIndex — fallbacks (never silent)', () => {
+ it('an empty change set (watcher overflow) falls back to a full rescan', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ const inc = await updateAssetIndex(root, prev, [], { write: false });
+ expect(inc.fullRescan).toBe(true);
+ expect(inc.reason).toContain('overflow');
+ });
+
+ it('a bulk change above the limit falls back to a full rescan', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ const many = Array.from({ length: INCREMENTAL_PATH_LIMIT + 1 }, (_, i) => `assets/x${i}.png`);
+ const inc = await updateAssetIndex(root, prev, many, { write: false });
+ expect(inc.fullRescan).toBe(true);
+ expect(inc.reason).toContain('bulk');
+ });
+
+ it('a directory change (create / rename / move) falls back to a full rescan', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ mkdirSync(path.join(root, 'assets/newdir'));
+ const inc = await updateAssetIndex(root, prev, ['assets/newdir'], { write: false });
+ expect(inc.fullRescan).toBe(true);
+ expect(inc.reason).toContain('directory');
+ });
+
+ it('a removed directory that held assets falls back (its child moves are invisible)', async () => {
+ const { index: prev } = await scanAssetDatabase(root, { write: false });
+ // Simulate the dir vanishing (the watcher may report only the dir path).
+ rmSync(path.join(root, 'assets/fonts'), { recursive: true });
+ const inc = await updateAssetIndex(root, prev, ['assets/fonts'], { write: false });
+ expect(inc.fullRescan).toBe(true);
+ expect(inc.reason).toContain('directory');
+ });
+});
diff --git a/desktop/tests/entity-ref-index.test.ts b/desktop/tests/entity-ref-index.test.ts
new file mode 100644
index 000000000..c977f855f
--- /dev/null
+++ b/desktop/tests/entity-ref-index.test.ts
@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file EntityRefIndex — the reverse index the Reconciler consults on spawn to
+ * re-project a just-spawned entity's referrers in O(referrers) rather than
+ * scanning the whole model. The correctness bar: after ANY sequence of
+ * incremental mutations (spawn / despawn / entity-ref field write /
+ * component remove), the index must equal one rebuilt from scratch — the
+ * same equivalence the reconciler relies on to drop the full-model scan.
+ */
+import { describe, it, expect } from 'vitest';
+import { EntityRefIndex } from '@/engine/EntityRefIndex';
+
+// A minimal model + the entity-ref field map the reconciler reads from the
+// component registry (Joint.connectedEntity, a made-up two-ref component).
+type Comp = { type: string; data: Record<string, unknown> };
+type Ent = { id: number; components: Comp[] };
+const ENTITY_FIELDS: Record<string, string[]> = {
+ Joint: ['connectedEntity'],
+ Link: ['a', 'b'],
+};
+
+function refsOf(comp: Comp): number[] {
+ const fields = ENTITY_FIELDS[comp.type] ?? [];
+ const out: number[] = [];
+ for (const f of fields) {
+ const v = comp.data[f];
+ if (typeof v === 'number') out.push(v);
+ }
+ return out;
+}
+
+/** A full rebuild from the final model — the reference the incremental index must match. */
+function fullBuild(model: Map<number, Ent>): EntityRefIndex {
+ const idx = new EntityRefIndex();
+ for (const e of model.values()) for (const c of e.components) idx.setReferrer(e.id, c.type, refsOf(c));
+ return idx;
+}
+
+// A tiny driver mirroring the reconciler's index hooks on model events.
+class Harness {
+ readonly model = new Map<number, Ent>();
+ readonly idx = new EntityRefIndex();
+
+ spawn(e: Ent): void {
+ this.model.set(e.id, e);
+ for (const c of e.components) this.idx.setReferrer(e.id, c.type, refsOf(c));
+ }
+ despawn(id: number): void {
+ this.model.delete(id);
+ this.idx.removeEntity(id);
+ }
+ setField(id: number, type: string, field: string, value: number): void {
+ const comp = this.model.get(id)?.components.find((c) => c.type === type);
+ if (!comp) return;
+ comp.data[field] = value;
+ this.idx.setReferrer(id, type, refsOf(comp));
+ }
+ removeComponent(id: number, type: string): void {
+ const e = this.model.get(id);
+ if (e) e.components = e.components.filter((c) => c.type !== type);
+ this.idx.setReferrer(id, type, []);
+ }
+}
+
+const ent = (id: number, comps: Comp[]): Ent => ({ id, components: comps });
+const joint = (connectedEntity: number): Comp => ({ type: 'Joint', data: { connectedEntity } });
+
+describe('EntityRefIndex — basic reverse lookups', () => {
+ it('reports the components whose entity-ref field targets a source id', () => {
+ const idx = new EntityRefIndex();
+ idx.setReferrer(5, 'Joint', [2]);
+ idx.setReferrer(6, 'Link', [2, 3]);
+ expect(idx.referrersOf(2).sort((a, b) => a.entity - b.entity)).toEqual([
+ { entity: 5, comp: 'Joint' },
+ { entity: 6, comp: 'Link' },
+ ]);
+ expect(idx.referrersOf(3)).toEqual([{ entity: 6, comp: 'Link' }]);
+ expect(idx.referrersOf(99)).toEqual([]);
+ });
+
+ it('treats 0 / negatives (INVALID_ENTITY) as no reference', () => {
+ const idx = new EntityRefIndex();
+ idx.setReferrer(5, 'Joint', [0]);
+ idx.setReferrer(6, 'Joint', [-1]);
+ expect(idx.referrersOf(0)).toEqual([]);
+ expect(idx.snapshot().incoming).toEqual({});
+ });
+
+ it('a re-pointed field moves the edge; the old target loses its referrer', () => {
+ const idx = new EntityRefIndex();
+ idx.setReferrer(5, 'Joint', [2]);
+ idx.setReferrer(5, 'Joint', [3]); // re-point 5's joint from 2 → 3
+ expect(idx.referrersOf(2)).toEqual([]);
+ expect(idx.referrersOf(3)).toEqual([{ entity: 5, comp: 'Joint' }]);
+ });
+
+ it('removeEntity drops the entity as a referrer everywhere', () => {
+ const idx = new EntityRefIndex();
+ idx.setReferrer(5, 'Link', [2, 3]);
+ idx.removeEntity(5);
+ expect(idx.referrersOf(2)).toEqual([]);
+ expect(idx.referrersOf(3)).toEqual([]);
+ expect(idx.snapshot()).toEqual({ out: {}, incoming: {} });
+ });
+});
+
+describe('EntityRefIndex — incremental == full rebuild', () => {
+ it('matches a from-scratch rebuild after a spawn / repoint / despawn sequence', () => {
+ const h = new Harness();
+ // Paste a subtree where a parent joint points at a child spawned later.
+ h.spawn(ent(1, [joint(3)])); // 1's joint targets 3 (not yet spawned)
+ h.spawn(ent(2, [joint(1)]));
+ h.spawn(ent(3, [{ type: 'Link', data: { a: 1, b: 2 } }]));
+ // Edits + structural churn.
+ h.setField(2, 'Joint', 'connectedEntity', 3); // 2 re-points 1 → 3
+ h.setField(1, 'Joint', 'connectedEntity', 0); // 1 clears its ref
+ h.spawn(ent(4, [joint(3), { type: 'Link', data: { a: 3, b: 3 } }]));
+ h.removeComponent(4, 'Link');
+ h.despawn(3); // 3 leaves; its outgoing Link edges vanish, incoming edges stay
+ h.spawn(ent(3, [{ type: 'Link', data: { a: 4, b: 1 } }])); // undo-of-delete: 3 returns, re-pointed
+
+ expect(h.idx.snapshot()).toEqual(fullBuild(h.model).snapshot());
+ });
+
+ it('matches a from-scratch rebuild after a heavy batch paste + partial delete', () => {
+ const h = new Harness();
+ for (let i = 1; i <= 300; i++) h.spawn(ent(i, [joint(i === 1 ? 0 : i - 1)])); // chain 2→1, 3→2, …
+ for (let i = 2; i <= 300; i += 2) h.despawn(i); // delete every other node
+ for (let i = 301; i <= 320; i++) h.spawn(ent(i, [{ type: 'Link', data: { a: 1, b: 301 } }]));
+
+ expect(h.idx.snapshot()).toEqual(fullBuild(h.model).snapshot());
+ });
+});