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): progressive disclosure for the Details inspector

yhh3f1068f5469c
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 22f6cd1d0..6cedb7b08 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -53,6 +53,7 @@ import { useSelection } from '@/store/selectionStore';
import { usePrefabConflicts } from '@/store/prefabConflicts';
import { useEditorStore } from '@/store/editorStore';
import { useControllerStore } from '@/store/controllerStore';
+import { useInspectorCollapse, isSectionCollapsed } from '@/store/inspectorCollapse';
import { isGeared, controllerCurrentPage, readModelField, readGearBindings, resolveControllers } from '@/controller/controllerModel';
import { useOutliner } from '@/outliner/OutlinerController';
import { isFolderUnder, folderName } from '@/outliner/folders';
@@ -64,7 +65,7 @@ import { InspectorClipboard } from '@/engine/inspectorClipboard';
import { SceneCommands, toModelValue } from '@/engine/SceneCommands';
import { ENTITY_SOURCES, createFromSource } from '@/engine/entitySources';
import { PlayInspect } from '@/engine/PlayInspect';
-import { DimensionUnit, AnchorAxis, detectAnchorAxes, UIPositionType, FlexDirection, FlexWrap, JustifyContent, AlignItems, INTERACTION_CONTROLLER, INTERACTION_PAGES, parseLocaleTable, EasingType, INVALID_ENTITY } from 'esengine';
+import { DimensionUnit, AnchorAxis, detectAnchorAxes, UIPositionType, FlexDirection, FlexWrap, JustifyContent, AlignItems, INTERACTION_CONTROLLER, INTERACTION_PAGES, parseLocaleTable, EasingType, BUILTIN_SHADER_TEMPLATES, INVALID_ENTITY } from 'esengine';
import type { SceneData, InputMapAsset, ActionType, Binding, LocaleTableAsset, PluralCategory, GearValue, GearTween, MaterialAssetData } from 'esengine';
import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba, dynamicEnumOptions, boxGroupsFor, isRequiredEmpty, type BoxGroupDef } from '@/engine/schema';
import * as imap from '@/project/inputMapDoc';
@@ -86,8 +87,10 @@ import {
renderMaterialThumbnail,
shaderProjectPathOf,
shaderRelRef,
+ BUILTIN_SHADER_PREFIX,
type MaterialContext,
} from '@/material/materialInspectorModel';
+import { convertShaderToUnique } from '@/material/openMaterial';
import { AnimClipDocument } from '@/flipbook/AnimClipDocument';
import { buildAnimClipComponents, makeAnimClipWrite } from '@/flipbook/animClipInspectorModel';
import { ColorControl, rgbaToHex8 } from '@/components/ColorControl';
@@ -1908,6 +1911,9 @@ function FlexLayoutControl({ entities, comp }: { entities: EntityId[]; comp: Ins
// ancestor, so a geared leaf still shows (and switches) the root's controllers.
function ControllersInline({ entityId }: { entityId: EntityId }) {
useSyncExternalStore(SceneStore.subscribe, SceneStore.getRevision);
+ const collapseExplicit = useInspectorCollapse((s) => s.explicit);
+ const toggleCollapse = useInspectorCollapse((s) => s.toggle);
+ const collapsed = isSectionCollapsed(collapseExplicit, '__controllers');
const activeController = useControllerStore((s) => s.activeController);
const setActiveController = useControllerStore((s) => s.setActiveController);
const recording = useControllerStore((s) => s.recording);
@@ -1940,14 +1946,22 @@ function ControllersInline({ entityId }: { entityId: EntityId }) {
return (
<div className="ctrl-inline">
- <div className="ctrl-head">
+ <div
+ className="ctrl-head ctrl-fold"
+ role="button"
+ tabIndex={0}
+ onClick={() => toggleCollapse('__controllers')}
+ onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); toggleCollapse('__controllers'); } }}
+ >
+ <span className="ctrl-caret">{collapsed ? <ChevronRight size={12} strokeWidth={2.4} /> : <ChevronDown size={12} strokeWidth={2.4} />}</span>
<span className="ctrl-title">{t('ctrl.title')}</span>
- <button type="button" className={`ctrl-rec${recording ? ' on' : ''}`} title={t('ctrl.recordTitle')} onClick={toggleRecording}>
+ <button type="button" className={`ctrl-rec${recording ? ' on' : ''}`} title={t('ctrl.recordTitle')} onClick={(e) => { e.stopPropagation(); toggleRecording(); }}>
<Circle size={9} fill="currentColor" />
{t('ctrl.record')}
</button>
</div>
+ {!collapsed && (<>
{controllers.length === 0 && <div className="ctrl-hint">{t('ctrl.hintAdd')}</div>}
{controllers.length > 0 && (
@@ -2011,6 +2025,7 @@ function ControllersInline({ entityId }: { entityId: EntityId }) {
<button type="button" className="ctrl-btn sm" title={t('ctrl.addController')} onClick={addController}><Plus size={12} /></button>
<button type="button" className="ctrl-btn sm" title={t('ctrl.addInteraction')} disabled={hasInteraction} onClick={addInteraction}><MousePointerClick size={12} /></button>
</div>
+ </>)}
</div>
);
}
@@ -2255,14 +2270,10 @@ function ComponentSection({
// (no add/remove/rename of the running game) — just live value debugging.
function GameDetails() {
const { selectedEntity, 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;
- });
+ // Persisted, shared collapse — a folded section stays folded across selections and
+ // restarts (chrome components default folded via the store's policy).
+ const collapseMap = useInspectorCollapse((s) => s.explicit);
+ const toggle = useInspectorCollapse((s) => s.toggle);
// The shallow tree snapshot strips component data; Details reads the selected
// entity's FULL data, fetched alongside the tree. Wrap it as a one-entity
@@ -2295,7 +2306,7 @@ function GameDetails() {
key={comp.name}
entities={[selection]}
comp={comp}
- collapsed={collapsed.has(comp.name)}
+ collapsed={isSectionCollapsed(collapseMap, comp.name)}
onToggle={() => toggle(comp.name)}
action={textBoxAction(comp, selection)}
write={(key, type, value) =>
@@ -2329,17 +2340,34 @@ function MaterialShaderSection({
collapsed: boolean;
onToggle: () => void;
}) {
- const shaderPath = shaderProjectPathOf(filePath, asset.shader);
+ const isBuiltin = asset.shader.startsWith(BUILTIN_SHADER_PREFIX);
+ const shaderPath = isBuiltin ? '' : shaderProjectPathOf(filePath, asset.shader);
const info = shaderPath ? ProjectStore.assetInfo(shaderPath) : null;
- const missing = !isInstance && !!asset.shader && !info;
+ const missing = !isInstance && !isBuiltin && !!asset.shader && !info;
+
+ // The picker offers built-in templates + every project `.esshader`. An option's value encodes
+ // which kind it is, so onPick can spell the stored ref: a `builtin:<id>` share-by-reference, or a
+ // path relative to the material. Pointing several materials at one file here = sharing a shader.
+ const options: { value: string; label: string }[] = [
+ ...BUILTIN_SHADER_TEMPLATES.map((tpl) => ({ value: BUILTIN_SHADER_PREFIX + tpl.id, label: t('mat.shaderBuiltin', { name: tpl.label }) })),
+ ...ProjectStore.listAssets('shader').map((a) => ({ value: `file:${a.path}`, label: a.name })),
+ ];
+ const current = isBuiltin ? asset.shader : `file:${shaderPath}`;
+ // Keep the current selection visible even when it isn't a listed option (a renamed / missing file).
+ if (asset.shader && !options.some((o) => o.value === current)) {
+ options.unshift({ value: current, label: info?.name ?? baseName(asset.shader) });
+ }
- const pick = (ref: string | number) => {
- const picked = typeof ref === 'string' ? ProjectStore.assetInfo(ref) : null;
- if (!picked) return; // clearing / unresolved is a no-op — a base material must keep a shader
- const rel = shaderRelRef(filePath, picked.path);
+ const onPick = (v: string) => {
+ const ref = v.startsWith(BUILTIN_SHADER_PREFIX)
+ ? v
+ : v.startsWith('file:')
+ ? shaderRelRef(filePath, v.slice('file:'.length))
+ : null;
+ if (ref == null) return;
MaterialDocument.edit('Set shader', (d) => {
- if (d.shader === rel) return;
- d.shader = rel;
+ if (d.shader === ref) return;
+ d.shader = ref;
// Parameters and the switch permutation belong to the old shader — start the new one clean.
d.properties = {};
delete d.switches;
@@ -2373,10 +2401,22 @@ function MaterialShaderSection({
{t('mat.shader')}
</span>
<div className="prop-value">
- <AssetControl value={shaderPath} assetType="shader" onChange={pick} />
+ <span className="field dropdown">
+ <Select variant="field" value={current} options={options} ariaLabel="shader" onChange={onPick} />
+ </span>
</div>
</div>
</div>
+ {isBuiltin && (
+ <button
+ type="button"
+ className="comp-action"
+ title={t('mat.convertToUniqueTip')}
+ onClick={() => void convertShaderToUnique(filePath, asset.shader.slice(BUILTIN_SHADER_PREFIX.length))}
+ >
+ {t('mat.convertToUnique')}
+ </button>
+ )}
</>
)}
</div>
@@ -2393,13 +2433,8 @@ function MaterialShaderSection({
function MaterialAssetInspector({ path }: { path: string }) {
const revision = useSyncExternalStore(MaterialDocument.subscribe, MaterialDocument.getRevision);
const [ctx, setCtx] = useState<MaterialContext | null>(null);
- const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
- const toggle = (name: string) =>
- setCollapsed((s) => {
- const n = new Set(s);
- n.has(name) ? n.delete(name) : n.add(name);
- return n;
- });
+ const collapseMap = useInspectorCollapse((s) => s.explicit);
+ const toggle = useInspectorCollapse((s) => s.toggle);
// Load the selected material into the singleton document when the selection changes, and bind
// the running handle the scene's sprites use (0 when it's not in the current scene).
@@ -2512,7 +2547,7 @@ function MaterialAssetInspector({ path }: { path: string }) {
asset={asset}
filePath={path}
isInstance={isInstance}
- collapsed={collapsed.has('Shader')}
+ collapsed={isSectionCollapsed(collapseMap, 'Shader')}
onToggle={() => toggle('Shader')}
/>
{components.map((comp) => (
@@ -2520,7 +2555,7 @@ function MaterialAssetInspector({ path }: { path: string }) {
key={comp.name}
entities={[]}
comp={comp}
- collapsed={collapsed.has(comp.name)}
+ collapsed={isSectionCollapsed(collapseMap, comp.name)}
onToggle={() => toggle(comp.name)}
write={write}
/>
@@ -2981,13 +3016,8 @@ function AssetInspector({ path }: { path: string }) {
// when the selected clip IS the open one, else falls back to import settings.
function AnimClipAssetInspector({ path }: { path: string }) {
useSyncExternalStore(AnimClipDocument.subscribe, AnimClipDocument.getRevision);
- const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
- const toggle = (name: string) =>
- setCollapsed((s) => {
- const n = new Set(s);
- n.has(name) ? n.delete(name) : n.add(name);
- return n;
- });
+ const collapseMap = useInspectorCollapse((s) => s.explicit);
+ const toggle = useInspectorCollapse((s) => s.toggle);
const asset = AnimClipDocument.asset;
const loaded = !!asset && AnimClipDocument.filePath === path;
@@ -3017,7 +3047,7 @@ function AnimClipAssetInspector({ path }: { path: string }) {
key={comp.name}
entities={[]}
comp={comp}
- collapsed={collapsed.has(comp.name)}
+ collapsed={isSectionCollapsed(collapseMap, comp.name)}
onToggle={() => toggle(comp.name)}
write={write}
/>
@@ -3306,13 +3336,8 @@ function FolderInspector({ path }: { path: string }) {
// edits route through source.write. The one shared inspector, no bespoke panel.
function SourceInspector({ source }: { source: InspectSource }) {
useSyncExternalStore(source.subscribe, source.getRevision);
- const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
- const toggle = (name: string) =>
- setCollapsed((s) => {
- const n = new Set(s);
- n.has(name) ? n.delete(name) : n.add(name);
- return n;
- });
+ const collapseMap = useInspectorCollapse((s) => s.explicit);
+ const toggle = useInspectorCollapse((s) => s.toggle);
const components = source.build();
return (
<div className="insp">
@@ -3327,7 +3352,7 @@ function SourceInspector({ source }: { source: InspectSource }) {
key={comp.name}
entities={[]}
comp={comp}
- collapsed={collapsed.has(comp.name)}
+ collapsed={isSectionCollapsed(collapseMap, comp.name)}
onToggle={() => toggle(comp.name)}
write={source.write}
/>
@@ -3364,16 +3389,11 @@ function EditorDetails() {
const multi = ids.length > 1;
const [query, setQuery] = useState('');
- const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
+ const collapseMap = useInspectorCollapse((s) => s.explicit);
+ const toggle = useInspectorCollapse((s) => s.toggle);
const [compMenu, setCompMenu] = useState<{ x: number; y: number; comp: string } | null>(null);
const [addOpen, setAddOpen] = useState(false);
const [filtOn, setFiltOn] = useState(false);
- const toggle = (name: string) =>
- setCollapsed((prev) => {
- const next = new Set(prev);
- next.has(name) ? next.delete(name) : next.add(name);
- return next;
- });
const entity = useMemo(
() => (ready ? SceneQuery.readEntity(selectedId!) : null),
@@ -3588,7 +3608,7 @@ function EditorDetails() {
key={comp.name}
entities={ids}
comp={comp}
- collapsed={collapsed.has(comp.name)}
+ collapsed={isSectionCollapsed(collapseMap, comp.name)}
onToggle={() => toggle(comp.name)}
onMore={(e, name) => setCompMenu({ x: e.clientX, y: e.clientY, comp: name })}
action={uiNodeCanvasAction(ids, comp)}
diff --git a/desktop/src/store/inspectorCollapse.ts b/desktop/src/store/inspectorCollapse.ts
new file mode 100644
index 000000000..c990b10e8
--- /dev/null
+++ b/desktop/src/store/inspectorCollapse.ts
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file inspectorCollapse.ts — persisted collapse state for Details inspector
+ * sections, keyed by component name (or a synthetic section key like
+ * `__controllers`). Shared by every inspector variant so a section a user
+ * folds stays folded across selections AND editor restarts, instead of the
+ * old per-mount useState that reset on every reselect.
+ *
+ * A section's default state comes from DEFAULT_COLLAPSED (rarely-tuned "chrome"
+ * opens folded so a UI widget's inspector isn't a wall of always-open sections);
+ * an explicit user toggle overrides that per section and is what gets persisted.
+ */
+import { create } from 'zustand';
+
+// Sections that open COLLAPSED by default: chrome that pads every UI widget's
+// inspector — Focusable (tabIndex/isFocused, rarely touched) and ThemeStyle (a
+// zero-field runtime tag). A user's explicit toggle overrides and persists.
+const DEFAULT_COLLAPSED = new Set(['Focusable', 'ThemeStyle']);
+
+const LS_KEY = 'estella.inspectorCollapse';
+
+function load(): Record<string, boolean> {
+ if (typeof localStorage === 'undefined') return {};
+ try {
+ return JSON.parse(localStorage.getItem(LS_KEY) ?? '{}') as Record<string, boolean>;
+ } catch {
+ return {}; // corrupt blob → start clean
+ }
+}
+function save(explicit: Record<string, boolean>): void {
+ if (typeof localStorage === 'undefined') return;
+ try {
+ localStorage.setItem(LS_KEY, JSON.stringify(explicit));
+ } catch {
+ /* quota / private mode — persistence is best-effort */
+ }
+}
+
+/** Whether a section renders collapsed: the explicit user choice, else the default. */
+export function isSectionCollapsed(explicit: Record<string, boolean>, name: string): boolean {
+ return explicit[name] ?? DEFAULT_COLLAPSED.has(name);
+}
+
+interface InspectorCollapseState {
+ /** Explicit user choices, section-key → collapsed?. Absent ⇒ the default policy. */
+ explicit: Record<string, boolean>;
+ /** Toggle a section's collapse (persists the explicit choice). */
+ toggle: (name: string) => void;
+}
+
+export const useInspectorCollapse = create<InspectorCollapseState>((set, get) => ({
+ explicit: load(),
+ toggle: (name) =>
+ set(() => {
+ const cur = get().explicit;
+ const explicit = { ...cur, [name]: !isSectionCollapsed(cur, name) };
+ save(explicit);
+ return { explicit };
+ }),
+}));
diff --git a/desktop/src/theme/controllers.css b/desktop/src/theme/controllers.css
index 2622fe924..2869b66ee 100644
--- a/desktop/src/theme/controllers.css
+++ b/desktop/src/theme/controllers.css
@@ -8,6 +8,11 @@
the fields so choosing a page + gearing a field happen in one place. Reuses every
.ctrl-* class from the panel; this is only the containing card. */
.ctrl-inline { display: flex; flex-direction: column; gap: 8px; padding: 8px; margin-bottom: 8px; background: var(--srf-2); border: 1px solid var(--border); border-radius: var(--r-sm); }
+/* Foldable header: caret + title on the left, record pinned right. */
+.ctrl-fold { justify-content: flex-start; gap: 5px; cursor: pointer; user-select: none; }
+.ctrl-fold .ctrl-rec { margin-left: auto; }
+.ctrl-caret { display: inline-flex; align-items: center; color: var(--text-dim); }
+.ctrl-fold:hover .ctrl-title { color: var(--text); }
.ctrl-hint { font-size: var(--fs-2xs); color: var(--text-dim); line-height: 1.4; padding: 0 2px; }
.ctrl-head { display: flex; align-items: center; justify-content: space-between; }