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): UE5-PIE live game inspection in Outliner/Details (PD2/PD3)
esengineb563d4455b74
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsxindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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.cssindex 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.cssindex 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); }