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
feat(editor): edit prefab VARIANTS in Prefab Mode (base-tracked save) (P2 UX)
yhh177eec792871
diff --git a/desktop/src/components/PrefabModeBanner.tsx b/desktop/src/components/PrefabModeBanner.tsxindex d436ed0b4..e6c277d08 100644--- a/desktop/src/components/PrefabModeBanner.tsx+++ b/desktop/src/components/PrefabModeBanner.tsx@@ -17,10 +17,11 @@ export function PrefabModeBanner() {const pe = project?.prefabEdit;if (!pe) return null;const back = pe.returnScene ? t('proj.prefabModeBackTo', { name: pe.returnScene }) : t('proj.prefabModeBack');+ const label = pe.isVariant ? t('proj.prefabModeVariantBanner') : t('proj.prefabModeBanner');return (<div className="prefab-mode-bar"><span className="pmb-icon"><Package size={14} strokeWidth={1.9} /></span>- <span className="pmb-label">{t('proj.prefabModeBanner')}</span>+ <span className="pmb-label">{label}</span><span className="pmb-name">{pe.name}</span><span className="pmb-actions"><Button variant="primary" onClick={() => void ProjectStore.save()}>diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.tsindex e5fbb7290..6c96ccdd8 100644--- a/desktop/src/i18n/messages/project.ts+++ b/desktop/src/i18n/messages/project.ts@@ -121,6 +121,7 @@ export const projectMessages = defineMessages({'proj.savedPrefab': { en: 'Saved prefab {name}', zh: '已保存预制体 {name}' },'proj.prefabModeNested': { en: 'Nested / variant prefabs can\'t be edited in place yet', zh: '暂不支持原位编辑嵌套 / 变体预制体' },'proj.prefabModeBanner': { en: 'Editing Prefab', zh: '正在编辑预制体' },+ 'proj.prefabModeVariantBanner': { en: 'Editing Variant', zh: '正在编辑变体' },'proj.prefabModeBack': { en: 'Back to Scene', zh: '返回场景' },'proj.prefabModeBackTo': { en: 'Back to {name}', zh: '返回 {name}' },'proj.prefabModeSave': { en: 'Save Prefab', zh: '保存预制体' },diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex f7b278b8e..aace906b4 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -144,8 +144,9 @@ interface ProjectState {currentScene: string | null;/** When editing a PREFAB asset in place (Prefab Mode) rather than a scene:* the prefab's display name + path, plus the leaf name of the scene "Back to- * Scene" returns to (for the banner breadcrumb). `currentScene` is null. */- prefabEdit?: { name: string; path: string; returnScene: string | null } | null;+ * Scene" returns to (for the banner breadcrumb) and whether it's a VARIANT+ * (a different badge / banner). `currentScene` is null. */+ prefabEdit?: { name: string; path: string; returnScene: string | null; isVariant: boolean } | null;}/**@@ -220,6 +221,11 @@ class ProjectStoreImpl {/** Editor camera at enter, restored on exit so "Back to Scene" returns the* user to the exact view they left instead of reframing to the scene camera. */returnView: { x: number; y: number; orthoSize: number } | null;+ /** When editing a VARIANT: its base asset + ref. Save collapses the edited+ * tree against this base into a variant delta (preserving basePrefab), rather+ * than extracting a flat prefab. Null for an ordinary (flat) prefab. */+ base: PrefabData | null;+ baseRef: string | null;} | null = null;/** Cold refs already handed to a live load this registry generation — the touch* listener fires on every projection of a still-cold ref, so without this a@@ -1916,8 +1922,11 @@ class ProjectStoreImpl {* same outliner / inspector / viewport used for scenes. The asset is flattened* into ordinary entities (each remembered by its prefabEntityId so save-back* preserves identity), the current scene is swapped out, and a banner offers- * "Back to Scene". Only FLAT prefabs for now — a nested/variant prefab would- * un-nest on save, so those are refused. The caller guards unsaved changes.+ * "Back to Scene". A FLAT prefab extracts back to a flat asset on save; a+ * VARIANT of a flat base is editable too (save collapses the edits against the+ * base into a variant delta, preserving basePrefab). Nested prefabs — and+ * variants of a nested / variant base — are still refused (re-nesting on save+ * is unsolved). The caller guards unsaved changes.*/async openPrefab(path: string): Promise<void> {const st = this.state;@@ -1931,10 +1940,21 @@ class ProjectStoreImpl {Toasts.push(t('proj.prefabLoadFailed', { name: leaf }), 'error');return;}- if (prefab.basePrefab || prefab.entities.some((e) => e.nestedPrefab)) {+ // Nested prefabs can't be edited in place (re-nesting on save is unsolved).+ if (prefab.entities.some((e) => e.nestedPrefab)) {Toasts.push(t('proj.prefabModeNested'), 'warn');return;}+ // A VARIANT is editable when its base is FLAT (so save can collapse against a+ // 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);+ if (!base || base.basePrefab || base.entities.some((e) => e.nestedPrefab)) {+ Toasts.push(t('proj.prefabModeNested'), 'warn');+ return;+ }+ }// The scene to return to + the view to restore on exit. Opening a prefab// from WITHIN Prefab Mode keeps the ORIGINAL home scene/view (an existing@@ -1943,8 +1963,10 @@ class ProjectStoreImpl {const returnView = this.prefabSession?.returnView ?? EngineHost.editorViewState();// Flatten the asset into ordinary entities; remember each entity's stable id.+ // A variant resolves its base through the warm-cache resolver (loadPrefabAsset+ // above warmed it), yielding base entities + the variant's own overrides/adds.let nid = 0;- const { entities, rootId } = flattenPrefab(prefab, [], { allocateId: () => nid++, loadPrefab: () => null });+ const { entities, rootId } = flattenPrefab(prefab, [], { allocateId: () => nid++, loadPrefab: this.prefabResolverSync });const idBySource = new Map(entities.map((e) => [e.id, e.prefabEntityId]));const sceneData = {version: '1.0',@@ -1959,12 +1981,18 @@ class ProjectStoreImpl {// A prefab carries no camera, so syncEditorViewToScene left the scene's view —// the prefab could sit off-screen if the user had panned away. Frame its// content so it's centered and readable on enter (matches Godot/Unity).- // frameSelection skips entities without visual bounds and no-ops if none have.- const world = EngineHost.world;- if (world) ViewportController.frameSelection([...world.getAllEntities()]);+ // Deferred two frames: frameSelection reads composed WORLD transforms, which+ // read (0,0) until the first engine tick — so a variant whose root carries a+ // position override would otherwise frame at the origin and sit off-screen.+ const frameContent = (): void => {+ const world = EngineHost.world;+ if (world) ViewportController.frameSelection([...world.getAllEntities()]);+ };+ requestAnimationFrame(() => requestAnimationFrame(frameContent));const returnLeaf = returnScene ? (returnScene.split('/').pop() ?? returnScene) : null;- this.prefabSession = { ref, path, name: prefab.name, rootSource: rootId, idBySource, returnScene, returnView };- this.store.setState({ project: { ...st, currentScene: null, prefabEdit: { name: prefab.name, path, returnScene: returnLeaf } } });+ const baseRef = prefab.basePrefab ?? null;+ this.prefabSession = { ref, path, name: prefab.name, rootSource: rootId, idBySource, returnScene, returnView, base, baseRef };+ this.store.setState({ project: { ...st, currentScene: null, prefabEdit: { name: prefab.name, path, returnScene: returnLeaf, isVariant: !!baseRef } } });Toasts.push(t('proj.openedPrefab', { name: prefab.name }), 'info', 1600);}@@ -1996,7 +2024,9 @@ class ProjectStoreImpl {/*** Save the prefab being edited in Prefab Mode back to its `.esprefab`, PRESERVING* each entity's prefabEntityId (so existing instances' overrides still resolve)- * and minting uuids only for entities added during the session.+ * and minting uuids only for entities added during the session. A VARIANT session+ * instead collapses the edited tree against its base into a variant delta+ * (keeping basePrefab), so editing a variant stays base-tracked.*/async savePrefab(): Promise<void> {const pe = this.prefabSession;@@ -2005,12 +2035,32 @@ class ProjectStoreImpl {if (!model) return;const idBySource = new Map(pe.idBySource);for (const e of model.entities) if (!idBySource.has(e.id)) idBySource.set(e.id, crypto.randomUUID());- const prefab = extractPrefab(- model.entities as unknown as ExtractEntity[],- pe.rootSource,- pe.name,- (srcId) => idBySource.get(srcId) ?? crypto.randomUUID(),- );++ let prefab: PrefabData;+ if (pe.base && pe.baseRef) {+ // VARIANT: diff the edited tree against the flat base → the variant's own+ // overrides + additions, then rebuild the variant (basePrefab preserved).+ const processed: ProcessedEntity[] = model.entities.map((e) => ({+ id: e.id,+ prefabEntityId: idBySource.get(e.id) ?? crypto.randomUUID(),+ name: e.name,+ parent: e.parent,+ children: e.children ?? [],+ components: e.components as ProcessedEntity['components'],+ visible: (e as { visible?: boolean }).visible ?? true,+ }));+ const delta = collapseInstance(pe.base, pe.baseRef, processed, this.prefabResolverSync);+ 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');+ prefab = buildVariant(pe.base, pe.baseRef, pe.name, { overrides, added: delta.added });+ } else {+ prefab = extractPrefab(+ model.entities as unknown as ExtractEntity[],+ pe.rootSource,+ pe.name,+ (srcId) => idBySource.get(srcId) ?? crypto.randomUUID(),+ );+ }try {await window.estella.fs.write(pe.path, JSON.stringify(prefab, null, 2) + '\n');} catch {