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): the running world's outliner folds, filters, and hides

esengine4e1fcdb0d30e
diff --git a/desktop/src/engine/PlayInspect.ts b/desktop/src/engine/PlayInspect.ts
index d0aeeb8c9..0505b77eb 100644
--- a/desktop/src/engine/PlayInspect.ts
+++ b/desktop/src/engine/PlayInspect.ts
@@ -39,9 +39,15 @@ const TREE_GAP_MS = 150;
const DETAIL_GAP_MS = 33;
/** A cheap structural signature of the shallow tree (ids / parent / name / component
- * types) — drives keeping the tree reference stable when only values changed. */
+ * types) — drives keeping the tree reference stable when only values changed.
+ *
+ * `hidden` rides along despite being a value: it is the one value the TREE shows,
+ * so leaving it out would hold the old reference and the eye you just clicked
+ * would not change. */
function treeSig(t: SceneData): string {
- return t.entities.map((e) => `${e.id},${e.parent ?? ''},${e.name},${e.components.map((c) => c.type).join('+')}`).join('|');
+ return t.entities
+ .map((e) => `${e.id},${e.parent ?? ''},${e.name},${(e as { hidden?: boolean }).hidden ? 'h' : ''},${e.components.map((c) => c.type).join('+')}`)
+ .join('|');
}
class PlayInspectImpl {
@@ -104,6 +110,13 @@ class PlayInspectImpl {
void this.poll(false);
}
+ /** Show/hide a running entity. The eye is a TREE fact, so this resamples the
+ * tree — a detail-only poll would leave the row it was clicked on unchanged. */
+ setVisible(id: EntityId, visible: boolean): void {
+ PlayRealm.setVisible(id, visible);
+ void this.poll(true);
+ }
+
// Start the loop if it should run and isn't already (called on start + on the
// first subscriber appearing while playing).
private arm(): void {
diff --git a/desktop/src/engine/PlayRealm.ts b/desktop/src/engine/PlayRealm.ts
index 5405d6bdb..acc5dcba0 100644
--- a/desktop/src/engine/PlayRealm.ts
+++ b/desktop/src/engine/PlayRealm.ts
@@ -363,6 +363,11 @@ export class PlayRealmInstance {
this.post({ type: 'estella:play:setField', entityId, comp, key, value });
}
+ /** Show/hide a running entity (the Outliner's eye; reverts on Stop). */
+ setVisible(entityId: number, visible: boolean): void {
+ this.post({ type: 'estella:play:setVisible', entityId, visible });
+ }
+
private post(message: PlayOutbound, transfer?: Transferable[]): void {
this.iframe?.contentWindow?.postMessage(message, '*', transfer);
}
diff --git a/desktop/src/engine/playProtocol.ts b/desktop/src/engine/playProtocol.ts
index 9bfd1e1f0..9e4bb9458 100644
--- a/desktop/src/engine/playProtocol.ts
+++ b/desktop/src/engine/playProtocol.ts
@@ -18,7 +18,7 @@ import type { SceneData, PhysicsPluginConfig, AudioProjectConfig, ThemeOverrides
* compares it against its own and refuses a mismatch (P1) rather than failing
* obscurely on a shape it doesn't understand. Bump on any incompatible message change.
*/
-export const PLAY_PROTOCOL_VERSION = 2;
+export const PLAY_PROTOCOL_VERSION = 3;
/**
* The handshake check: `null` if the realm's reported protocol version is compatible
@@ -97,12 +97,26 @@ export interface PlayPayload {
/** A live inspect snapshot: a shallow entity tree (Outliner) + the selected entity's
* full data (Details). The reply payload of a `query { kind: 'snapshot' }`.
* `tree` is null for a detail-only sample (`withTree: false`) — the editor polls
- * the selected entity faster than the O(entities) tree. */
+ * the selected entity faster than the O(entities) tree.
+ *
+ * Each tree entity carries {@link LiveVisibility} alongside the fields SceneData
+ * declares, so the running world's Outliner reads the same `hidden` bit an
+ * edited scene does and the shared tree builder needs no live-specific branch. */
export interface PlaySnapshot {
tree: SceneData | null;
selected: SceneData['entities'][number] | null;
}
+/** The visibility half of a live tree entity — what the Outliner's eye reads.
+ * `hideable` is a separate bit from `hidden` because they answer different
+ * questions: a bare transform is not hidden AND cannot be hidden (its children
+ * draw, it doesn't), and a row that cannot act shows no eye rather than a
+ * control that quietly does nothing. */
+export interface LiveVisibility {
+ hidden?: boolean;
+ hideable?: boolean;
+}
+
export type PlayQueryKind = 'snapshot' | 'subsystems' | 'stats' | 'step';
/** What `query { kind: 'step' }` answers with: the clock AFTER the advance, so a
@@ -148,7 +162,12 @@ export type PlayOutbound =
// `step` only: how far to advance, and with what fixed delta.
frames?: number; dt?: number;
}
- | { type: 'estella:play:setField'; entityId: number; comp: string; key: string; value: unknown };
+ | { type: 'estella:play:setField'; entityId: number; comp: string; key: string; value: unknown }
+ // Show/hide a live entity (the Outliner's eye). An operation rather than a
+ // field write: WHICH components carry visibility is the engine's knowledge, and
+ // the realm answers it with the SDK's own setEntityVisible so the editor never
+ // has to keep a second list of what counts as a renderer.
+ | { type: 'estella:play:setVisible'; entityId: number; visible: boolean };
/** realm → editor. Discriminated by `type`. */
export type PlayInbound =
diff --git a/desktop/src/i18n/messages/outliner.ts b/desktop/src/i18n/messages/outliner.ts
index 976cda931..eed961932 100644
--- a/desktop/src/i18n/messages/outliner.ts
+++ b/desktop/src/i18n/messages/outliner.ts
@@ -31,6 +31,7 @@ export const outlinerMessages = defineMessages({
'out.colVis': { en: 'vis', zh: '可见性' },
'out.tree': { en: 'Scene hierarchy', zh: '场景层级' },
+ 'out.treeGame': { en: 'Running world hierarchy', zh: '运行中世界的层级' },
// — Empty states —
'out.emptyScene': { en: 'No entities in scene.', zh: '场景中没有实体。' },
'out.waitingEngine': { en: 'Waiting for engine…', zh: '正在等待引擎…' },
diff --git a/desktop/src/outliner/OutlinerController.ts b/desktop/src/outliner/OutlinerController.ts
index 5d871d77f..8ff76aead 100644
--- a/desktop/src/outliner/OutlinerController.ts
+++ b/desktop/src/outliner/OutlinerController.ts
@@ -3,16 +3,21 @@
/**
* @file OutlinerController.ts — the outliner's headless view-state.
*
- * Owns the editor-tree state the SceneModel doesn't: which rows are expanded and
- * the search query. Kept OUT of the React panel so the tree is testable headless
- * and (later) drivable by EditorControlSurface / the editor MCP — the panel is a
- * thin renderer over this + {@link buildOutlinerItems}.
+ * Owns the tree state the source doesn't: which rows are expanded and the search
+ * query. Kept OUT of the React panel so the tree is testable headless and (later)
+ * drivable by EditorControlSurface / the editor MCP — the panel is a thin
+ * renderer over this + {@link buildOutlinerItems}.
*
* Expansion is keyed by stable string ITEM KEYS (`e<id>` for entities, `f:<path>`
- * for folders), so one set covers both row kinds. Model-anchored self-healing
- * (mirrors selectionStore): expansion is pruned when an entity is removed
- * (`entityRemoved`) and the whole view resets on a scene swap (`reset`). One per
- * EditorSession; the default instance binds the app's SceneModel.
+ * for folders), so one set covers both row kinds. One store per tree: the edited
+ * scene has one, the running world another — their ids come from different
+ * spaces (source ids vs realm runtime ids) and must never share an expansion set.
+ *
+ * Self-healing follows the shape of the source. A model announces a removal, so
+ * the scene store prunes on `entityRemoved` and resets on `reset`; a snapshot
+ * source announces nothing, so the live store prunes with {@link retainIds} on
+ * each arriving tree — the running world recycles entity ids, and a recycled id
+ * would otherwise inherit a dead entity's expansion.
*/
import { create } from 'zustand';
import { SceneModel, SceneModelImpl } from '@/engine/SceneModel';
@@ -20,6 +25,15 @@ import type { EntityId } from '@/types';
import { entityKey, folderKey, type SortMode } from './OutlinerModel';
import { folderPrefixes, normalizeFolder, rebaseFolder } from './folders';
+/** What the controller needs from the tree it is a view of. Both members serve
+ * `revealEntity` alone — everything else here is pure view-state. */
+export interface OutlinerSource {
+ /** An entity's transform parent, or null at a root. */
+ parentOf(id: EntityId): EntityId | null;
+ /** A root's folder path; `''` for a source without folders (the live world). */
+ folderOf(id: EntityId): string;
+}
+
interface OutlinerState {
/** Expanded item keys (`e<id>` / `f:<path>`). */
expanded: Set<string>;
@@ -56,12 +70,14 @@ interface OutlinerState {
/** Prune a removed entity's key (self-heal on the model's `entityRemoved`). */
dropId: (id: EntityId) => void;
+ /** Keep only these entities' keys — the snapshot-source self-heal. */
+ retainIds: (ids: ReadonlySet<EntityId>) => void;
/** Reset the view on a scene swap (the model's `reset`). */
reset: () => void;
}
-/** Build an outliner controller bound to a model. One per EditorSession. */
-export function createOutlinerStore(model: SceneModelImpl) {
+/** Build an outliner controller over a source. One per tree. */
+export function createOutlinerStore(source: OutlinerSource) {
const useStore = create<OutlinerState>((set) => ({
expanded: new Set<string>(),
query: '',
@@ -93,12 +109,12 @@ export function createOutlinerStore(model: SceneModelImpl) {
const seen = new Set<number>();
while (cur != null && !seen.has(cur)) {
seen.add(cur);
- const parent: number | null = model.entityBySource(cur)?.parent ?? null;
+ const parent: number | null = source.parentOf(cur);
if (parent != null) next.add(entityKey(parent));
else root = cur;
cur = parent;
}
- for (const pre of folderPrefixes(normalizeFolder(model.folderOf(root)))) next.add(folderKey(pre));
+ for (const pre of folderPrefixes(normalizeFolder(source.folderOf(root)))) next.add(folderKey(pre));
return { expanded: next };
}),
rebaseFolderKeys: (oldPath, newPath) =>
@@ -134,16 +150,34 @@ export function createOutlinerStore(model: SceneModelImpl) {
next.delete(k);
return { expanded: next, cursor };
}),
+ retainIds: (ids) =>
+ set((s) => {
+ const stale = [...s.expanded].filter((k) => k.startsWith('e') && !ids.has(Number(k.slice(1))));
+ const cursor = s.cursor && stale.includes(s.cursor) ? null : s.cursor;
+ if (stale.length === 0) return cursor === s.cursor ? s : { cursor };
+ const next = new Set(s.expanded);
+ for (const k of stale) next.delete(k);
+ return { expanded: next, cursor };
+ }),
reset: () => set({ expanded: new Set(), query: '', cursor: null, selectedFolder: null }),
}));
+ return useStore;
+}
+
+/** A controller over an edited scene: the model is both the source and, because
+ * it announces its own removals, the self-heal. One per EditorSession. */
+export function createSceneOutlinerStore(model: SceneModelImpl) {
+ const store = createOutlinerStore({
+ parentOf: (id) => model.entityBySource(id)?.parent ?? null,
+ folderOf: (id) => model.folderOf(id),
+ });
model.subscribe((ev) => {
- if (ev.kind === 'entityRemoved') useStore.getState().dropId(ev.sourceId);
- else if (ev.kind === 'reset') useStore.getState().reset();
+ if (ev.kind === 'entityRemoved') store.getState().dropId(ev.sourceId);
+ else if (ev.kind === 'reset') store.getState().reset();
});
-
- return useStore;
+ return store;
}
/** The app's default-session outliner controller. Other sessions build their own. */
-export const useOutliner = createOutlinerStore(SceneModel);
+export const useOutliner = createSceneOutlinerStore(SceneModel);
diff --git a/desktop/src/outliner/OutlinerRow.tsx b/desktop/src/outliner/OutlinerRow.tsx
index e1cdd0274..97115276d 100644
--- a/desktop/src/outliner/OutlinerRow.tsx
+++ b/desktop/src/outliner/OutlinerRow.tsx
@@ -168,7 +168,7 @@ function OutlinerRowInner(props: OutlinerRowProps) {
)}
{columns.map((col) =>
- col.applies(item) ? (
+ col.applies(item, columnCtx) ? (
<Fragment key={col.id}>{col.render(item, columnCtx)}</Fragment>
) : (
<span key={col.id} className="rcol-spacer" data-col={col.id} style={{ width: col.width }} />
diff --git a/desktop/src/outliner/columns.tsx b/desktop/src/outliner/columns.tsx
index def36ab63..b5ef8b120 100644
--- a/desktop/src/outliner/columns.tsx
+++ b/desktop/src/outliner/columns.tsx
@@ -21,6 +21,11 @@ export interface OutlinerColumnContext {
onToggleLock?: (id: EntityId, locked: boolean) => void;
/** Whether an entity is a prefab instance (drives the Type column's "Prefab"). */
isPrefab?: (id: EntityId) => boolean;
+ /** Whether hiding this entity would do anything. Absent ⇒ always (an edited
+ * scene hides any entity, the flag being the editor's own). The running world
+ * answers false for a bare transform — its children draw, it doesn't — and
+ * that row gets no eye rather than one that quietly does nothing. */
+ canToggleVisible?: (id: EntityId) => boolean;
}
export interface OutlinerColumn {
@@ -28,8 +33,10 @@ export interface OutlinerColumn {
/** Header label ('' = icon-only column, no header text). */
header: string;
width: number;
- /** Whether this column shows a cell for `item` (else an aligned spacer). */
- applies: (item: OutlinerItem) => boolean;
+ /** Whether this column shows a cell for `item` (else an aligned spacer). Takes
+ * the same context `render` does, so "no cell here" can depend on the tree —
+ * the running world has rows with nothing to hide. */
+ applies: (item: OutlinerItem, ctx: OutlinerColumnContext) => boolean;
render: (item: OutlinerItem, ctx: OutlinerColumnContext) => ReactNode;
}
@@ -94,7 +101,7 @@ export const VIS_COLUMN: OutlinerColumn = {
id: 'vis',
header: '',
width: 24,
- applies: (item) => item.kind === 'entity',
+ applies: (item, ctx) => item.kind === 'entity' && (ctx.canToggleVisible?.(item.id) ?? true),
render: (item, ctx) => {
if (item.kind !== 'entity') return null;
const visible = item.node.visible;
diff --git a/desktop/src/outliner/playOutliner.ts b/desktop/src/outliner/playOutliner.ts
new file mode 100644
index 000000000..750081be9
--- /dev/null
+++ b/desktop/src/outliner/playOutliner.ts
@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file playOutliner.ts — the running world's tree view-state.
+ *
+ * The second {@link createOutlinerStore} instance, over the live realm snapshot
+ * instead of the edited scene. It is a separate store rather than a mode of the
+ * editor one because the two speak different id spaces — source ids and realm
+ * runtime ids — and one expansion set across both would open rows at random.
+ *
+ * The live world has no folders (nothing organizes a running game but its own
+ * hierarchy), so `folderOf` is always the root.
+ */
+import { PlayInspect } from '@/engine/PlayInspect';
+import type { EntityId } from '@/types';
+import { createOutlinerStore } from './OutlinerController';
+import { ROOT_FOLDER } from './folders';
+
+export const usePlayOutliner = createOutlinerStore({
+ parentOf: (id) => PlayInspect.getTree()?.entities.find((e) => e.id === id)?.parent ?? null,
+ folderOf: () => ROOT_FOLDER,
+});
+
+/**
+ * Drop expansion for entities the running world no longer has.
+ *
+ * Not housekeeping: the ECS recycles entity ids, so without this a bullet
+ * spawned into a despawned parent's id arrives already expanded — and rows open
+ * on their own while you are reading somewhere else in the tree.
+ */
+export function pruneToLiveEntities(ids: ReadonlySet<EntityId>): void {
+ usePlayOutliner.getState().retainIds(ids);
+}
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 45b85d0b2..9e8e9d2b6 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -3735,9 +3735,13 @@ function SourceInspector({ source }: { source: InspectSource }) {
}
// Dispatcher: the live game inspector during PIE, the edit inspector otherwise.
+// Both halves of "during PIE" matter — Stop takes the Outliner's world picker
+// away, so a choice that outlived the realm would strand this panel on a world
+// that no longer exists, with nothing on screen able to switch it back.
export function Details() {
+ const isPlaying = useEditorStore((s) => s.isPlaying);
const inspectWorld = useEditorStore((s) => s.inspectWorld);
- return inspectWorld === 'game' ? <GameDetails /> : <EditorDetails />;
+ return isPlaying && inspectWorld === 'game' ? <GameDetails /> : <EditorDetails />;
}
function EditorDetails() {
diff --git a/desktop/src/panels/Outliner.tsx b/desktop/src/panels/Outliner.tsx
index c7195dc62..e0f68bc81 100644
--- a/desktop/src/panels/Outliner.tsx
+++ b/desktop/src/panels/Outliner.tsx
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
-import { Search, Plus, FolderPlus, ArrowDownUp, Boxes } from 'lucide-react';
+import { Search, Plus, FolderPlus, ArrowDownUp, Boxes, ChevronsDownUp, ChevronsUpDown } from 'lucide-react';
import { SearchField } from '@/components/SearchField';
import { EmptyState } from '@/components/EmptyState';
import { useEditorStore } from '@/store/editorStore';
@@ -21,9 +21,11 @@ import { buildOutlinerItems, collectExpandableKeys, entityKey, folderKey, parseQ
import { useOutliner } from '@/outliner/OutlinerController';
import { OutlinerRow } from '@/outliner/OutlinerRow';
import { useAgent, touchedEntities } from '@/store/AgentStore';
-import { OUTLINER_COLUMNS, TYPE_COLUMN, type OutlinerColumnContext } from '@/outliner/columns';
+import { usePlayOutliner, pruneToLiveEntities } from '@/outliner/playOutliner';
+import { OUTLINER_COLUMNS, TYPE_COLUMN, VIS_COLUMN, type OutlinerColumnContext } from '@/outliner/columns';
import { joinFolder, folderParent, folderName, normalizeFolder, isFolderUnder } from '@/outliner/folders';
import type { EntityId } from '@/types';
+import type { LiveVisibility } from '@/engine/playProtocol';
import { createFromSource, type EntitySource } from '@/engine/entitySources';
import { CreatePopover } from '@/components/CreatePopover';
import { Segmented } from '@/components/Segmented';
@@ -34,9 +36,7 @@ import { useAgentFresh } from '@/outliner/agentFresh';
const ROW_H = 24;
const NO_EXPANSION: ReadonlySet<string> = new Set();
// Stable props so the memoized game-tree rows don't all re-render on selection.
-const GAME_COLUMNS = [TYPE_COLUMN];
-const EMPTY_COL_CTX: OutlinerColumnContext = {};
-const NOOP = () => {};
+const GAME_COLUMNS = [TYPE_COLUMN, VIS_COLUMN];
const gameOnClick = (item: OutlinerItem) => {
if (item.kind === 'entity') PlayInspect.select(item.id);
};
@@ -52,41 +52,79 @@ const COL_ID_LABEL: Record<string, string> = { lock: t('out.colLock'), vis: t('o
const entityIds = (items: OutlinerItem[]): EntityId[] =>
items.filter((i): i is Extract<OutlinerItem, { kind: 'entity' }> => i.kind === 'entity').map((i) => i.id);
-// One row of the live "Game" tree: a read-only, always-expanded
-// view of the running realm, sharing the editor's virtualization. No folders.
+// The live "Game" tree: the running realm, over the same builder, row and
+// virtualization as the editor tree. No folders (nothing organizes a running
+// game but its own hierarchy) and no authoring — what it does offer is the two
+// things you need to READ a world of a few thousand entities: rows that fold,
+// and an eye that turns one off to find out what it was.
function GameTree() {
const snapshot = useSyncExternalStore(PlayInspect.subscribe, PlayInspect.getTree);
const selection = useSyncExternalStore(PlayInspect.subscribe, PlayInspect.getSelection);
- const items = useMemo(() => buildOutlinerItems(snapshot, { expanded: NO_EXPANSION, expandAll: true }), [snapshot]);
+ const expanded = usePlayOutliner((s) => s.expanded);
+ const query = usePlayOutliner((s) => s.query);
+ const setQuery = usePlayOutliner((s) => s.setQuery);
+ const toggleExpanded = usePlayOutliner((s) => s.toggleExpanded);
+
+ // Keyed on the snapshot REFERENCE, which PlayInspect holds stable unless the
+ // tree actually differs — so a steady game rebuilds neither set per sample.
+ const liveIds = useMemo(() => new Set((snapshot?.entities ?? []).map((e) => e.id)), [snapshot]);
+ const hideable = useMemo(
+ () => new Set((snapshot?.entities ?? []).filter((e) => (e as LiveVisibility).hideable).map((e) => e.id)),
+ [snapshot],
+ );
+ useEffect(() => pruneToLiveEntities(liveIds), [liveIds]);
+
+ const items = useMemo(() => buildOutlinerItems(snapshot, { expanded, query }), [snapshot, expanded, query]);
+ const highlight = useMemo(() => parseQuery(query).text, [query]);
+ const columnCtx = useMemo<OutlinerColumnContext>(
+ () => ({
+ onToggleVisible: (id, visible) => PlayInspect.setVisible(id, visible),
+ canToggleVisible: (id) => hideable.has(id),
+ }),
+ [hideable],
+ );
+ const expandAll = () => usePlayOutliner.getState().setExpanded(collectExpandableKeys(snapshot));
- if (items.length === 0) {
- return (
- <div className="pbody">
- <div className="empty">
- <Search size={22} strokeWidth={1.4} />
- <p>{t('out.waitingGame')}</p>
- </div>
- </div>
- );
- }
return (
- <VirtualTree
- className="pbody"
- items={items}
- rowHeight={ROW_H}
- getKey={(it) => it.key}
- renderRow={(it) => (
- <OutlinerRow
- item={it}
- selected={it.kind === 'entity' && selection === it.id}
- collapsible={false}
- columns={GAME_COLUMNS}
- columnCtx={EMPTY_COL_CTX}
- onToggle={NOOP}
- onClick={gameOnClick}
+ <>
+ <div className="phead">
+ <SearchField placeholder={t('out.searchPlaceholder')} value={query} onChange={setQuery} />
+ <IconButton title={t('out.expandAll')} onClick={expandAll}>
+ <ChevronsUpDown size={14} strokeWidth={2} />
+ </IconButton>
+ <IconButton title={t('out.collapseAll')} onClick={() => usePlayOutliner.getState().setExpanded([])}>
+ <ChevronsDownUp size={14} strokeWidth={2} />
+ </IconButton>
+ </div>
+ {items.length === 0 ? (
+ <div className="pbody">
+ <EmptyState
+ icon={Search}
+ title={liveIds.size === 0 ? t('out.waitingGame') : t('out.noMatch', { query })}
+ />
+ </div>
+ ) : (
+ <VirtualTree
+ className="pbody"
+ role="tree"
+ aria-label={t('out.treeGame')}
+ items={items}
+ rowHeight={ROW_H}
+ getKey={(it) => it.key}
+ renderRow={(it) => (
+ <OutlinerRow
+ item={it}
+ selected={it.kind === 'entity' && selection === it.id}
+ highlight={highlight}
+ columns={GAME_COLUMNS}
+ columnCtx={columnCtx}
+ onToggle={toggleExpanded}
+ onClick={gameOnClick}
+ />
+ )}
/>
)}
- />
+ </>
);
}
@@ -640,9 +678,11 @@ export function Outliner() {
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [ctx]);
- // While playing, a world picker switches the outliner (+ Details)
- // between the edit scene and the live running game.
- const gameMode = inspectWorld === 'game';
+ // While playing, a world picker switches the outliner (+ Details) between the
+ // edit scene and the live running game. Gated on `isPlaying` as well as the
+ // choice: Stop takes the picker away, and a mode you can no longer leave would
+ // strand the panel on a world that no longer exists.
+ const gameMode = isPlaying && inspectWorld === 'game';
// Stable handlers (latest-ref) so the memoized rows skip on a selection change.
const rowFns = {
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index 3fe295bc8..405e103cd 100644
--- a/desktop/src/playHost.ts
+++ b/desktop/src/playHost.ts
@@ -14,10 +14,10 @@
* Everything is same-origin estella:// (host, sdk, bundle, wasm, assets),
* sidestepping the custom-scheme cross-fetch ban.
*/
-import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations, Net, MessagePortTransport, Assets, Ads, createMockAdProvider, Leaderboard, createLocalLeaderboard, registerPackagedSideModules, Input, inputEventCallbacks } from 'esengine';
+import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations, Net, MessagePortTransport, Assets, Ads, createMockAdProvider, Leaderboard, createLocalLeaderboard, registerPackagedSideModules, Input, inputEventCallbacks, isEntityVisible, setEntityVisible, hasVisibility } from 'esengine';
import type { App, ESEngineModule, SceneData } from 'esengine';
import { PLAY_PROTOCOL_VERSION } from './engine/playProtocol';
-import type { PlayOutbound, PlayInbound } from './engine/playProtocol';
+import type { PlayOutbound, PlayInbound, LiveVisibility } from './engine/playProtocol';
import { translateAssetHandles, projectRelative } from './engine/liveAssetRefs';
type LiveEntity = SceneData['entities'][number];
@@ -84,6 +84,14 @@ function liveSnapshot(world: App['world'], selectedId: number | null, withTree:
const nameOf = (e: number): string =>
(nameDef ? (world.tryGet(e as never, nameDef) as { value?: string } | null)?.value : undefined) ?? `Entity_${e}`;
+ // The one exception to the types-only rule: the Outliner's eye needs a value,
+ // and both halves are asked of the SDK, so the editor never keeps its own list
+ // of what counts as a renderer.
+ const visibilityOf = (e: number): LiveVisibility =>
+ hasVisibility(world, e as never)
+ ? { hideable: true, hidden: !isEntityVisible(world, e as never) }
+ : {};
+
// The tree walk is O(entities) — a detail-only sample (withTree false) skips it
// so the editor can poll the selected entity faster than the tree.
const tree = withTree
@@ -93,7 +101,7 @@ function liveSnapshot(world: App['world'], selectedId: number | null, withTree:
entities: all.map((e): LiveEntity => {
const id = e as never as number;
// Component TYPES only — no data decode (the Outliner reads kind from types).
- return { id, name: nameOf(id), parent: parentOf.get(id) ?? null, children: childrenOf.get(id) ?? [], components: inspectableTypes(world, id).map((type) => ({ type, data: {} })) } as LiveEntity;
+ return { id, name: nameOf(id), parent: parentOf.get(id) ?? null, children: childrenOf.get(id) ?? [], components: inspectableTypes(world, id).map((type) => ({ type, data: {} })), ...visibilityOf(id) } as LiveEntity;
}),
} as unknown as SceneData)
: null;
@@ -782,6 +790,11 @@ window.addEventListener('message', (e: MessageEvent) => {
case 'estella:play:setField':
if (data.entityId != null && data.comp && data.key) setField(data.entityId, data.comp, data.key, data.value);
break;
+ case 'estella:play:setVisible':
+ if (app && data.entityId != null && app.world.valid(data.entityId as never)) {
+ setEntityVisible(app.world, data.entityId as never, data.visible);
+ }
+ break;
}
});
diff --git a/desktop/tests/outliner-columns.test.ts b/desktop/tests/outliner-columns.test.ts
index 5c6f4981a..aa529b012 100644
--- a/desktop/tests/outliner-columns.test.ts
+++ b/desktop/tests/outliner-columns.test.ts
@@ -8,7 +8,9 @@
import { describe, it, expect } from 'vitest';
import type { SceneData } from 'esengine';
import { buildOutlinerItems } from '@/outliner/OutlinerModel';
-import { OUTLINER_COLUMNS, TYPE_COLUMN, LOCK_COLUMN, VIS_COLUMN } from '@/outliner/columns';
+import { OUTLINER_COLUMNS, TYPE_COLUMN, LOCK_COLUMN, VIS_COLUMN, type OutlinerColumnContext } from '@/outliner/columns';
+
+const NO_CTX: OutlinerColumnContext = {};
// One entity (root) + one folder, via the real builder, to test `applies`.
function items() {
@@ -25,11 +27,19 @@ describe('outliner column registry', () => {
const all = items();
const entity = all.find((i) => i.kind === 'entity')!;
const folder = all.find((i) => i.kind === 'folder')!;
- expect(TYPE_COLUMN.applies(entity)).toBe(true);
- expect(TYPE_COLUMN.applies(folder)).toBe(true);
- expect(LOCK_COLUMN.applies(entity)).toBe(true);
- expect(LOCK_COLUMN.applies(folder)).toBe(false); // → an aligned spacer on folder rows
- expect(VIS_COLUMN.applies(entity)).toBe(true);
- expect(VIS_COLUMN.applies(folder)).toBe(false);
+ expect(TYPE_COLUMN.applies(entity, NO_CTX)).toBe(true);
+ expect(TYPE_COLUMN.applies(folder, NO_CTX)).toBe(true);
+ expect(LOCK_COLUMN.applies(entity, NO_CTX)).toBe(true);
+ expect(LOCK_COLUMN.applies(folder, NO_CTX)).toBe(false); // → an aligned spacer on folder rows
+ expect(VIS_COLUMN.applies(entity, NO_CTX)).toBe(true);
+ expect(VIS_COLUMN.applies(folder, NO_CTX)).toBe(false);
+ });
+
+ // The running world has rows with nothing of their own to draw (a bare
+ // transform). They get a spacer, not an eye that would quietly do nothing.
+ it('Visibility yields to the context when the tree says an entity cannot be hidden', () => {
+ const entity = items().find((i) => i.kind === 'entity')!;
+ expect(VIS_COLUMN.applies(entity, { canToggleVisible: () => false })).toBe(false);
+ expect(VIS_COLUMN.applies(entity, { canToggleVisible: () => true })).toBe(true);
});
});
diff --git a/desktop/tests/outliner-controller.test.ts b/desktop/tests/outliner-controller.test.ts
index cdbda9110..1108d3d8c 100644
--- a/desktop/tests/outliner-controller.test.ts
+++ b/desktop/tests/outliner-controller.test.ts
@@ -8,7 +8,7 @@
import { describe, it, expect, beforeEach } from 'vitest';
import type { SceneData } from 'esengine';
import { EditorSession } from '@/engine/EditorSession';
-import { createOutlinerStore } from '@/outliner/OutlinerController';
+import { createSceneOutlinerStore } from '@/outliner/OutlinerController';
import { entityKey, folderKey } from '@/outliner/OutlinerModel';
const ent = (id: number, parent: number | null, children: number[]) => ({ id, name: `E${id}`, parent, children, components: [] as unknown[] });
@@ -18,12 +18,12 @@ const scene = (): SceneData =>
describe('OutlinerController', () => {
let S: EditorSession;
- let store: ReturnType<typeof createOutlinerStore>;
+ let store: ReturnType<typeof createSceneOutlinerStore>;
beforeEach(() => {
S = EditorSession.create();
S.model.adopt(scene(), new Map());
S.model.setFolder(1, 'A/B');
- store = createOutlinerStore(S.model);
+ store = createSceneOutlinerStore(S.model);
});
it('revealEntity expands transform ancestors + the root folder path', () => {
@@ -83,6 +83,27 @@ describe('OutlinerController', () => {
expect(store.getState().selectedFolder).toBeNull();
});
+ // The snapshot-source self-heal. A running world announces nothing when an
+ // entity dies, and its ids are RECYCLED — so a key kept past its entity would
+ // open a row belonging to something else entirely.
+ it('retainIds drops expansion + cursor for entities the source no longer has', () => {
+ store.getState().setExpanded([entityKey(1), entityKey(2), folderKey('A')]);
+ store.getState().setCursor(entityKey(2));
+ store.getState().retainIds(new Set([1]));
+ const exp = store.getState().expanded;
+ expect(exp.has(entityKey(1))).toBe(true);
+ expect(exp.has(entityKey(2))).toBe(false);
+ expect(exp.has(folderKey('A'))).toBe(true); // folder keys are not entity keys
+ expect(store.getState().cursor).toBeNull();
+ });
+
+ it('retainIds keeps the same expansion object when nothing went away', () => {
+ store.getState().setExpanded([entityKey(1)]);
+ const before = store.getState().expanded;
+ store.getState().retainIds(new Set([1, 2, 3]));
+ expect(store.getState().expanded).toBe(before); // no re-render on a steady frame
+ });
+
it('reset clears expansion + query + cursor + selected folder', () => {
store.getState().setExpanded([entityKey(1)]);
store.getState().setQuery('x');