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.

feat(editor): Prefab Mode return-flow polish + first-class context (P2 UX)

yhhfd60426589cb
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 026f2066f..701d667e2 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import { useEffect } from 'react';
+import { useEffect, useSyncExternalStore } from 'react';
import { MenuBar } from '@/layout/MenuBar';
import { Toolbar } from '@/layout/Toolbar';
import { StatusBar } from '@/layout/StatusBar';
@@ -246,6 +246,9 @@ export function App() {
return () => { cancelled = true; clearTimeout(safety); LoadGate.close(); };
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [showLauncher]);
+ // Prefab Mode tints the whole workspace so it's unmistakable you're editing a
+ // prefab asset, not the scene (the banner names it; this frames the viewport).
+ const inPrefabMode = useSyncExternalStore(ProjectStore.subscribe, () => !!ProjectStore.getSnapshot()?.prefabEdit);
const buildOpen = useEditorStore((s) => s.buildOpen);
const settingsOpen = useEditorStore((s) => s.settingsOpen);
const tilemapPickerOpen = useEditorStore((s) => s.tilemapPickerOpen);
@@ -256,7 +259,7 @@ export function App() {
// the StatusBar consuming live engine data every 333ms) shows a recoverable
// card instead of white-screening the whole editor.
return (
- <div className="shell">
+ <div className={inPrefabMode ? 'shell shell--prefab' : 'shell'}>
<ErrorBoundary label="menubar"><Perf id="menubar"><MenuBar /></Perf></ErrorBoundary>
<ErrorBoundary label="toolbar"><Perf id="toolbar"><Toolbar /></Perf></ErrorBoundary>
<ErrorBoundary label="prefab-banner"><PrefabModeBanner /></ErrorBoundary>
diff --git a/desktop/src/components/PrefabModeBanner.tsx b/desktop/src/components/PrefabModeBanner.tsx
index 81910c8ba..d436ed0b4 100644
--- a/desktop/src/components/PrefabModeBanner.tsx
+++ b/desktop/src/components/PrefabModeBanner.tsx
@@ -16,6 +16,7 @@ export function PrefabModeBanner() {
const project = useSyncExternalStore(ProjectStore.subscribe, ProjectStore.getSnapshot);
const pe = project?.prefabEdit;
if (!pe) return null;
+ const back = pe.returnScene ? t('proj.prefabModeBackTo', { name: pe.returnScene }) : t('proj.prefabModeBack');
return (
<div className="prefab-mode-bar">
<span className="pmb-icon"><Package size={14} strokeWidth={1.9} /></span>
@@ -26,7 +27,7 @@ export function PrefabModeBanner() {
<Save size={13} strokeWidth={1.9} /> {t('proj.prefabModeSave')}
</Button>
<Button onClick={() => void ProjectStore.exitPrefabMode()}>
- <ArrowLeft size={13} strokeWidth={1.9} /> {t('proj.prefabModeBack')}
+ <ArrowLeft size={13} strokeWidth={1.9} /> {back}
</Button>
</span>
</div>
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index 3d89add52..5d2cfb74f 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -301,6 +301,24 @@ class EngineHostImpl {
view.active = !this.playing_;
}
+ /** The editor camera's current center + ortho half-height, or null pre-boot.
+ * Prefab Mode saves this on enter so exit can return the user to the exact
+ * scene view they left (syncEditorViewToScene would otherwise reframe). */
+ editorViewState(): { x: number; y: number; orthoSize: number } | null {
+ const view = this.getResource(EditorView);
+ return view ? { x: view.x, y: view.y, orthoSize: view.orthoSize } : null;
+ }
+
+ /** Restore the editor camera to a saved center + zoom (the inverse read of
+ * {@link editorViewState}). No-op pre-boot. */
+ setEditorView(v: { x: number; y: number; orthoSize: number }): void {
+ const view = this.getResource(EditorView);
+ if (!view) return;
+ view.x = v.x;
+ view.y = v.y;
+ view.orthoSize = v.orthoSize;
+ }
+
/**
* Drive the editor reference grid from the editor's Show-Flags + Snap state.
* The renderer only paints when the EditorView is active (edit mode), so this
diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.ts
index 6e795982c..23aaeb634 100644
--- a/desktop/src/i18n/messages/project.ts
+++ b/desktop/src/i18n/messages/project.ts
@@ -122,7 +122,9 @@ export const projectMessages = defineMessages({
'proj.prefabModeNested': { en: 'Nested / variant prefabs can\'t be edited in place yet', zh: '暂不支持原位编辑嵌套 / 变体预制体' },
'proj.prefabModeBanner': { en: 'Editing Prefab', zh: '正在编辑预制体' },
'proj.prefabModeBack': { en: 'Back to Scene', zh: '返回场景' },
+ 'proj.prefabModeBackTo': { en: 'Back to {name}', zh: '返回 {name}' },
'proj.prefabModeSave': { en: 'Save Prefab', zh: '保存预制体' },
+ 'proj.prefabBadge': { en: 'Prefab', zh: '预制体' },
'proj.resaveNone': { en: 'No prefabs to re-save', zh: '没有可重新保存的预制体' },
'proj.resaveDone': { en: 'Re-saved {count} prefab(s) to the current format', zh: '已将 {count} 个预制体重新保存为当前格式' },
'proj.resaveFailed': { en: 'Re-saved {upgraded}, {failed} failed', zh: '已重新保存 {upgraded} 个,{failed} 个失败' },
@@ -141,6 +143,7 @@ export const projectMessages = defineMessages({
'proj.includedInExport': { en: 'Included in export: {name}', zh: '已包含在导出中:{name}' },
'proj.saveExclusionFailed': { en: 'Failed to save export exclusion', zh: '保存导出排除项失败' },
'proj.openedScene': { en: 'Opened {name}', zh: '已打开 {name}' },
+ 'proj.returnedScene': { en: 'Returned to {name}', zh: '已返回 {name}' },
'proj.savedScene': { en: 'Saved {name}', zh: '已保存 {name}' },
// — Play realm (Game panel overlay fallbacks) —
diff --git a/desktop/src/layout/MenuBar.tsx b/desktop/src/layout/MenuBar.tsx
index e5e1f9c1d..8d38fe16d 100644
--- a/desktop/src/layout/MenuBar.tsx
+++ b/desktop/src/layout/MenuBar.tsx
@@ -248,7 +248,13 @@ export function MenuBar() {
{project ? (
<div className="menubar-title">
<strong>{project.name}</strong>
- {project.currentScene ? (
+ {project.prefabEdit ? (
+ <>
+ <span className="sep">/</span>
+ <span className="mono">{project.prefabEdit.name}</span>
+ <span className="prefab-crumb-tag">{t('proj.prefabBadge')}</span>
+ </>
+ ) : project.currentScene ? (
<>
<span className="sep">/</span>
<span className="mono">{project.currentScene.split('/').pop()}</span>
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index b9205f333..d7e723224 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -172,6 +172,8 @@ if (new URLSearchParams(location.search).has('automation')) {
logs: (tail = 50) => LogStore.getSnapshot().slice(-tail),
togglePerfOverlay: () => PerfMonitor.toggleOverlay(),
captureThumbnail: () => ProjectStore.captureThumbnail(),
+ /** The editor camera center + zoom (framing assertions in shot tests). */
+ editorView: () => EngineHost.editorViewState(),
surface: EditorControlSurface,
/** Live world position of a SOURCE entity (engine-composed, Yoga-fresh for
* UI nodes) — lets a drag-automation shot assert a move stuck or was
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 7bec58e97..648c8a5d3 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -9,6 +9,7 @@ import { applyWidgetTheme } from '@/engine/widgetTheme';
import { bootProfiler } from '@/engine/bootProfiler';
import { SceneModel } from '@/engine/SceneModel';
import { Reconciler } from '@/engine/Reconciler';
+import { ViewportController } from '@/engine/ViewportController';
import { blankInputMap } from './inputMapDoc';
import { EditorHistory } from '@/engine/EditorHistory';
import { expandScenePrefabs, collapseScenePrefabs } from '@/engine/PrefabInstance';
@@ -142,8 +143,9 @@ interface ProjectState {
/** The scene currently loaded into the world (project-relative path). */
currentScene: string | null;
/** When editing a PREFAB asset in place (Prefab Mode) rather than a scene:
- * the prefab's display name + path, for the banner. `currentScene` is null. */
- prefabEdit?: { name: string; path: string } | null;
+ * 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;
}
/**
@@ -215,6 +217,9 @@ class ProjectStoreImpl {
rootSource: number;
idBySource: Map<number, string>;
returnScene: string | null;
+ /** 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;
} | 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
@@ -1777,12 +1782,14 @@ class ProjectStoreImpl {
* Open a different scene file as the editor document (Content Browser
* double-click). Persists it as the last-opened scene and reloads the world
* (which clears history + selection — the caller guards unsaved changes).
+ * `quiet` suppresses the "Opened" toast so a caller that owns its own feedback
+ * (exitPrefabMode's "Returned to …") isn't double-noted.
*/
- async openScene(relPath: string): Promise<void> {
+ async openScene(relPath: string, opts?: { quiet?: boolean }): Promise<void> {
if (!this.state) return;
await this.persistLastScene(relPath);
await this.loadCurrentScene();
- Toasts.push(t('proj.openedScene', { name: relPath.split('/').pop() ?? relPath }), 'info', 1600);
+ if (!opts?.quiet) Toasts.push(t('proj.openedScene', { name: relPath.split('/').pop() ?? relPath }), 'info', 1600);
}
/**
@@ -1810,6 +1817,12 @@ class ProjectStoreImpl {
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
+ // session's — its currentScene is null), so "Back" always lands in the scene.
+ const returnScene = this.prefabSession?.returnScene ?? st.currentScene;
+ const returnView = this.prefabSession?.returnView ?? EngineHost.editorViewState();
+
// Flatten the asset into ordinary entities; remember each entity's stable id.
let nid = 0;
const { entities, rootId } = flattenPrefab(prefab, [], { allocateId: () => nid++, loadPrefab: () => null });
@@ -1824,8 +1837,15 @@ class ProjectStoreImpl {
} as unknown as SceneData;
await this.adoptDocument(sceneData);
- this.prefabSession = { ref, path, name: prefab.name, rootSource: rootId, idBySource, returnScene: st.currentScene };
- this.store.setState({ project: { ...st, currentScene: null, prefabEdit: { name: prefab.name, path } } });
+ // 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()]);
+ 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 } } });
Toasts.push(t('proj.openedPrefab', { name: prefab.name }), 'info', 1600);
}
@@ -1884,16 +1904,24 @@ class ProjectStoreImpl {
Toasts.push(t('proj.savedPrefab', { name: pe.name }), 'success');
}
- /** Leave Prefab Mode and return to the scene that was open (or a blank one). */
+ /** Leave Prefab Mode and return to the scene that was open (or a blank one),
+ * restoring the editor view the user left it at. */
async exitPrefabMode(): Promise<void> {
if (!this.prefabSession) return;
if (!(await confirmDiscard(t('discard.exitPrefab')))) return;
- const back = this.prefabSession.returnScene;
+ const { returnScene: back, returnView } = this.prefabSession;
this.prefabSession = null;
const st = this.state;
if (st) this.store.setState({ project: { ...st, prefabEdit: null } });
- if (back) await this.openScene(back);
- else await this.newScene();
+ if (back) {
+ await this.openScene(back, { quiet: true });
+ // Reframe to where the user was before entering (openScene reseeds the view
+ // from the scene camera; this puts their pan/zoom back).
+ if (returnView) EngineHost.setEditorView(returnView);
+ Toasts.push(t('proj.returnedScene', { name: back.split('/').pop() ?? back }), 'info', 1600);
+ } else {
+ await this.newScene();
+ }
}
/** True if the changed paths include the open scene document. */
diff --git a/desktop/src/theme/menus.css b/desktop/src/theme/menus.css
index 0f4b60846..e1d20a128 100644
--- a/desktop/src/theme/menus.css
+++ b/desktop/src/theme/menus.css
@@ -172,6 +172,22 @@
.prefab-mode-bar .pmb-name { font-weight: 600; color: var(--info-warm); }
.prefab-mode-bar .pmb-actions { margin-left: auto; display: flex; gap: 6px; }
+/* Title-bar crumb tag: a small "Prefab" chip next to the prefab name so the
+ window title reads as a prefab document, not an unnamed scene. */
+.menubar-title .prefab-crumb-tag {
+ font-size: var(--fs-2xs); font-weight: 600; letter-spacing: 0.02em;
+ color: var(--info-warm); background: var(--info-warm-soft);
+ border: 1px solid var(--info-warm-line); border-radius: 4px;
+ padding: 0 5px; line-height: 15px;
+}
+
+/* Prefab Mode frames the workspace in the same warm accent as the banner, so the
+ viewport itself reads as "editing a prefab" at a glance. Inset so it never
+ overlaps panel scrollbars. */
+.shell--prefab .shell__workspace {
+ box-shadow: inset 0 0 0 1px var(--info-warm-line);
+}
+
/* ── New Tilemap tileset chooser ── */
.tmpick { display: flex; flex-direction: column; gap: 10px; }
.tmpick__hint { font-size: var(--fs-sm); color: var(--text-mute); }