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(outliner): pluggable column registry (UE5 ISceneOutlinerColumn)

esengine53776cd0aab4
diff --git a/desktop/src/outliner/OutlinerController.ts b/desktop/src/outliner/OutlinerController.ts
index 045583833..05286be37 100644
--- a/desktop/src/outliner/OutlinerController.ts
+++ b/desktop/src/outliner/OutlinerController.ts
@@ -32,6 +32,8 @@ interface OutlinerState {
selectedFolder: string | null;
/** Sibling sort: `manual` (scene order) / `name` / `type`. View-only. */
sortMode: SortMode;
+ /** Hidden trailing-column ids (the column registry; a user preference). */
+ hiddenColumns: Set<string>;
/** Flip one row's expansion (pass an item key). */
toggleExpanded: (key: string) => void;
@@ -49,6 +51,8 @@ interface OutlinerState {
/** Select a folder (or clear with null). */
selectFolder: (path: string | null) => void;
setSortMode: (mode: SortMode) => void;
+ /** Show/hide a trailing column by id. */
+ toggleColumn: (id: string) => void;
/** Prune a removed entity's key (self-heal on the model's `entityRemoved`). */
dropId: (id: EntityId) => void;
@@ -64,6 +68,7 @@ export function createOutlinerStore(model: SceneModelImpl) {
cursor: null,
selectedFolder: null,
sortMode: 'manual',
+ hiddenColumns: new Set<string>(),
toggleExpanded: (key) =>
set((s) => {
@@ -113,6 +118,12 @@ export function createOutlinerStore(model: SceneModelImpl) {
setCursor: (cursor) => set({ cursor }),
selectFolder: (selectedFolder) => set({ selectedFolder }),
setSortMode: (sortMode) => set({ sortMode }),
+ toggleColumn: (id) =>
+ set((s) => {
+ const next = new Set(s.hiddenColumns);
+ next.has(id) ? next.delete(id) : next.add(id);
+ return { hiddenColumns: next };
+ }),
dropId: (id) =>
set((s) => {
diff --git a/desktop/src/outliner/OutlinerRow.tsx b/desktop/src/outliner/OutlinerRow.tsx
index d74192e53..401723597 100644
--- a/desktop/src/outliner/OutlinerRow.tsx
+++ b/desktop/src/outliner/OutlinerRow.tsx
@@ -5,16 +5,19 @@
*
* Purely presentational: selection / rename / drop / prefab state arrive as props
* (it does NOT subscribe to any store), so with virtualization only the ~window of
- * visible rows ever renders or re-renders. Renders both row kinds (entity / folder);
- * editor-only affordances (visibility toggle, rename, drag-drop) are gated on their
- * handlers — the PIE tree passes none and gets a click-to-select read-only row.
+ * visible rows ever renders or re-renders. The Name/tree part (twist + icon +
+ * name) is fixed; the trailing cells come from the {@link OutlinerColumn} registry
+ * — a column renders its cell, or an aligned spacer where it doesn't apply, so
+ * columns line up across entity + folder rows. The PIE tree passes a read-only
+ * column set and no edit handlers.
*/
import type React from 'react';
-import { ChevronRight, Eye, EyeOff, Lock, LockOpen, Folder, FolderOpen } from 'lucide-react';
+import { Fragment } from 'react';
+import { ChevronRight, Folder, FolderOpen } from 'lucide-react';
import { NodeIcon } from '@/components/icons';
import type { ReactNode } from 'react';
-import type { EntityId, NodeKind } from '@/types';
import type { OutlinerItem } from './OutlinerModel';
+import type { OutlinerColumn, OutlinerColumnContext } from './columns';
/** Wrap the first case-insensitive match of `hl` in the name with a highlight. */
function highlightName(name: string, hl?: string): ReactNode {
@@ -30,22 +33,9 @@ function highlightName(name: string, hl?: string): ReactNode {
);
}
-/** Entity kind → the label shown in the outliner's right-hand "Type" column. */
-const KIND_TYPE: Record<NodeKind, string> = {
- camera: 'Camera',
- sprite: 'Sprite',
- spine: 'Spine',
- physics: 'Physics',
- ui: 'UI',
- audio: 'Audio',
- group: 'Group',
- light: 'Light',
- empty: 'Entity',
-};
-
export interface OutlinerRowProps {
item: OutlinerItem;
- /** Entity selection highlight (folders never carry entity selection). */
+ /** Entity selection highlight (folders highlight via the folder selection). */
selected: boolean;
/** Keyboard-focus row (shows a focus ring; distinct from selection). */
cursored?: boolean;
@@ -58,13 +48,15 @@ export interface OutlinerRowProps {
prefab?: boolean;
/** When false, the twist is hidden + non-interactive (the always-expanded PIE tree). */
collapsible?: boolean;
+ /** Trailing columns to render after the name (the column registry). */
+ columns: OutlinerColumn[];
+ /** Per-cell callbacks/queries for the columns. */
+ columnCtx: OutlinerColumnContext;
onToggle: (key: string) => void;
onClick: (item: OutlinerItem, e: React.MouseEvent) => void;
onContextMenu?: (e: React.MouseEvent, item: OutlinerItem) => void;
onStartRename?: (item: OutlinerItem) => void;
onCommitRename?: (item: OutlinerItem, name: string) => void;
- onToggleVisible?: (id: EntityId, visible: boolean) => void;
- onToggleLock?: (id: EntityId, locked: boolean) => void;
draggable?: boolean;
onDragStart?: (item: OutlinerItem, e: React.DragEvent) => void;
onDragOver?: (item: OutlinerItem, e: React.DragEvent) => void;
@@ -73,7 +65,7 @@ export interface OutlinerRowProps {
}
export function OutlinerRow(props: OutlinerRowProps) {
- const { item, selected, renaming, dropPos, prefab } = props;
+ const { item, selected, renaming, dropPos, prefab, columns, columnCtx } = props;
const isFolder = item.kind === 'folder';
const { depth, hasChildren, expanded } = item;
@@ -81,21 +73,7 @@ export function OutlinerRow(props: OutlinerRowProps) {
const visible = item.kind === 'entity' ? item.node.visible : true;
const locked = item.kind === 'entity' ? item.node.locked : false;
- // Right column: entity type (prefab/kind + child count), or a folder's item count.
- let typeLabel: string;
- if (item.kind === 'folder') {
- typeLabel = item.count > 0 ? String(item.count) : '';
- } else {
- const childCount = item.node.children?.length ?? 0;
- const baseType = prefab ? 'Prefab' : (KIND_TYPE[item.node.kind] ?? 'Entity');
- typeLabel = childCount > 0 ? `${baseType} · ${childCount}` : baseType;
- }
-
const canRename = !!props.onCommitRename;
- const isEntity = item.kind === 'entity';
- const entityId = item.kind === 'entity' ? item.id : -1;
- const showVis = !!props.onToggleVisible && isEntity;
- const showLock = !!props.onToggleLock && isEntity;
const collapsible = props.collapsible !== false;
const showTwist = hasChildren && collapsible;
@@ -166,32 +144,12 @@ export function OutlinerRow(props: OutlinerRowProps) {
</span>
)}
- <span className="rtype">{typeLabel}</span>
-
- {showLock && (
- <span
- className="rlock"
- title={locked ? 'Unlock' : 'Lock'}
- onClick={(e) => {
- e.stopPropagation();
- props.onToggleLock!(entityId, !locked);
- }}
- >
- {locked ? <Lock size={12} strokeWidth={1.85} /> : <LockOpen size={12} strokeWidth={1.85} />}
- </span>
- )}
-
- {showVis && (
- <span
- className="rvis"
- title="Toggle visibility"
- onClick={(e) => {
- e.stopPropagation();
- props.onToggleVisible!(entityId, !visible);
- }}
- >
- {visible ? <Eye size={13} strokeWidth={1.85} /> : <EyeOff size={13} strokeWidth={1.85} />}
- </span>
+ {columns.map((col) =>
+ col.applies(item) ? (
+ <Fragment key={col.id}>{col.render(item, columnCtx)}</Fragment>
+ ) : (
+ <span key={col.id} className="rcol-spacer" style={{ width: col.width }} />
+ ),
)}
</div>
);
diff --git a/desktop/src/outliner/columns.tsx b/desktop/src/outliner/columns.tsx
new file mode 100644
index 000000000..77b68104a
--- /dev/null
+++ b/desktop/src/outliner/columns.tsx
@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file columns.tsx — the outliner's pluggable column registry (UE5
+ * ISceneOutlinerColumn). The Name/tree column is fixed (twist + icon +
+ * name, owned by OutlinerRow); every TRAILING column — Type, Lock,
+ * Visibility — is a descriptor here, so the row + header strip render from
+ * data and columns can be shown/hidden (and new ones added) without
+ * touching the row. A column renders a cell per item, or an aligned spacer
+ * where it doesn't apply (so the columns line up across entity/folder rows).
+ */
+import type { ReactNode } from 'react';
+import { Eye, EyeOff, Lock, LockOpen } from 'lucide-react';
+import type { EntityId, NodeKind } from '@/types';
+import type { OutlinerItem } from './OutlinerModel';
+
+/** Per-render callbacks/queries a column cell may need (entity-scoped). */
+export interface OutlinerColumnContext {
+ onToggleVisible?: (id: EntityId, visible: boolean) => void;
+ onToggleLock?: (id: EntityId, locked: boolean) => void;
+ /** Whether an entity is a prefab instance (drives the Type column's "Prefab"). */
+ isPrefab?: (id: EntityId) => boolean;
+}
+
+export interface OutlinerColumn {
+ id: string;
+ /** 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;
+ render: (item: OutlinerItem, ctx: OutlinerColumnContext) => ReactNode;
+}
+
+/** Entity kind → the label shown in the Type column. */
+const KIND_TYPE: Record<NodeKind, string> = {
+ camera: 'Camera',
+ sprite: 'Sprite',
+ spine: 'Spine',
+ physics: 'Physics',
+ ui: 'UI',
+ audio: 'Audio',
+ group: 'Group',
+ light: 'Light',
+ empty: 'Entity',
+};
+
+/** Type / count column — prefab instances read "Prefab", others by kind + child count. */
+export const TYPE_COLUMN: OutlinerColumn = {
+ id: 'type',
+ header: 'Type',
+ width: 78,
+ applies: () => true,
+ render: (item, ctx) => {
+ let label: string;
+ if (item.kind === 'folder') {
+ label = item.count > 0 ? String(item.count) : '';
+ } else {
+ const childCount = item.node.children?.length ?? 0;
+ const base = ctx.isPrefab?.(item.id) ? 'Prefab' : (KIND_TYPE[item.node.kind] ?? 'Entity');
+ label = childCount > 0 ? `${base} · ${childCount}` : base;
+ }
+ return <span className="rtype">{label}</span>;
+ },
+};
+
+/** Lock toggle (entity rows). */
+export const LOCK_COLUMN: OutlinerColumn = {
+ id: 'lock',
+ header: '',
+ width: 24,
+ applies: (item) => item.kind === 'entity',
+ render: (item, ctx) => {
+ if (item.kind !== 'entity') return null;
+ const locked = item.node.locked;
+ return (
+ <span
+ className="rlock"
+ title={locked ? 'Unlock' : 'Lock'}
+ onClick={(e) => {
+ e.stopPropagation();
+ ctx.onToggleLock?.(item.id, !locked);
+ }}
+ >
+ {locked ? <Lock size={12} strokeWidth={1.85} /> : <LockOpen size={12} strokeWidth={1.85} />}
+ </span>
+ );
+ },
+};
+
+/** Visibility (editor-hidden) toggle (entity rows). */
+export const VIS_COLUMN: OutlinerColumn = {
+ id: 'vis',
+ header: '',
+ width: 24,
+ applies: (item) => item.kind === 'entity',
+ render: (item, ctx) => {
+ if (item.kind !== 'entity') return null;
+ const visible = item.node.visible;
+ return (
+ <span
+ className="rvis"
+ title="Toggle visibility"
+ onClick={(e) => {
+ e.stopPropagation();
+ ctx.onToggleVisible?.(item.id, !visible);
+ }}
+ >
+ {visible ? <Eye size={13} strokeWidth={1.85} /> : <EyeOff size={13} strokeWidth={1.85} />}
+ </span>
+ );
+ },
+};
+
+/** The built-in column registry, in display order (after the Name/tree column). */
+export const OUTLINER_COLUMNS: OutlinerColumn[] = [TYPE_COLUMN, LOCK_COLUMN, VIS_COLUMN];
diff --git a/desktop/src/panels/Outliner.tsx b/desktop/src/panels/Outliner.tsx
index 9b31f7860..bfbc4322b 100644
--- a/desktop/src/panels/Outliner.tsx
+++ b/desktop/src/panels/Outliner.tsx
@@ -15,6 +15,7 @@ import { VirtualTree } from '@/components/VirtualTree';
import { buildOutlinerItems, collectExpandableKeys, entityKey, folderKey, parseQuery, type OutlinerItem } from '@/outliner/OutlinerModel';
import { useOutliner } from '@/outliner/OutlinerController';
import { OutlinerRow } from '@/outliner/OutlinerRow';
+import { OUTLINER_COLUMNS, TYPE_COLUMN, type OutlinerColumnContext } from '@/outliner/columns';
import { joinFolder, folderParent, folderName, normalizeFolder, isFolderUnder } from '@/outliner/folders';
import type { EntityId } from '@/types';
@@ -52,6 +53,8 @@ function GameTree() {
item={it}
selected={it.kind === 'entity' && selection === it.id}
collapsible={false}
+ columns={[TYPE_COLUMN]}
+ columnCtx={{}}
onToggle={() => {}}
onClick={(item) => {
if (item.kind === 'entity') PlayInspect.select(item.id);
@@ -72,6 +75,7 @@ export function Outliner() {
const cursor = useOutliner((s) => s.cursor);
const selectedFolder = useOutliner((s) => s.selectedFolder);
const sortMode = useOutliner((s) => s.sortMode);
+ const hiddenColumns = useOutliner((s) => s.hiddenColumns);
const selectedIds = useSelection((s) => s.selectedIds);
const selectedId = useSelection((s) => s.selectedId);
const selectedAsset = useSelection((s) => s.selectedAsset);
@@ -86,6 +90,7 @@ export function Outliner() {
const [drop, setDrop] = useState<{ key: string; pos: 'before' | 'on' | 'after' } | null>(null);
const [ctx, setCtx] = useState<{ x: number; y: number; item: OutlinerItem | null } | null>(null); // item null = empty-space menu
const [sortMenu, setSortMenu] = useState<{ x: number; y: number } | null>(null);
+ const [colsMenu, setColsMenu] = useState<{ x: number; y: number } | null>(null);
// Controlled scroll for reveal-on-select + keyboard nav (nonce re-fires same index).
const [scrollTo, setScrollTo] = useState<{ index: number; nonce: number }>({ index: -1, nonce: 0 });
const scrollNonce = useRef(0);
@@ -111,6 +116,15 @@ export function Outliner() {
);
const flatIds = useMemo(() => entityIds(items), [items]);
const highlight = useMemo(() => parseQuery(query).text, [query]);
+ const activeColumns = useMemo(() => OUTLINER_COLUMNS.filter((c) => !hiddenColumns.has(c.id)), [hiddenColumns]);
+ const columnCtx = useMemo<OutlinerColumnContext>(
+ () => ({
+ onToggleVisible: (id, visible) => SceneCommands.setEntityVisible(id, visible),
+ onToggleLock: (id, locked) => SceneCommands.setEntityLocked(id, locked),
+ isPrefab: (id) => SceneModel.prefabTag(id) != null,
+ }),
+ [],
+ );
// First time entities appear: expand groups + folders, select the first entity.
useEffect(() => {
@@ -508,14 +522,14 @@ export function Outliner() {
renaming={renaming === it.key}
dropPos={drop?.key === it.key ? drop.pos : undefined}
prefab={it.kind === 'entity' && SceneModel.prefabTag(it.id) != null}
+ columns={activeColumns}
+ columnCtx={columnCtx}
draggable
onToggle={toggleExpanded}
onClick={onRowClick}
onContextMenu={onContextMenu}
onStartRename={onStartRename}
onCommitRename={commitRename}
- onToggleVisible={(id, visible) => SceneCommands.setEntityVisible(id, visible)}
- onToggleLock={(id, locked) => SceneCommands.setEntityLocked(id, locked)}
onDragStart={onDragStartRow}
onDragOver={onDragOverRow}
onDrop={onDropRow}
@@ -572,10 +586,20 @@ export function Outliner() {
</button>
</div>
{sceneCount > 0 && (
- <div className="outliner-cols">
+ <div
+ className="outliner-cols"
+ title="Right-click to show/hide columns"
+ onContextMenu={(e) => {
+ e.preventDefault();
+ setColsMenu({ x: e.clientX, y: e.clientY });
+ }}
+ >
<span className="c-name">Name</span>
- <span className="c-type">Type</span>
- <span className="c-vis" />
+ {activeColumns.map((col) => (
+ <span key={col.id} className="c-col" style={{ width: col.width }}>
+ {col.header}
+ </span>
+ ))}
</div>
)}
{sceneCount === 0 ? (
@@ -623,6 +647,17 @@ export function Outliner() {
}))}
/>
)}
+ {colsMenu && !gameMode && (
+ <ContextMenu
+ x={colsMenu.x}
+ y={colsMenu.y}
+ onClose={() => setColsMenu(null)}
+ items={OUTLINER_COLUMNS.map((col) => ({
+ label: `${hiddenColumns.has(col.id) ? ' ' : '✓ '}${col.header || col.id}`,
+ onClick: () => useOutliner.getState().toggleColumn(col.id),
+ }))}
+ />
+ )}
</div>
);
}
diff --git a/desktop/src/theme/outliner.css b/desktop/src/theme/outliner.css
index e5f45781b..62cbd3657 100644
--- a/desktop/src/theme/outliner.css
+++ b/desktop/src/theme/outliner.css
@@ -43,9 +43,9 @@
background: var(--srf-2);
flex-shrink: 0;
}
+.outliner-cols { cursor: default; }
.outliner-cols .c-name { flex: 1; }
-.outliner-cols .c-type { width: 78px; flex-shrink: 0; }
-.outliner-cols .c-vis { width: 48px; text-align: center; flex-shrink: 0; } /* lock + eye */
+.outliner-cols .c-col { flex-shrink: 0; } /* registry columns; width set inline per column */
/* Rows */
.row {
@@ -96,6 +96,7 @@
font-size: var(--fs-sm);
outline: none;
}
+.row .rcol-spacer { flex-shrink: 0; } /* aligns columns where a row has no cell (e.g. folder lock/vis) */
.row .rtype { width: 78px; font-size: var(--fs-2xs); color: var(--text-mute); font-family: var(--mono); flex-shrink: 0; }
.row.sel .rtype { color: rgba(255, 255, 255, 0.72); }
.row .rvis, .row .rlock { width: 24px; display: grid; place-items: center; color: var(--text-mute); opacity: 0; transition: opacity var(--t-fast), color var(--t-fast); flex-shrink: 0; }
diff --git a/desktop/tests/outliner-columns.test.ts b/desktop/tests/outliner-columns.test.ts
new file mode 100644
index 000000000..f87ed42c2
--- /dev/null
+++ b/desktop/tests/outliner-columns.test.ts
@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Outliner column registry (REARCH_OUTLINER P5 — UE5 ISceneOutlinerColumn).
+ * The trailing columns are descriptors; `applies` gates per-item cells so
+ * entity-only columns (lock/vis) render an aligned spacer on folder rows.
+ */
+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';
+
+// One entity (root) + one folder, via the real builder, to test `applies`.
+function items() {
+ const data = { version: '1.0', name: 'c', entities: [{ id: 1, name: 'A', parent: null, children: [], components: [] }] } as unknown as SceneData;
+ return buildOutlinerItems(data, { expanded: new Set(), folders: ['F'], folderOf: () => '' });
+}
+
+describe('outliner column registry', () => {
+ it('the registry is Type, Lock, Visibility in order', () => {
+ expect(OUTLINER_COLUMNS.map((c) => c.id)).toEqual(['type', 'lock', 'vis']);
+ });
+
+ it('Type applies to every row; Lock/Vis only to entities', () => {
+ 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);
+ });
+});
diff --git a/desktop/tests/outliner-controller.test.ts b/desktop/tests/outliner-controller.test.ts
index 812b777a1..46ac9a99d 100644
--- a/desktop/tests/outliner-controller.test.ts
+++ b/desktop/tests/outliner-controller.test.ts
@@ -68,6 +68,14 @@ describe('OutlinerController', () => {
expect(store.getState().expanded.has(entityKey(2))).toBe(false);
});
+ it('toggleColumn hides/shows a column id', () => {
+ expect(store.getState().hiddenColumns.has('vis')).toBe(false);
+ store.getState().toggleColumn('vis');
+ expect(store.getState().hiddenColumns.has('vis')).toBe(true);
+ store.getState().toggleColumn('vis');
+ expect(store.getState().hiddenColumns.has('vis')).toBe(false);
+ });
+
it('selectFolder sets/clears the selected folder', () => {
store.getState().selectFolder('A/B');
expect(store.getState().selectedFolder).toBe('A/B');