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.

refactor(editor): EngineHost → pure engine host; session owns wiring (P2 U1)

esengine93d5c2aa84e3
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 4f6197b45..f11e356a0 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -3,7 +3,7 @@ import { MenuBar } from '@/layout/MenuBar';
import { Toolbar } from '@/layout/Toolbar';
import { StatusBar } from '@/layout/StatusBar';
import { DockLayout } from '@/layout/DockLayout';
-import { EngineHost } from '@/engine/EngineHost';
+import { defaultSession } from '@/engine/EditorSession';
import { Launcher } from '@/launcher/Launcher';
import { Toaster } from '@/components/Toaster';
import { useEditorStore } from '@/store/editorStore';
@@ -38,7 +38,7 @@ export function App() {
const isPlaying = useEditorStore((s) => s.isPlaying);
const isPaused = useEditorStore((s) => s.isPaused);
useEffect(() => {
- EngineHost.setRunMode(isPlaying, isPaused);
+ defaultSession.surface.setRunMode(isPlaying, isPaused);
}, [isPlaying, isPaused]);
// The editor opens on the launcher (project browser); the shell + engine mount
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index 5fb7a9ed0..f04c65d55 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -24,10 +24,11 @@ import type {
} from '@/types';
import type { SceneData } from 'esengine';
import { EngineHost } from './EngineHost';
-import { SceneCommands, type SceneCommandsImpl } from './SceneCommands';
-import { SceneQuery, type SceneQueryImpl } from './SceneQuery';
-import { SceneModel, type SceneModelImpl } from './SceneModel';
-import { EditorHistory, type EditorHistoryImpl } from './EditorHistory';
+import type { SceneCommandsImpl } from './SceneCommands';
+import type { SceneQueryImpl } from './SceneQuery';
+import type { SceneModelImpl } from './SceneModel';
+import type { EditorHistoryImpl } from './EditorHistory';
+import type { ReconcilerImpl } from './Reconciler';
/** A captured viewport frame: raw RGBA pixels (GL order: bottom-up rows). */
export interface ViewportCapture {
@@ -42,6 +43,7 @@ export interface SurfaceSession {
history: EditorHistoryImpl;
commands: SceneCommandsImpl;
query: SceneQueryImpl;
+ reconciler: ReconcilerImpl;
}
export class EditorControlSurfaceImpl {
@@ -62,12 +64,16 @@ export class EditorControlSurfaceImpl {
}
/**
- * Switch edit↔play. Play runs gameplay against the live World; Stop rebuilds it
- * from the untouched edit model (gameplay never dirties the edit scene). Returns
- * true if a play→edit rebuild happened. Selection survives it (stable source ids).
+ * Switch edit↔play. Play runs gameplay against the live World; on Stop this
+ * rebuilds the World from the untouched edit model (this session's Reconciler)
+ * so gameplay never dirties the edit scene. Returns true if a play→edit rebuild
+ * happened. Selection survives it (stable source ids). The single run-mode
+ * boundary: EngineHost handles the pure engine flip, the session the rebuild.
*/
setRunMode(playing: boolean, paused = false): boolean {
- return EngineHost.setRunMode(playing, paused);
+ const wasStop = EngineHost.setRunMode(playing, paused);
+ if (wasStop) this.s.reconciler.rebuildWorld();
+ return wasStop;
}
/**
@@ -186,12 +192,7 @@ export class EditorControlSurfaceImpl {
}
}
-/** The app's default-session control surface. */
-export const EditorControlSurface = new EditorControlSurfaceImpl({
- model: SceneModel,
- history: EditorHistory,
- commands: SceneCommands,
- query: SceneQuery,
-});
-
+// The app's default-session surface is `EditorSession.default.surface`, exported
+// as `EditorControlSurface` from EditorSession.ts — one default surface, owned by
+// the session (no parallel singleton here).
export type EditorControlSurfaceT = EditorControlSurfaceImpl;
diff --git a/desktop/src/engine/EditorSession.ts b/desktop/src/engine/EditorSession.ts
index 6b9a00c9c..e797ba60c 100644
--- a/desktop/src/engine/EditorSession.ts
+++ b/desktop/src/engine/EditorSession.ts
@@ -5,7 +5,7 @@ import { Reconciler, ReconcilerImpl } from './Reconciler';
import { SceneCommands, SceneCommandsImpl } from './SceneCommands';
import { SceneQuery, SceneQueryImpl } from './SceneQuery';
import { useSelection, createSelectionStore, type SelectionStore } from '@/store/selectionStore';
-import { EditorControlSurface, EditorControlSurfaceImpl } from './EditorControlSurface';
+import { EditorControlSurfaceImpl } from './EditorControlSurface';
/**
* The single editor boundary (REARCH_EDITOR_MODEL.md §3.5, P2). One instance owns
@@ -85,9 +85,13 @@ export class EditorSession {
selection: useSelection,
commands: SceneCommands,
query: SceneQuery,
- surface: EditorControlSurface,
});
}
/** The app's default editor session (the one the UI drives). */
export const defaultSession = EditorSession.default;
+
+/** The app's default-session control surface — the ONE programmatic boundary for
+ * the UI, the headless host, and the MCP server (REARCH_EDITOR_MODEL.md P2). */
+export const EditorControlSurface = defaultSession.surface;
+export type { EditorControlSurfaceT } from './EditorControlSurface';
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index f767d3c46..c9afe30a4 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -12,8 +12,6 @@ import {
setPlayMode,
} from 'esengine';
import type { App, ESEngineModule, ResourceDef } from 'esengine';
-import { SceneStore } from './SceneStore';
-import { Reconciler } from './Reconciler';
import { SceneLoader } from './SceneLoader';
import { checkEngineBuild } from './EngineGuard';
import type { ReadonlyWorldT, WorldT } from './schema';
@@ -127,28 +125,23 @@ class EngineHostImpl {
}
/**
- * Map the editor's play/pause UI state onto the engine, with play-state
- * isolation: entering play runs gameplay against the live World; Stop discards
- * those mutations by rebuilding the World from the untouched edit MODEL
- * (model-authoritative, REARCH_EDITOR_MODEL.md) — no snapshot, no stale id map.
- * Not playing ⇒ edit mode (gameplay frozen via env.playModeOnly, scene still
+ * Map the editor's play/pause UI state onto the engine (pure engine concern):
+ * not playing ⇒ edit mode (gameplay frozen via env.playModeOnly, scene still
* rendered/editable); playing ⇒ gameplay runs; paused-while-playing halts every
* schedule. No-op until booted.
*
- * @returns true if a play→edit rebuild happened. Selection survives it (source
- * ids are stable across the rebuild), so the caller need not clear it.
+ * Play-state isolation (rebuilding the World from the untouched edit MODEL on
+ * Stop) is orchestrated by the EditorSession/surface, not here — EngineHost is
+ * a pure engine host and does not know the Reconciler.
+ *
+ * @returns true if this was a play→edit (Stop) transition, so the caller
+ * (the session) can rebuild the World from the model.
*/
setRunMode(isPlaying: boolean, isPaused: boolean): boolean {
const app = this.app_;
if (!app) return false;
- let restored = false;
- if (!isPlaying && this.playing_) {
- // play → edit (Stop): rebuild the World from the untouched edit model,
- // discarding everything gameplay did to the World during play.
- Reconciler.rebuildWorld();
- restored = true;
- }
+ const wasStop = !isPlaying && this.playing_;
this.playing_ = isPlaying;
// The editor camera shows in edit mode; entering play switches the viewport
@@ -159,7 +152,7 @@ class EngineHostImpl {
setPlayMode(isPlaying);
app.setPaused(isPlaying && isPaused);
- return restored;
+ return wasStop;
}
/**
@@ -337,12 +330,11 @@ class EngineHostImpl {
setEditorMode(true);
setPlayMode(false);
- // Model-authoritative data flow (REARCH_EDITOR_MODEL.md): commands mutate
- // the SceneModel; the Reconciler is the single writer that follows into the
- // World, and SceneStore turns model changes into panel reactivity. Attach
- // the Reconciler FIRST so the World is projected before reactivity fires.
- Reconciler.attach();
- SceneStore.install();
+ // Model-authoritative wiring (Reconciler model→World projection + SceneStore
+ // reactivity) is owned by the EditorSession (constructed at app/headless
+ // entry), not here — EngineHost is a pure engine host (REARCH_EDITOR_MODEL.md
+ // P2). The session's wiring only subscribes the model, so it is in place
+ // before this boot loads the initial scene.
if (opts.loadInitialScene) {
// Load the opened project's scene if the launcher set a bootstrap;
diff --git a/desktop/src/headless.ts b/desktop/src/headless.ts
index abf226088..fed6a7cb8 100644
--- a/desktop/src/headless.ts
+++ b/desktop/src/headless.ts
@@ -9,7 +9,9 @@
* back for reproducible verification.
*/
import { EngineHost } from './engine/EngineHost';
-import { EditorControlSurface, type EditorControlSurfaceT } from './engine/EditorControlSurface';
+// From EditorSession: importing it constructs the default session (which wires the
+// Reconciler + SceneStore to the model) before the engine boots below.
+import { EditorControlSurface, type EditorControlSurfaceT } from './engine/EditorSession';
declare global {
interface Window {