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
refactor(project): loaded prefabs are a cache, not a field
yhh1aeafd4745fb
diff --git a/desktop/src/project/PrefabCache.ts b/desktop/src/project/PrefabCache.tsnew file mode 100644index 000000000..f0a0c9be5--- /dev/null+++ b/desktop/src/project/PrefabCache.ts@@ -0,0 +1,139 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file PrefabCache.ts — loaded `.esprefab` assets, and the synchronous resolver+ * the expansion needs.+ *+ * Expanding a prefab instance is SYNCHRONOUS — `flattenPrefab` walks a variant's+ * base and every `nestedPrefab` in one pass and cannot await — while reading a+ * `.esprefab` off disk is not. The gap between those two facts is this cache: an+ * async load warms every dependency a prefab can reach, and the expansion then+ * resolves them out of memory.+ *+ * Warming is why a plain memo will not do. {@link load} caches the prefab BEFORE+ * warming its dependencies, so a variant or nested reference that cycles back+ * terminates on the second visit instead of fetching forever.+ *+ * The cache is separate from {@link AssetRegistry} because it is a different kind+ * of thing: the registry says where an asset IS, from a scan; this holds asset+ * CONTENT, read on demand and invalidated per file when one changes. Their+ * lifetimes differ too — a rebuild of the lookup tables must not drop every+ * loaded prefab, which is exactly the distinction an incremental rescan turns on.+ */+import { migratePrefabData, validateOverrides } from 'esengine';+import type { PrefabData, SceneData, PrefabOverride, StaleOverride } from 'esengine';+import { AssetRegistry, UUID_PREFIX } from './AssetRegistry';+import { usePrefabConflicts } from '@/store/prefabConflicts';+import { Toasts } from '@/store/Toasts';+import { t } from '@/i18n';++class PrefabCacheImpl {+ /** ref (`@uuid:`) → the loaded `.esprefab`. */+ private readonly byRef = new Map<string, PrefabData>();++ /**+ * Load a `.esprefab` by ref, cached, warming its base and every nested+ * reference so {@link resolveSync} can answer for all of them.+ */+ async load(ref: string): Promise<PrefabData | null> {+ if (!ref.startsWith(UUID_PREFIX)) return null;+ const cached = this.byRef.get(ref);+ if (cached) return cached;+ const path = AssetRegistry.pathForUuid(ref.slice(UUID_PREFIX.length).toLowerCase());+ if (!path) return null;+ try {+ const prefab = migratePrefabData(JSON.parse(await window.estella.fs.read(path))).data as PrefabData;+ // Cache BEFORE warming deps so a variant/nested ref CYCLE terminates (the+ // second visit hits the cache and returns instead of re-fetching forever).+ this.byRef.set(ref, prefab);+ await this.warm(prefab);+ return prefab;+ } catch (err) {+ console.warn('[project] prefab load failed', path, err);+ return null;+ }+ }++ /** Recursively load a prefab's base (variant `basePrefab`) + every entity's+ * `nestedPrefab` ref into the cache. flattenPrefab resolves those SYNChronously+ * during expansion, so they must already be resident. */+ private async warm(prefab: PrefabData): Promise<void> {+ if (prefab.basePrefab) await this.load(prefab.basePrefab);+ for (const e of prefab.entities) {+ const nested = e.nestedPrefab?.prefabPath;+ if (nested) await this.load(nested);+ }+ }++ /** Synchronous prefab resolver for flattenPrefab's variant / nested expansion —+ * a cache read (the async {@link load} pre-warms every dependency). Passed to+ * the scene-load + instantiate paths so a variant / nested instance resolves+ * its base the same way in both.+ *+ * An arrow property, not a method: it is handed around as a bare callback. */+ resolveSync = (ref: string): PrefabData | null => this.byRef.get(ref) ?? null;++ /** The entity carrying `prefabId` inside a cached prefab, if it is loaded. */+ entityOf(ref: string, prefabId: string): PrefabData['entities'][number] | undefined {+ return this.byRef.get(ref)?.entities.find((e) => e.prefabEntityId === prefabId);+ }++ /** Record a prefab this editor just wrote, so the next expansion sees the new+ * content without a disk round-trip. */+ put(ref: string, prefab: PrefabData): void {+ this.byRef.set(ref, prefab);+ }++ /** Drop everything — a full rescan, or a pass that rewrote every prefab on disk. */+ clear(): void {+ this.byRef.clear();+ }++ /**+ * Evict only the prefabs whose FILE changed or went away, given the paths a+ * rescan reported and the set it still knows about.+ *+ * Selective on purpose: an incremental rescan fires on any disk touch, and+ * dropping the whole cache there means a scene save re-reads every `.esprefab`+ * the open scene instantiates.+ */+ evictChanged(changed: ReadonlySet<string>, kept: ReadonlySet<string>): void {+ for (const ref of [...this.byRef.keys()]) {+ const p = AssetRegistry.pathForUuid(ref.slice(UUID_PREFIX.length).toLowerCase());+ if (!p || changed.has(p) || !kept.has(p)) this.byRef.delete(ref);+ }+ }++ /**+ * Scan a raw scene's prefab-instance entries for STALE overrides — ones that+ * target an entity / component the prefab no longer has. The loader silently+ * drops them (the customization vanishes with no trace), so record them per+ * instance root ({@link usePrefabConflicts}) for the Inspector to surface. Only+ * FLAT bases are checked: validateOverrides is structural, so a variant / nested+ * base (whose inherited entities live in ITS base) would false-positive.+ */+ reportStaleOverrides(raw: SceneData): void {+ const byInstance = new Map<number, StaleOverride[]>();+ for (const e of raw.entities as unknown[]) {+ const entry = e as { id?: number; prefab?: string; overrides?: PrefabOverride[] };+ if (typeof entry.prefab !== 'string' || !entry.overrides?.length || typeof entry.id !== 'number') continue;+ const base = this.byRef.get(entry.prefab);+ if (!base || base.basePrefab || base.entities.some((be) => be.nestedPrefab)) continue;+ const { stale } = validateOverrides(base, { instanceOverrides: entry.overrides });+ if (stale.length > 0) byInstance.set(entry.id, stale);+ }+ usePrefabConflicts.getState().setAll(byInstance);+ const total = usePrefabConflicts.getState().total;+ if (total > 0) {+ console.warn(+ `[prefab] ${total} stale override(s) on ${byInstance.size} instance(s) reference prefab ` ++ `structure that no longer exists — dropped on load. Select an affected instance to review, ` ++ `or save to persist the cleanup.`,+ );+ Toasts.push(t('proj.staleOverrides', { overrides: total, instances: byInstance.size }), 'warn', 4500);+ }+ }+}++/** The open project's loaded prefab assets. */+export const PrefabCache = new PrefabCacheImpl();diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex d0f0295ff..3d4149808 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -1,15 +1,16 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { createStore } from 'zustand/vanilla';-import { getComponent, Assets, migratePrefabData, extractPrefab, flattenPrefab, collectExternalEntityRefs, collapseInstance, applyDeltaToSource, buildVariant, validateOverrides, textureImportSettingsFrom, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides, resolveAssetGroup, folderGroupMode, withFolderGroup, folderAlwaysInclude, withFolderAlwaysInclude, withActiveRemoteRoot, Audio, applyAudioProjectConfig } from 'esengine';+import { getComponent, Assets, migratePrefabData, extractPrefab, flattenPrefab, collectExternalEntityRefs, collapseInstance, applyDeltaToSource, buildVariant, textureImportSettingsFrom, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides, resolveAssetGroup, folderGroupMode, withFolderGroup, folderAlwaysInclude, withFolderAlwaysInclude, withActiveRemoteRoot, Audio, applyAudioProjectConfig } from 'esengine';import { importerDefaults, applyImporterEdit } from './assetImporter';import { AssetRegistry, UUID_PREFIX, refUuid, type AssetEntryLite } from './AssetRegistry';+import { PrefabCache } from './PrefabCache';import {runtimeConfigOf, packagedRuntimeFields, normalizeCollisionLayers, normalizeCollisionLayerMasks,type RuntimeProjectConfig,} from './runtimeConfig';import type { ParsedTextureImportSettings } from 'esengine';-import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig, AssetsData, ThemeOverrides, StaleOverride, PrefabOverride, AddressableManifest, AssetGroupsConfig, AssetGroupMode } from 'esengine';+import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig, AssetsData, ThemeOverrides, AddressableManifest, AssetGroupsConfig, AssetGroupMode } from 'esengine';import { EngineHost } from '@/engine/EngineHost';import { applyWidgetTheme } from '@/engine/widgetTheme';import { bootProfiler } from '@/engine/bootProfiler';@@ -145,11 +146,6 @@ function stripRetiredComponents(data: SceneData): string[] {class ProjectStoreImpl {private readonly store = createStore<{ project: ProjectState | null }>(() => ({ project: null }));- // The uuid↔path lookup tables and the load bookkeeping keyed by them live in- // {@link AssetRegistry}. This still drives the SCAN that fills them — that needs- // the open project, its root and its watcher — but it no longer owns the answers.- /** ref → loaded `.esprefab` (PrefabData), for scene load-expand / save-collapse. */- private readonly prefabCache = new Map<string, PrefabData>();/** Active Prefab Mode session, or null. Holds the id-preservation map* (source id → prefabEntityId) so save-back keeps each entity's identity, plus* the scene to return to on exit. The reactive `prefabEdit` in ProjectState is@@ -192,7 +188,7 @@ class ProjectStoreImpl {// directly from the asset entities; a variant/nested base degrades to the// component default (the entry simply isn't found here).setPrefabBaseResolver((ref, prefabId) => {- const pe = this.prefabCache.get(ref)?.entities.find((e) => e.prefabEntityId === prefabId);+ const pe = PrefabCache.entityOf(ref, prefabId);return pe ? pe.components : null;});// Collider layer-mask fields resolve their bit labels from this project setting.@@ -231,7 +227,7 @@ class ProjectStoreImpl {setAssetRefProblemResolver((ref) => AssetRegistry.assetRefProblem(ref));// Instantiating a variant / nested prefab resolves its base through the same// warm-cache reader the scene-load path uses (one resolution truth).- SceneCommands.setPrefabResolver(this.prefabResolverSync);+ SceneCommands.setPrefabResolver(PrefabCache.resolveSync);}/** Read accessor so existing `this.state` reads stay unchanged after the move. */@@ -512,7 +508,7 @@ class ProjectStoreImpl {let nextId = raw.entities.reduce((m, e) => Math.max(m, (e as { id?: number }).id ?? 0), 0) + 1;const { scene: expandedRaw, tags } = await bootProfiler.phase('expandPrefabs', () => expandScenePrefabs(raw,- (ref) => this.loadPrefabAsset(ref),+ (ref) => PrefabCache.load(ref),() => nextId++,));@@ -567,7 +563,7 @@ class ProjectStoreImpl {this.applyEditorRuntimeConfig();// Surface any instance overrides the loader just dropped (they point at prefab// structure that no longer exists) — otherwise the customization loss is silent.- this.detectPrefabConflicts(raw);+ PrefabCache.reportStaleOverrides(raw);// Loading a scene always leaves Prefab Mode (if it was active).this.prefabSession = null;this.store.setState({ project: { ...st, currentScene: rel, prefabEdit: null } });@@ -731,7 +727,7 @@ class ProjectStoreImpl {* The prefab cache is ours; the lookup tables and load bookkeeping are the* registry's, and it decides what a rebuild keeps. */private populateRegistry(entries: readonly AssetEntryLite[]): void {- this.prefabCache.clear();+ PrefabCache.clear();AssetRegistry.clearLoadState();AssetRegistry.rebuild(entries);}@@ -769,11 +765,7 @@ class ProjectStoreImpl {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 ? AssetRegistry.pathForUuid(uuid) : undefined;- if (!p || changed.has(p) || !kept.has(p)) this.prefabCache.delete(ref);- }+ PrefabCache.evictChanged(changed, kept);AssetRegistry.rebuild(entries);}@@ -983,42 +975,13 @@ class ProjectStoreImpl {* / save-collapse path resolves prefab instances through this. Warms the* prefab's base (variant) + nested refs into the cache too, so the SYNChronous* flatten resolver ({@link prefabResolverSync}) can resolve them. */- private async loadPrefabAsset(ref: string): Promise<PrefabData | null> {- if (!ref.startsWith(UUID_PREFIX)) return null;- const cached = this.prefabCache.get(ref);- if (cached) return cached;- const path = AssetRegistry.pathForUuid(ref.slice(UUID_PREFIX.length).toLowerCase());- if (!path) return null;- try {- const prefab = migratePrefabData(JSON.parse(await window.estella.fs.read(path))).data as PrefabData;- // Cache BEFORE warming deps so a variant/nested ref CYCLE terminates (the- // second visit hits the cache and returns instead of re-fetching forever).- this.prefabCache.set(ref, prefab);- await this.warmPrefabDeps(prefab);- return prefab;- } catch (err) {- console.warn('[project] prefab load failed', path, err);- return null;- }- }-/** Recursively load a prefab's base (variant `basePrefab`) + every entity's* `nestedPrefab` ref into the cache. flattenPrefab resolves those SYNChronously* during expansion, so they must already be resident. */- private async warmPrefabDeps(prefab: PrefabData): Promise<void> {- if (prefab.basePrefab) await this.loadPrefabAsset(prefab.basePrefab);- for (const e of prefab.entities) {- const nested = e.nestedPrefab?.prefabPath;- if (nested) await this.loadPrefabAsset(nested);- }- }-/** Synchronous prefab resolver for flattenPrefab's variant / nested expansion —* a cache read (the async {@link loadPrefabAsset} pre-warms every dependency).* Installed on the scene-load + instantiate paths so a variant / nested* instance resolves its base the same way in both. */- private prefabResolverSync = (ref: string): PrefabData | null => this.prefabCache.get(ref) ?? null;-/*** Scan a raw scene's prefab-instance entries for STALE overrides — ones that* target an entity / component the prefab no longer has. The loader silently@@ -1027,28 +990,6 @@ class ProjectStoreImpl {* FLAT bases are checked: validateOverrides is structural, so a variant / nested* base (whose inherited entities live in ITS base) would false-positive.*/- private detectPrefabConflicts(raw: SceneData): void {- const byInstance = new Map<number, StaleOverride[]>();- for (const e of raw.entities as unknown[]) {- const entry = e as { id?: number; prefab?: string; overrides?: PrefabOverride[] };- if (typeof entry.prefab !== 'string' || !entry.overrides?.length || typeof entry.id !== 'number') continue;- const base = this.prefabCache.get(entry.prefab);- if (!base || base.basePrefab || base.entities.some((be) => be.nestedPrefab)) continue;- const { stale } = validateOverrides(base, { instanceOverrides: entry.overrides });- if (stale.length > 0) byInstance.set(entry.id, stale);- }- usePrefabConflicts.getState().setAll(byInstance);- const total = usePrefabConflicts.getState().total;- if (total > 0) {- console.warn(- `[prefab] ${total} stale override(s) on ${byInstance.size} instance(s) reference prefab ` +- `structure that no longer exists — dropped on load. Select an affected instance to review, ` +- `or save to persist the cleanup.`,- );- Toasts.push(t('proj.staleOverrides', { overrides: total, instances: byInstance.size }), 'warn', 4500);- }- }-/*** Instantiate a `.esprefab` (by project-relative path) into the open scene@@ -1067,7 +1008,7 @@ class ProjectStoreImpl {const uuid = AssetRegistry.uuidFor(path);if (!uuid) return null;const ref = UUID_PREFIX + uuid;- const prefab = await this.loadPrefabAsset(ref);+ const prefab = await PrefabCache.load(ref);if (!prefab) {Toasts.push(t('proj.prefabLoadFailed', { name: path.split('/').pop() ?? path }), 'error');return null;@@ -1097,7 +1038,7 @@ class ProjectStoreImpl {icon: Boxes,keywords: [name],build: async () => {- const p = await this.loadPrefabAsset(ref);+ const p = await PrefabCache.load(ref);if (!p) {Toasts.push(t('proj.prefabLoadFailed', { name }), 'error');throw new Error('prefab load failed');@@ -1178,7 +1119,7 @@ class ProjectStoreImpl {if (!ref) return null;const info = AssetRegistry.assetInfo(ref);if (!info) return null;- const oldPrefab = await this.loadPrefabAsset(ref);+ const oldPrefab = await PrefabCache.load(ref);if (!oldPrefab) {Toasts.push(t('proj.prefabLoadFailed', { name: info.path.split('/').pop() ?? info.path }), 'error');return null;@@ -1204,7 +1145,7 @@ class ProjectStoreImpl {if (processed.length === 0) return null;// The full delta against the asset: property overrides + structural edits.- const delta = collapseInstance(oldPrefab, ref, processed, this.prefabResolverSync);+ const delta = collapseInstance(oldPrefab, ref, processed, PrefabCache.resolveSync);const overrides = delta.overrides.filter((o) => o.type !== 'metadata_set' && o.type !== 'metadata_removed');const { added, removed } = delta;@@ -1235,7 +1176,7 @@ class ProjectStoreImpl {Toasts.push(t('proj.applyWriteFailed', { name }), 'error');return null;}- this.prefabCache.set(ref, newPrefab);+ PrefabCache.put(ref, newPrefab);// Re-sync this instance to the updated base so its (now-applied) edits// clear — reuses the proven delete + re-instantiate path.@@ -1275,7 +1216,7 @@ class ProjectStoreImpl {if (!ref) return null;const info = AssetRegistry.assetInfo(ref);if (!info) return null;- const base = await this.loadPrefabAsset(ref);+ const base = await PrefabCache.load(ref);if (!base) {Toasts.push(t('proj.prefabLoadFailed', { name: info.path.split('/').pop() ?? info.path }), 'error');return null;@@ -1300,7 +1241,7 @@ class ProjectStoreImpl {}if (processed.length === 0) return null;- const delta = collapseInstance(base, ref, processed, this.prefabResolverSync);+ const delta = collapseInstance(base, ref, processed, PrefabCache.resolveSync);const overrides = delta.overrides.filter((o) => o.type !== 'metadata_set' && o.type !== 'metadata_removed');if (delta.removed.length > 0) {Toasts.push(t('proj.variantNoRemove', { count: delta.removed.length }), 'warn');@@ -1455,7 +1396,7 @@ class ProjectStoreImpl {failed++;}}- this.prefabCache.clear(); // rewritten assets must reload fresh+ PrefabCache.clear(); // rewritten assets must reload freshif (failed > 0) Toasts.push(t('proj.resaveFailed', { upgraded, failed }), 'error');else Toasts.push(t('proj.resaveDone', { count: upgraded }), 'success');}@@ -2115,7 +2056,7 @@ class ProjectStoreImpl {const entities = await collapseScenePrefabs(model.entities,(id) => SceneModel.prefabTag(id),- (ref) => this.loadPrefabAsset(ref),+ (ref) => PrefabCache.load(ref),);return { ...model, name: this.state?.name ?? model.name, entities };}@@ -2183,7 +2124,7 @@ class ProjectStoreImpl {if (!opts?.discardChanges && !(await confirmDiscard(t('discard.openPrefab', { name: leaf })))) return;const uuid = AssetRegistry.uuidFor(path);const ref = uuid ? UUID_PREFIX + uuid : null;- const prefab = ref ? await this.loadPrefabAsset(ref) : null;+ const prefab = ref ? await PrefabCache.load(ref) : null;if (!ref || !prefab) {Toasts.push(t('proj.prefabLoadFailed', { name: leaf }), 'error');return;@@ -2197,7 +2138,7 @@ class ProjectStoreImpl {// simple baseline). A variant-of-variant / variant-of-nested base is refused.let base: PrefabData | null = null;if (prefab.basePrefab) {- base = await this.loadPrefabAsset(prefab.basePrefab);+ base = await PrefabCache.load(prefab.basePrefab);if (!base || base.basePrefab || base.entities.some((e) => e.nestedPrefab)) {Toasts.push(t('proj.prefabModeNested'), 'warn');return;@@ -2218,7 +2159,7 @@ class ProjectStoreImpl {// above warmed it), yielding base entities + the variant's own overrides/adds.let nid = 0;const allocateId = (): number => nid++;- const { entities, rootId } = flattenPrefab(prefab, [], { allocateId, loadPrefab: this.prefabResolverSync });+ const { entities, rootId } = flattenPrefab(prefab, [], { allocateId, loadPrefab: PrefabCache.resolveSync });const idBySource = new Map(entities.map((e) => [e.id, e.prefabEntityId]));let docEntities = entities.map(toDocumentEntity);// A UI prefab's boxes are fractions of a parent it no longer has, so open it inside@@ -2267,7 +2208,7 @@ class ProjectStoreImpl {if (!source?.build) return null;try {const canvas = await source.build({ parent: null });- const flat = flattenPrefab(canvas, [], { allocateId, loadPrefab: this.prefabResolverSync });+ const flat = flattenPrefab(canvas, [], { allocateId, loadPrefab: PrefabCache.resolveSync });return { entities: flat.entities.map(toDocumentEntity), rootId: flat.rootId };} catch {return null;@@ -2334,7 +2275,7 @@ class ProjectStoreImpl {components: e.components as ProcessedEntity['components'],visible: (e as { visible?: boolean }).visible ?? true,}));- const delta = collapseInstance(pe.base, pe.baseRef, processed, this.prefabResolverSync);+ const delta = collapseInstance(pe.base, pe.baseRef, processed, PrefabCache.resolveSync);const overrides = delta.overrides.filter((o) => o.type !== 'metadata_set' && o.type !== 'metadata_removed');const prefab = buildVariant(pe.base, pe.baseRef, pe.name, { overrides, added: delta.added });return { prefab, idBySource, removedCount: delta.removed.length };@@ -2361,7 +2302,7 @@ class ProjectStoreImpl {Toasts.push(t('proj.applyWriteFailed', { name: pe.path.split('/').pop() ?? pe.path }), 'error');return;}- this.prefabCache.set(pe.ref, prefab);+ PrefabCache.put(pe.ref, prefab);this.prefabSession = { ...pe, idBySource };EditorHistory.markSaved();Toasts.push(t('proj.savedPrefab', { name: pe.name }), 'success');@@ -2547,3 +2488,4 @@ class ProjectStoreImpl {export const ProjectStore = new ProjectStoreImpl();+