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): incremental asset index, entity-ref reverse index, merged multi-select outline
esengine9352e8895406
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.tsindex 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.tsindex 062f0e0be..0672f78b3 100644--- a/desktop/electron/main.ts+++ b/desktop/electron/main.ts@@ -26,7 +26,7 @@ import { syncAutosave, listAutosave, restoreAutosave, clearAutosave, type Autosaimport { 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 emitdiff --git a/desktop/electron/preload.ts b/desktop/electron/preload.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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: ReactPointerEveconst 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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());+ });+});