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): UE5-PIE live game inspection in Outliner/Details (PD2/PD3)

esengineb563d4455b74
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsx
index 64b2bd6f1..c54de63ea 100644
--- a/desktop/src/App.tsx
+++ b/desktop/src/App.tsx
@@ -12,6 +12,7 @@ import { BuildDialog } from '@/components/BuildDialog';
import { useEditorStore } from '@/store/editorStore';
import { commands } from '@/commands';
import { PlayRealm } from '@/engine/PlayRealm';
+import { PlayInspect } from '@/engine/PlayInspect';
import { ProjectStore } from '@/project/ProjectStore';
import { dockApi } from '@/layout/dockApi';
import { Toasts } from '@/store/Toasts';
@@ -60,10 +61,14 @@ export function App() {
return;
}
void PlayRealm.start(payload);
+ PlayInspect.start(); // poll the running game for live inspect/debug
+ useEditorStore.getState().setInspectWorld('game'); // flip Outliner/Details to the live game
// 'window' → a Game dock tab; 'viewport' → the Viewport mounts it (PIE).
if (useEditorStore.getState().playTarget === 'window') dockApi.openGame();
} else {
PlayRealm.stop();
+ PlayInspect.stop();
+ useEditorStore.getState().setInspectWorld('editor');
dockApi.closeGame();
}
}, [isPlaying]);
diff --git a/desktop/src/engine/PlayInspect.ts b/desktop/src/engine/PlayInspect.ts
new file mode 100644
index 000000000..ee667e6b8
--- /dev/null
+++ b/desktop/src/engine/PlayInspect.ts
@@ -0,0 +1,63 @@
+/**
+ * @file PlayInspect.ts — the editor's "Game" inspection source (UE5-PIE Details).
+ * While playing, it polls the running realm for a live SceneData snapshot
+ * (via PlayRealm.snapshot → serializeScene of the realm's World) and holds
+ * the user's live selection. The Outliner/Details build their view-models
+ * from this snapshot (reusing buildSceneTree/buildInspector) when in Game
+ * mode; field edits route to PlayRealm.setField (live, reverts on Stop).
+ *
+ * Selection here is a REALM runtime id — distinct from the editor's
+ * source-id selection (selectionStore), never mixed.
+ */
+import { createStore } from 'zustand/vanilla';
+import type { SceneData } from 'esengine';
+import type { EntityId } from '@/types';
+import { PlayRealm } from './PlayRealm';
+
+interface PlayInspectState {
+ snapshot: SceneData | null;
+ selection: EntityId | null;
+}
+
+const POLL_MS = 300;
+
+class PlayInspectImpl {
+ private readonly store = createStore<PlayInspectState>(() => ({ snapshot: null, selection: null }));
+ private timer: ReturnType<typeof setInterval> | null = null;
+
+ subscribe = (fn: () => void): (() => void) => this.store.subscribe(fn);
+ getSnapshot = (): PlayInspectState => this.store.getState();
+
+ select(selection: EntityId | null): void {
+ this.store.setState({ ...this.store.getState(), selection });
+ }
+
+ /** Begin polling the running realm (call on Play). */
+ start(): void {
+ this.stop();
+ void this.poll();
+ this.timer = setInterval(() => void this.poll(), POLL_MS);
+ }
+
+ /** Stop polling + clear (call on Stop) — live state is discarded with the realm. */
+ stop(): void {
+ if (this.timer) {
+ clearInterval(this.timer);
+ this.timer = null;
+ }
+ this.store.setState({ snapshot: null, selection: null });
+ }
+
+ /** Live-edit a field of the running game; refresh immediately for snappy feedback. */
+ setField(id: EntityId, comp: string, key: string, value: unknown): void {
+ PlayRealm.setField(id, comp, key, value);
+ void this.poll();
+ }
+
+ private async poll(): Promise<void> {
+ const snapshot = await PlayRealm.snapshot();
+ if (snapshot) this.store.setState({ ...this.store.getState(), snapshot });
+ }
+}
+
+export const PlayInspect = new PlayInspectImpl();
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index cb6fefceb..e56de1e10 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -46,7 +46,7 @@ const valueEqual = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JS
* components keep the untouched axis; color keeps alpha). 2D rotation is stored
* as a quaternion; angle controls convert degrees↔quat.
*/
-function toModelValue(
+export function toModelValue(
cur: Record<string, unknown>,
type: InspectorFieldType,
key: string,
diff --git a/desktop/src/engine/SceneQuery.ts b/desktop/src/engine/SceneQuery.ts
index 83da48563..9a6923dbc 100644
--- a/desktop/src/engine/SceneQuery.ts
+++ b/desktop/src/engine/SceneQuery.ts
@@ -1,3 +1,4 @@
+import type { SceneData } from 'esengine';
import type { SceneNode, NodeKind, EntityId, InspectorComponent, InspectorFieldValue } from '@/types';
import { SceneStore, SceneStoreImpl } from './SceneStore';
import { SceneModel, SceneModelImpl } from './SceneModel';
@@ -11,6 +12,56 @@ import {
modelIsVisible,
} from './schema';
+type SceneEntity = SceneData['entities'][number];
+
+// ── Pure view-model builders over a SceneData ────────────────────────────────
+// Shared by SceneQuery (the editor model) and PlayInspect (a live realm snapshot
+// from serializeScene) — same view-models, different source. Ids are whatever the
+// source uses (editor source ids / realm runtime ids).
+
+/** Outliner tree from a SceneData; nesting derived from each entity's `parent`. */
+export function buildSceneTree(data: SceneData | null): SceneNode[] {
+ if (!data) return [];
+ const ids = new Set(data.entities.map((e) => e.id));
+ const childrenOf = new Map<number, SceneEntity[]>();
+ const roots: SceneEntity[] = [];
+ for (const e of data.entities) {
+ if (e.parent != null && ids.has(e.parent)) {
+ const arr = childrenOf.get(e.parent);
+ if (arr) arr.push(e);
+ else childrenOf.set(e.parent, [e]);
+ } else {
+ roots.push(e); // no parent, or a dangling parent → a scene root
+ }
+ }
+ const build = (e: SceneEntity): SceneNode => {
+ const kind = modelKindOf(e);
+ const kids = childrenOf.get(e.id)?.map(build);
+ return { id: e.id, name: modelNameOf(e, kind), kind, visible: modelIsVisible(e), locked: false, children: kids && kids.length ? kids : undefined };
+ };
+ return roots.map(build);
+}
+
+/** Name/kind/components for one entity in a SceneData. */
+export function buildEntityInfo(data: SceneData | null, id: EntityId): { name: string; kind: NodeKind; components: string[] } | null {
+ const e = data?.entities.find((x) => x.id === id);
+ if (!e) return null;
+ const kind = modelKindOf(e);
+ return { name: modelNameOf(e, kind), kind, components: modelInspectableComponents(e).map((c) => c.label) };
+}
+
+/** Full inspector model for one entity in a SceneData. */
+export function buildInspector(data: SceneData | null, id: EntityId): InspectorComponent[] {
+ const e = data?.entities.find((x) => x.id === id);
+ if (!e) return [];
+ const out: InspectorComponent[] = [];
+ for (const { name, label } of modelInspectableComponents(e)) {
+ const cdata = (e.components.find((c) => c.type === name)?.data as Record<string, unknown>) ?? {};
+ out.push({ name, label, fields: inspectorFields(name, cdata) });
+ }
+ return out;
+}
+
/**
* Read-only projection of the editor's source-of-truth model into view-models
* (REARCH_EDITOR_MODEL.md §3.4). The outliner tree, inspector, and field reads
@@ -42,56 +93,17 @@ export class SceneQueryImpl {
* walk would silently drop or double-count.
*/
readSceneTree(): SceneNode[] {
- const data = this.model.current;
- if (!data) return [];
-
- const ids = new Set(data.entities.map((e) => e.id));
- const childrenOf = new Map<number, Array<(typeof data.entities)[number]>>();
- const roots: Array<(typeof data.entities)[number]> = [];
- for (const e of data.entities) {
- if (e.parent != null && ids.has(e.parent)) {
- const arr = childrenOf.get(e.parent);
- if (arr) arr.push(e);
- else childrenOf.set(e.parent, [e]);
- } else {
- roots.push(e); // no parent, or a dangling parent → a scene root
- }
- }
-
- const build = (e: (typeof data.entities)[number]): SceneNode => {
- const kind = modelKindOf(e);
- const kids = childrenOf.get(e.id)?.map(build);
- return {
- id: e.id,
- name: modelNameOf(e, kind),
- kind,
- visible: modelIsVisible(e),
- locked: false,
- children: kids && kids.length ? kids : undefined,
- };
- };
-
- return roots.map(build);
+ return buildSceneTree(this.model.current);
}
/** Inspect a single source entity (name, kind, which components it carries). */
readEntity(id: EntityId): { name: string; kind: NodeKind; components: string[] } | null {
- const e = this.model.entityBySource(id);
- if (!e) return null;
- const kind = modelKindOf(e);
- return { name: modelNameOf(e, kind), kind, components: modelInspectableComponents(e).map((c) => c.label) };
+ return buildEntityInfo(this.model.current, id);
}
/** Full editable inspector model for a source entity — fields resolved per component. */
readInspector(id: EntityId): InspectorComponent[] {
- const e = this.model.entityBySource(id);
- if (!e) return [];
- const out: InspectorComponent[] = [];
- for (const { name, label } of modelInspectableComponents(e)) {
- const data = (e.components.find((c) => c.type === name)?.data as Record<string, unknown>) ?? {};
- out.push({ name, label, fields: inspectorFields(name, data) });
- }
- return out;
+ return buildInspector(this.model.current, id);
}
/** Read one inspector field's current value (for undo before/after capture). */
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 97ec5d4ae..721fb79e6 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -25,11 +25,13 @@ import { AssetIcon, assetTint } from '@/components/icons';
import { Toasts } from '@/store/Toasts';
import { baseName, assetTypeOf, TYPE_CODE, IMAGE_RE } from '@/project/assetMeta';
import { useSelection } from '@/store/selectionStore';
+import { useEditorStore } from '@/store/editorStore';
import { EngineHost } from '@/engine/EngineHost';
import { SceneStore } from '@/engine/SceneStore';
-import { SceneQuery } from '@/engine/SceneQuery';
+import { SceneQuery, buildEntityInfo, buildInspector } from '@/engine/SceneQuery';
import { SceneModel } from '@/engine/SceneModel';
-import { SceneCommands } from '@/engine/SceneCommands';
+import { SceneCommands, toModelValue } from '@/engine/SceneCommands';
+import { PlayInspect } from '@/engine/PlayInspect';
import { modelAddableComponentEntries } from '@/engine/schema';
import { ProjectStore } from '@/project/ProjectStore';
import { ContextMenu } from '@/components/Menu';
@@ -351,11 +353,15 @@ function AssetControl({
);
}
-function FieldRow({ entity, comp, field }: { entity: EntityId; comp: string; field: InspectorField }) {
+// A field write override (the live "Game" inspector routes edits to the realm
+// instead of the undoable SceneCommands path). When set, gestures are no-ops.
+type FieldWrite = (key: string, type: InspectorField['type'], value: number | boolean | string | number[]) => void;
+
+function FieldRow({ entity, comp, field, write }: { entity: EntityId; comp: string; field: InspectorField; write?: FieldWrite }) {
const apply = (value: number | boolean | string | number[]) =>
- SceneCommands.setField(entity, comp, field.key, field.type, value as never);
- const begin = () => SceneCommands.beginGesture(`Edit ${field.label}`);
- const end = () => SceneCommands.endGesture();
+ write ? write(field.key, field.type, value) : SceneCommands.setField(entity, comp, field.key, field.type, value as never);
+ const begin = () => (write ? undefined : SceneCommands.beginGesture(`Edit ${field.label}`));
+ const end = () => (write ? undefined : SceneCommands.endGesture());
// Scalars (number/angle) scrub from the label; vectors from their axis tabs.
const isScalar = field.type === 'number' || field.type === 'angle';
@@ -411,12 +417,14 @@ function ComponentSection({
collapsed,
onToggle,
onMore,
+ write,
}: {
entity: EntityId;
comp: InspectorComponent;
collapsed: boolean;
onToggle: () => void;
- onMore: (e: React.MouseEvent, name: string) => void;
+ onMore?: (e: React.MouseEvent, name: string) => void;
+ write?: FieldWrite;
}) {
const Icon = componentIcon(comp.name);
return (
@@ -433,23 +441,25 @@ function ComponentSection({
<Icon size={13} strokeWidth={1.9} />
</span>
<span className="comp-name">{comp.label}</span>
- <button
- type="button"
- className="comp-menu"
- title="Component options"
- onClick={(e) => {
- e.stopPropagation();
- onMore(e, comp.name);
- }}
- >
- <MoreHorizontal size={13} strokeWidth={2} />
- </button>
+ {onMore && (
+ <button
+ type="button"
+ className="comp-menu"
+ title="Component options"
+ onClick={(e) => {
+ e.stopPropagation();
+ onMore(e, comp.name);
+ }}
+ >
+ <MoreHorizontal size={13} strokeWidth={2} />
+ </button>
+ )}
</header>
<div className="comp-body">
<div className="cinner">
<div className="comp-fields">
{comp.fields.map((f) => (
- <FieldRow key={f.key} entity={entity} comp={comp.name} field={f} />
+ <FieldRow key={f.key} entity={entity} comp={comp.name} field={f} write={write} />
))}
</div>
</div>
@@ -458,6 +468,59 @@ function ComponentSection({
);
}
+// The live "Game" inspector (UE5 PIE Details): reads the running realm snapshot +
+// routes edits to the realm (live, reverts on Stop). Structure is read-only here
+// (no add/remove/rename of the running game) — just live value debugging.
+function GameDetails() {
+ const { snapshot, selection } = useSyncExternalStore(PlayInspect.subscribe, PlayInspect.getSnapshot);
+ const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
+ const toggle = (name: string) =>
+ setCollapsed((s) => {
+ const n = new Set(s);
+ if (n.has(name)) n.delete(name);
+ else n.add(name);
+ return n;
+ });
+
+ const info = selection != null ? buildEntityInfo(snapshot, selection) : null;
+ const inspector = selection != null ? buildInspector(snapshot, selection) : [];
+ const compData = (name: string): Record<string, unknown> =>
+ (snapshot?.entities.find((e) => e.id === selection)?.components.find((c) => c.type === name)?.data as Record<string, unknown>) ?? {};
+
+ return (
+ <div className="insp">
+ <div className="game-live">● Playing — live values (revert on Stop)</div>
+ {selection == null || !info ? (
+ <div className="empty">
+ <p>Select a running entity in the Outliner to inspect + tweak it live.</p>
+ </div>
+ ) : (
+ <>
+ <div className="ent-head">
+ <span className="ent-name">{info.name}</span>
+ <span className="ent-meta">
+ <span className="pill">{info.kind}</span>
+ <span className="pill">#{selection}</span>
+ </span>
+ </div>
+ {inspector.map((comp) => (
+ <ComponentSection
+ key={comp.name}
+ entity={selection}
+ comp={comp}
+ collapsed={collapsed.has(comp.name)}
+ onToggle={() => toggle(comp.name)}
+ write={(key, type, value) =>
+ PlayInspect.setField(selection, comp.name, key, toModelValue(compData(comp.name), type, key, value as never))
+ }
+ />
+ ))}
+ </>
+ )}
+ </div>
+ );
+}
+
// Asset view of the unified inspector — shown when an asset (not an entity) is
// selected (in the content browser). Only fields the fs layer provides; the
// preview is the image itself or the type glyph.
@@ -516,7 +579,13 @@ function AssetInspector({ path }: { path: string }) {
);
}
+// Dispatcher: the live game inspector during PIE, the edit inspector otherwise.
export function Details() {
+ const inspectWorld = useEditorStore((s) => s.inspectWorld);
+ return inspectWorld === 'game' ? <GameDetails /> : <EditorDetails />;
+}
+
+function EditorDetails() {
const engine = useSyncExternalStore(EngineHost.subscribe, EngineHost.getSnapshot);
const revision = useSyncExternalStore(SceneStore.subscribe, SceneStore.getRevision);
const selectedId = useSelection((s) => s.selectedId);
diff --git a/desktop/src/panels/Outliner.tsx b/desktop/src/panels/Outliner.tsx
index 2b89e09ee..a599076bb 100644
--- a/desktop/src/panels/Outliner.tsx
+++ b/desktop/src/panels/Outliner.tsx
@@ -4,9 +4,10 @@ import { useEditorStore } from '@/store/editorStore';
import { useSelection } from '@/store/selectionStore';
import { EngineHost } from '@/engine/EngineHost';
import { SceneStore } from '@/engine/SceneStore';
-import { SceneQuery } from '@/engine/SceneQuery';
+import { SceneQuery, buildSceneTree } from '@/engine/SceneQuery';
import { SceneCommands } from '@/engine/SceneCommands';
import { SceneModel } from '@/engine/SceneModel';
+import { PlayInspect } from '@/engine/PlayInspect';
import { ProjectStore } from '@/project/ProjectStore';
import { NodeIcon } from '@/components/icons';
import { ContextMenu, type MenuItem } from '@/components/Menu';
@@ -163,10 +164,58 @@ function flatVisible(nodes: SceneNode[], expanded: Set<EntityId>, forceExpand: b
}
}
+// The live "Game" tree (UE5 PIE world): a read-only view of the running realm's
+// entities (from PlayInspect's snapshot); click selects into PlayInspect, which
+// the Details panel inspects/edits live. Always-expanded (transient debug view).
+function GameRow({ node, depth, selection }: { node: SceneNode; depth: number; selection: EntityId | null }) {
+ return (
+ <>
+ <div
+ className={`row${selection === node.id ? ' sel' : ''}`}
+ style={{ paddingLeft: depth * 14 }}
+ onClick={() => PlayInspect.select(node.id)}
+ >
+ <span className="twist leaf">
+ <ChevronRight size={9} strokeWidth={3} />
+ </span>
+ <span className="ricon">
+ <NodeIcon kind={node.kind} />
+ </span>
+ <span className="rname">{node.name}</span>
+ <span className="rtype">{KIND_TYPE[node.kind] ?? 'Entity'}</span>
+ </div>
+ {node.children?.map((c) => <GameRow key={c.id} node={c} depth={depth + 1} selection={selection} />)}
+ </>
+ );
+}
+
+function GameTree() {
+ const { snapshot, selection } = useSyncExternalStore(PlayInspect.subscribe, PlayInspect.getSnapshot);
+ const tree = useMemo(() => buildSceneTree(snapshot), [snapshot]);
+ if (tree.length === 0) {
+ return (
+ <div className="empty">
+ <Search size={22} strokeWidth={1.4} />
+ <p>Waiting for the running game…</p>
+ </div>
+ );
+ }
+ return (
+ <>
+ {tree.map((n) => (
+ <GameRow key={n.id} node={n} depth={0} selection={selection} />
+ ))}
+ </>
+ );
+}
+
export function Outliner() {
const engine = useSyncExternalStore(EngineHost.subscribe, EngineHost.getSnapshot);
const structRev = useSyncExternalStore(SceneStore.subscribe, SceneStore.getStructureRevision);
const expanded = useEditorStore((s) => s.expanded);
+ const isPlaying = useEditorStore((s) => s.isPlaying);
+ const inspectWorld = useEditorStore((s) => s.inspectWorld);
+ const setInspectWorld = useEditorStore((s) => s.setInspectWorld);
const initRef = useRef(false);
const dragIds = useRef<EntityId[] | null>(null);
@@ -314,8 +363,28 @@ export function Outliner() {
]
: [];
+ // While playing, a UE5-style world picker switches the outliner (+ Details)
+ // between the edit scene and the live running game.
+ const gameMode = inspectWorld === 'game';
+
return (
<div className="panel">
+ {isPlaying && (
+ <div className="world-pick">
+ <button type="button" className={gameMode ? '' : 'on'} onClick={() => setInspectWorld('editor')}>
+ Editor
+ </button>
+ <button type="button" className={gameMode ? 'on' : ''} onClick={() => setInspectWorld('game')}>
+ Game
+ </button>
+ </div>
+ )}
+ {gameMode ? (
+ <div className="pbody">
+ <GameTree />
+ </div>
+ ) : (
+ <>
<div className="phead">
<div className="search">
<Search size={13} strokeWidth={1.85} />
@@ -378,8 +447,10 @@ export function Outliner() {
))
)}
</div>
+ </>
+ )}
- {ctx && <ContextMenu x={ctx.x} y={ctx.y} items={ctxItems} onClose={() => setCtx(null)} />}
+ {ctx && !gameMode && <ContextMenu x={ctx.x} y={ctx.y} items={ctxItems} onClose={() => setCtx(null)} />}
</div>
);
}
diff --git a/desktop/src/store/editorStore.ts b/desktop/src/store/editorStore.ts
index 91e72a310..2a775e649 100644
--- a/desktop/src/store/editorStore.ts
+++ b/desktop/src/store/editorStore.ts
@@ -22,6 +22,10 @@ interface EditorState {
// Where Play runs: in the Viewport (UE5 PIE, default) or a separate Game tab.
playTarget: 'viewport' | 'window';
setPlayTarget: (t: 'viewport' | 'window') => void;
+ // Which world the Outliner/Details inspect: the edit scene or the live game
+ // (UE5 world picker). Auto-flips to 'game' on Play, 'editor' on Stop.
+ inspectWorld: 'editor' | 'game';
+ setInspectWorld: (w: 'editor' | 'game') => void;
// Launcher (project browser) vs editor shell. The editor opens on the
// launcher until a project is opened/created; `enterEditor` dismisses it.
@@ -77,6 +81,8 @@ export const useEditorStore = create<EditorState>((set) => ({
if (typeof localStorage !== 'undefined') localStorage.setItem('estella.playTarget', playTarget);
set({ playTarget });
},
+ inspectWorld: 'editor',
+ setInspectWorld: (inspectWorld) => set({ inspectWorld }),
showLauncher: true,
enterEditor: () => set({ showLauncher: false }),
diff --git a/desktop/src/theme/inspector.css b/desktop/src/theme/inspector.css
index f42be4164..c5d7005fc 100644
--- a/desktop/src/theme/inspector.css
+++ b/desktop/src/theme/inspector.css
@@ -141,3 +141,6 @@
.insp-empty .et { font-size: var(--fs-md); color: var(--text-dim); font-weight: 600; }
.insp-empty .es { font-size: var(--fs-sm); line-height: 1.5; }
.filter-empty { padding: 24px; text-align: center; color: var(--text-mute); font-size: var(--fs-sm); }
+
+/* Live "Game" inspector banner (UE5 PIE Details) — editing the running game. */
+.game-live { padding: 6px 12px; font-size: var(--fs-xs); font-weight: 500; color: var(--run-hi); background: rgba(70, 160, 74, 0.12); border-bottom: 1px solid var(--border); flex-shrink: 0; }
diff --git a/desktop/src/theme/outliner.css b/desktop/src/theme/outliner.css
index 5f1ee603f..4345c36c9 100644
--- a/desktop/src/theme/outliner.css
+++ b/desktop/src/theme/outliner.css
@@ -91,3 +91,9 @@
.row .rvis:hover { color: var(--text); }
.row.sel .rvis:hover { color: #fff; }
.row.hidden .rname { color: var(--text-mute); }
+
+/* World picker (UE5): switch the Outliner/Details between edit + live game. */
+.world-pick { display: flex; gap: 2px; padding: 6px 8px; border-bottom: 1px solid var(--border); flex-shrink: 0; }
+.world-pick button { flex: 1; height: 24px; font-size: var(--fs-xs); color: var(--text-mute); background: var(--srf-3); border-radius: var(--r-sm); transition: color var(--t-fast), background var(--t-fast); }
+.world-pick button.on { color: #fff; background: var(--acc); }
+.world-pick button:hover:not(.on) { color: var(--text); }