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): Prefab Mode return-flow polish + first-class context (P2 UX)
yhhfd60426589cb
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsxindex 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.tsxindex 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.tsindex 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 thisdiff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.tsindex 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.tsxindex 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.tsxindex 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 wasdiff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex 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.cssindex 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); }