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.

refactor(editor): one semantic per column, one surface per control

esengine8c12650185de
diff --git a/desktop/src/components/NineSliceEditor.tsx b/desktop/src/components/NineSliceEditor.tsx
index 7893a1e48..250b21659 100644
--- a/desktop/src/components/NineSliceEditor.tsx
+++ b/desktop/src/components/NineSliceEditor.tsx
@@ -16,6 +16,7 @@
* centre slice alive) lives in `project/nineSlice.ts` as pure functions.
*/
import { useEffect, useRef, useState } from 'react';
+import { useElementSize } from '@/components/useElementSize';
import { t } from '@/i18n';
import type { FieldWrite } from '@/types';
import {
@@ -42,7 +43,8 @@ export function NineSliceEditor({ path, importer, write }: {
}) {
const boxRef = useRef<HTMLDivElement>(null);
const [tex, setTex] = useState<{ w: number; h: number } | null>(null);
- const [box, setBox] = useState({ w: 0, h: BOX_H });
+ // The drawn box is width-fluid (the inspector column), so measure it.
+ const box = useElementSize(boxRef);
const [drag, setDrag] = useState<SliceEdge | null>(null);
const [hover, setHover] = useState<SliceEdge | null>(null);
@@ -56,16 +58,6 @@ export function NineSliceEditor({ path, importer, write }: {
return () => { alive = false; };
}, [path]);
- // The drawn box is width-fluid (the inspector column), so measure it.
- useEffect(() => {
- const el = boxRef.current;
- if (!el) return;
- const measure = () => setBox({ w: el.clientWidth, h: el.clientHeight });
- measure();
- const ro = new ResizeObserver(measure);
- ro.observe(el);
- return () => ro.disconnect();
- }, []);
const texW = tex?.w ?? 0;
const texH = tex?.h ?? 0;
diff --git a/desktop/src/components/NodeGraphCanvas.tsx b/desktop/src/components/NodeGraphCanvas.tsx
index 604a318a3..feecf439c 100644
--- a/desktop/src/components/NodeGraphCanvas.tsx
+++ b/desktop/src/components/NodeGraphCanvas.tsx
@@ -17,6 +17,7 @@
import { useEffect, useImperativeHandle, useRef, useState, type ReactNode, type Ref, type MouseEvent as ReactMouseEvent } from 'react';
import { ContextMenu, type MenuItem } from '@/components/Menu';
import { usePanelWindow } from '@/components/PanelWindow';
+import { ZoomControl } from '@/components/ZoomControl';
import { t } from '@/i18n';
export type { MenuItem };
@@ -111,6 +112,20 @@ export interface NodeGraphCanvasProps<N extends CanvasNode, E extends CanvasEdge
const nx = (n: CanvasNode) => n.x ?? 0;
const ny = (n: CanvasNode) => n.y ?? 0;
+/** How far the canvas zooms. The stepper and the wheel share these so the
+ * readout can never show a zoom the wheel refuses (or the reverse). */
+const ZOOM_MIN = 0.25;
+const ZOOM_MAX = 2.5;
+
+interface Viewport { x: number; y: number; zoom: number }
+
+/** Re-zoom about a fixed canvas point, so whatever is under `(mx, my)` stays there. */
+function zoomAbout(v: Viewport, zoom: number, mx: number, my: number): Viewport {
+ const next = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, zoom));
+ const k = next / v.zoom;
+ return { x: mx - (mx - v.x) * k, y: my - (my - v.y) * k, zoom: next };
+}
+
function bezier(x1: number, y1: number, x2: number, y2: number): string {
const dx = Math.max(40, Math.abs(x2 - x1) * 0.5);
return `M ${x1} ${y1} C ${x1 + dx} ${y1}, ${x2 - dx} ${y2}, ${x2} ${y2}`;
@@ -200,7 +215,7 @@ export function NodeGraphCanvas<N extends CanvasNode, E extends CanvasEdge>(prop
if (!el || !b) return setVp({ x: 0, y: 0, zoom: 1 });
const r = el.getBoundingClientRect(), pad = 60;
const cw = Math.max(1, b.maxX - b.minX), ch = Math.max(1, b.maxY - b.minY);
- const zoom = Math.min(1.5, Math.max(0.25, Math.min((r.width - pad * 2) / cw, (r.height - pad * 2) / ch)));
+ const zoom = Math.min(1.5, Math.max(ZOOM_MIN, Math.min((r.width - pad * 2) / cw, (r.height - pad * 2) / ch)));
setVp({ x: (r.width - cw * zoom) / 2 - b.minX * zoom, y: (r.height - ch * zoom) / 2 - b.minY * zoom, zoom });
};
const resetView = () => setVp({ x: 0, y: 0, zoom: 1 });
@@ -430,11 +445,7 @@ export function NodeGraphCanvas<N extends CanvasNode, E extends CanvasEdge>(prop
const r = el.getBoundingClientRect();
const mx = e.clientX - r.left;
const my = e.clientY - r.top;
- setVp(v => {
- const zoom = Math.min(2.5, Math.max(0.25, v.zoom * (e.deltaY < 0 ? 1.1 : 1 / 1.1)));
- const k = zoom / v.zoom;
- return { x: mx - (mx - v.x) * k, y: my - (my - v.y) * k, zoom };
- });
+ setVp(v => zoomAbout(v, v.zoom * (e.deltaY < 0 ? 1.1 : 1 / 1.1), mx, my));
}}
onContextMenu={e => { const p = toCanvas(e.clientX, e.clientY); openMenu(e, { kind: 'canvas', x: p.x, y: p.y }); }}>
{nodes.length === 0 && emptyHint && <div className="ng-empty">{emptyHint}</div>}
@@ -521,6 +532,22 @@ export function NodeGraphCanvas<N extends CanvasNode, E extends CanvasEdge>(prop
);
})}
</div>
+ {/* Corner chrome, not a toolbar row: this canvas pans without bounds, so its
+ view controls belong to the surface — the same place the viewport keeps
+ its own. The stepper itself is the one every zoomed panel uses. */}
+ <div className="ng-viewctl" onPointerDown={e => e.stopPropagation()} onWheel={e => e.stopPropagation()}>
+ <ZoomControl
+ zoom={vp.zoom}
+ min={ZOOM_MIN}
+ max={ZOOM_MAX}
+ onZoom={z => {
+ const r = canvasRef.current?.getBoundingClientRect();
+ setVp(v => zoomAbout(v, z, (r?.width ?? 0) / 2, (r?.height ?? 0) / 2));
+ }}
+ onFit={fitToContent}
+ fitTitle={t('ng.fit')}
+ />
+ </div>
</div>
{menu && menuItems && (
diff --git a/desktop/src/components/useElementSize.ts b/desktop/src/components/useElementSize.ts
new file mode 100644
index 000000000..8caeb44ce
--- /dev/null
+++ b/desktop/src/components/useElementSize.ts
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file useElementSize.ts
+ * @brief Live content-box size of a ref'd element, for the panels that fit a
+ * drawing to the space a dock gave them (9-slice box, flipbook stage).
+ */
+import { useEffect, useState, type RefObject } from 'react';
+
+/** Observes `ref` and returns its client size; `{ w: 0, h: 0 }` before first layout. */
+export function useElementSize(ref: RefObject<HTMLElement | null>): { w: number; h: number } {
+ const [size, setSize] = useState({ w: 0, h: 0 });
+ useEffect(() => {
+ const el = ref.current;
+ if (!el) return;
+ const measure = () => setSize({ w: el.clientWidth, h: el.clientHeight });
+ measure();
+ // The element's own document: a popped-out panel lives in another window,
+ // whose ResizeObserver is the one that fires for it.
+ const RO = el.ownerDocument.defaultView?.ResizeObserver ?? ResizeObserver;
+ const ro = new RO(measure);
+ ro.observe(el);
+ return () => ro.disconnect();
+ }, [ref]);
+ return size;
+}
diff --git a/desktop/src/i18n/messages/nodegraph.ts b/desktop/src/i18n/messages/nodegraph.ts
index 68fddb453..24af3bc64 100644
--- a/desktop/src/i18n/messages/nodegraph.ts
+++ b/desktop/src/i18n/messages/nodegraph.ts
@@ -15,6 +15,7 @@ export const nodegraphMessages = defineMessages({
'ng.fsmEmpty': { en: 'No state machine open', zh: '未打开状态机' },
'ng.btEmpty': { en: 'No behavior tree open', zh: '未打开行为树' },
'ng.animatorEmpty': { en: 'No animation controller open', zh: '未打开动画控制器' },
+ 'ng.fit': { en: 'Frame all nodes (F)', zh: '框选全部节点(F)' },
'ng.save': { en: 'Save', zh: '保存' },
'ng.deleteSelected': { en: 'Delete selected', zh: '删除所选' },
'ng.name': { en: 'Name', zh: '名称' },
diff --git a/desktop/src/outliner/OutlinerRow.tsx b/desktop/src/outliner/OutlinerRow.tsx
index 97115276d..378c165e4 100644
--- a/desktop/src/outliner/OutlinerRow.tsx
+++ b/desktop/src/outliner/OutlinerRow.tsx
@@ -91,6 +91,7 @@ function OutlinerRowInner(props: OutlinerRowProps) {
const canRename = !!props.onCommitRename;
const collapsible = props.collapsible !== false;
const showTwist = hasChildren && collapsible;
+ const childCount = item.kind === 'folder' ? item.count : (item.node.children?.length ?? 0);
return (
<div
@@ -164,6 +165,11 @@ function OutlinerRowInner(props: OutlinerRowProps) {
onDoubleClick={canRename && props.onStartRename ? () => props.onStartRename!(item) : undefined}
>
{highlightName(name, props.highlight)}
+ {/* "How many are inside me" — one fact, so a folder's items and an
+ entity's children read the same way. Inside the name so it hugs the
+ text; as a sibling it drifted to the far edge and collided with the
+ Type column. */}
+ {childCount > 0 && <span className="rcount">{childCount}</span>}
</span>
)}
diff --git a/desktop/src/outliner/columns.tsx b/desktop/src/outliner/columns.tsx
index b5ef8b120..2cd95785a 100644
--- a/desktop/src/outliner/columns.tsx
+++ b/desktop/src/outliner/columns.tsx
@@ -40,7 +40,12 @@ export interface OutlinerColumn {
render: (item: OutlinerItem, ctx: OutlinerColumnContext) => ReactNode;
}
-/** Entity kind → the label shown in the Type column. */
+/**
+ * Entity kind → the Type column's label, or '' for a kind that tells the reader
+ * nothing. `empty` is every entity the classifier found no distinguishing
+ * component on, so labelling it "Entity" set most of a scene's rows to a word
+ * that is true of all of them; blank says the same thing without the noise.
+ */
const KIND_TYPE: Record<NodeKind, string> = {
camera: t('out.kindCamera'),
sprite: t('out.kindSprite'),
@@ -50,24 +55,20 @@ const KIND_TYPE: Record<NodeKind, string> = {
audio: t('out.kindAudio'),
group: t('out.kindGroup'),
light: t('out.kindLight'),
- empty: t('out.kindEntity'),
+ empty: '',
};
-/** Type / count column — prefab instances read "Prefab", others by kind + child count. */
+/** Type column — what this row IS. Prefab instances read "Prefab", which the
+ * row's icon cannot say; everything else reads its kind. Counts are not a type
+ * and live next to the name (see OutlinerRow). */
export const TYPE_COLUMN: OutlinerColumn = {
id: 'type',
header: t('out.colType'),
width: 78,
- applies: () => true,
+ applies: (item) => item.kind === 'entity',
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) ? t('out.prefab') : (KIND_TYPE[item.node.kind] ?? t('out.kindEntity'));
- label = childCount > 0 ? `${base} · ${childCount}` : base;
- }
+ if (item.kind !== 'entity') return null;
+ const label = ctx.isPrefab?.(item.id) ? t('out.prefab') : KIND_TYPE[item.node.kind];
return <span className="rtype">{label}</span>;
},
};
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index e514797bf..48ebe3de5 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -871,15 +871,23 @@ function ComponentSection({
<span className="comp-arrow">
<ChevronRight size={9} strokeWidth={3} />
</span>
- <span
- className={`comp-chk${on ? ' on' : ''}${enable?.mixed ? ' mixed' : ''}`}
- role={enable ? 'checkbox' : undefined}
- aria-checked={enable ? (enable.mixed ? 'mixed' : enable.value) : undefined}
- title={enable ? (enable.value ? t('det.disableComponent') : t('det.enableComponent')) : undefined}
- onClick={enable ? toggleEnable : (e) => e.stopPropagation()}
- >
- {on && <Check size={9} strokeWidth={3.2} />}
- </span>
+ {/* Only a section that CAN be turned off draws a box. Transform and the
+ importer/asset sections cannot, and a permanently ticked checkbox
+ promises a toggle that isn't there — they keep the slot for alignment
+ and leave it empty. */}
+ {enable ? (
+ <span
+ className={`comp-chk${on ? ' on' : ''}${enable.mixed ? ' mixed' : ''}`}
+ role="checkbox"
+ aria-checked={enable.mixed ? 'mixed' : enable.value}
+ title={enable.value ? t('det.disableComponent') : t('det.enableComponent')}
+ onClick={toggleEnable}
+ >
+ {on && <Check size={9} strokeWidth={3.2} />}
+ </span>
+ ) : (
+ <span className="comp-chk-slot" aria-hidden="true" />
+ )}
{enable && enableGear}
<span className="comp-icon">
<Icon size={13} strokeWidth={1.9} />
diff --git a/desktop/src/panels/FlipbookEditor.tsx b/desktop/src/panels/FlipbookEditor.tsx
index d8128b7b7..767b0093a 100644
--- a/desktop/src/panels/FlipbookEditor.tsx
+++ b/desktop/src/panels/FlipbookEditor.tsx
@@ -21,6 +21,7 @@ import {
import { EmptyState } from '@/components/EmptyState';
import { GridField } from '@/components/GridField';
import { ZoomControl } from '@/components/ZoomControl';
+import { useElementSize } from '@/components/useElementSize';
import { Transport } from '@/components/Transport';
import { SaveButton } from '@/components/SaveButton';
import { AnimClipDocument } from '@/flipbook/AnimClipDocument';
@@ -60,6 +61,8 @@ export function FlipbookEditor() {
const [zoom, setZoom] = useState(2);
// Fit the whole sheet page into the scroll viewport (both axes).
const canvasRef = useRef<HTMLDivElement>(null);
+ const stageRef = useRef<HTMLDivElement>(null);
+ const stageBox = useElementSize(stageRef);
const fitZoom = () => {
const c = canvasRef.current;
if (!c || !sheet || sheet.pageWidth <= 0 || sheet.pageHeight <= 0) return;
@@ -145,9 +148,13 @@ export function FlipbookEditor() {
};
};
+ // The sprite fills the stage the dock actually gave us, square and inset so the
+ // anchor handle stays grabbable at the edges. Falls back to the CSS min-height
+ // before the first measurement.
+ const STAGE = Math.max(120, Math.min(stageBox.w, stageBox.h || 172) - 20);
+
// Onion skin: ghost the nearest frames behind the current one, fading with
// distance. Only while paused — during playback the trail is just noise.
- const STAGE = 152;
const onionGhosts: { i: number; dir: number; op: number }[] = [];
if (onion && !playing && asset.frames.length > 1) {
const n = asset.frames.length;
@@ -230,7 +237,7 @@ export function FlipbookEditor() {
{asset.frames.length > 0 && (
<div className="fb-pv">
- <div className="fb-pv__view">
+ <div className="fb-pv__view" ref={stageRef}>
{onionGhosts.map((g) => (
<span
key={`${g.dir}-${g.i}`}
diff --git a/desktop/src/theme/flipbook.css b/desktop/src/theme/flipbook.css
index 9c394d9d3..b8f938a75 100644
--- a/desktop/src/theme/flipbook.css
+++ b/desktop/src/theme/flipbook.css
@@ -191,6 +191,8 @@
/* Transport-driven preview stage: a checkerboard view with the current frame
(onion-skin ghosts behind it) over a control bar (shared <Transport> + onion). */
+/* The one section that takes the slack: every other row is content-sized, so a
+ tall dock used to end in dead space instead of a bigger sprite to judge. */
.fb-pv {
display: flex;
flex-direction: column;
@@ -198,11 +200,13 @@
padding: 8px 10px;
border-bottom: 1px solid var(--line);
background: var(--srf-2);
- flex: 0 0 auto;
+ flex: 1 1 auto;
+ min-height: 0;
}
.fb-pv__view {
position: relative;
- height: 172px;
+ flex: 1 1 auto;
+ min-height: 172px;
border-radius: var(--r-sm);
overflow: hidden;
background-color: var(--inset);
diff --git a/desktop/src/theme/inspector.css b/desktop/src/theme/inspector.css
index ff9d969fe..e2d31b541 100644
--- a/desktop/src/theme/inspector.css
+++ b/desktop/src/theme/inspector.css
@@ -67,6 +67,9 @@
.comp.open .comp-arrow svg { transform: rotate(90deg); }
.comp-chk { width: 14px; height: 14px; border: 1px solid var(--border-line); border-radius: var(--r-xs); display: grid; place-items: center; color: transparent; background: var(--inset); flex-shrink: 0; transition: all var(--t-fast); }
.comp-chk.on { background: var(--acc); border-color: var(--acc); color: var(--on-accent); }
+/* Holds the checkbox's place on a section that has nothing to toggle, so every
+ section's icon and name still line up. */
+.comp-chk-slot { width: 14px; flex-shrink: 0; }
.comp-icon { color: var(--text-dim); display: grid; place-items: center; }
.comp-name { font-weight: 600; font-size: var(--fs-sm); color: var(--text); flex: 1; }
.comp.override .comp-name::after { content: ''; display: inline-block; width: 5px; height: 5px; background: var(--warn); border-radius: 50%; margin-left: 7px; vertical-align: middle; }
diff --git a/desktop/src/theme/nodegraph.css b/desktop/src/theme/nodegraph.css
index 1bb48e752..cc1ad71ae 100644
--- a/desktop/src/theme/nodegraph.css
+++ b/desktop/src/theme/nodegraph.css
@@ -34,6 +34,20 @@
background-image: radial-gradient(var(--srf-3) 1px, transparent 1px);
}
.ng-svg { position: absolute; top: 0; left: 0; width: 4000px; height: 4000px; overflow: visible; }
+/* View controls as canvas chrome, matching the viewport's own corner overlays. */
+.ng-viewctl {
+ position: absolute;
+ right: 10px;
+ bottom: 10px;
+ z-index: 4;
+ padding: 2px 4px;
+ background: rgba(var(--glass-rgb), 0.72);
+ -webkit-backdrop-filter: blur(14px);
+ backdrop-filter: blur(14px);
+ border: 1px solid var(--border-line);
+ border-radius: var(--r-md);
+ box-shadow: var(--shadow-2);
+}
.ng-empty {
position: absolute;
inset: 0;
diff --git a/desktop/src/theme/outliner.css b/desktop/src/theme/outliner.css
index fdc34eb63..4f8327420 100644
--- a/desktop/src/theme/outliner.css
+++ b/desktop/src/theme/outliner.css
@@ -85,6 +85,14 @@
.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); }
+/* Child/item count: reads as an annotation on the name, never competing with it. */
+.row .rcount {
+ margin-left: 6px;
+ font-size: var(--fs-2xs);
+ font-family: var(--mono);
+ color: var(--text-faint);
+}
+.row.sel .rcount { color: rgba(255, 255, 255, 0.6); }
/* Narrow dock: the fixed Type column would eat the name into "C…" slivers —
drop it and give the name the full row (lock/visibility keep their cells). */
@container (max-width: 209px) {
diff --git a/desktop/tests/outliner-columns.test.ts b/desktop/tests/outliner-columns.test.ts
index aa529b012..2be12ed6a 100644
--- a/desktop/tests/outliner-columns.test.ts
+++ b/desktop/tests/outliner-columns.test.ts
@@ -6,12 +6,17 @@
* entity-only columns (lock/vis) render an aligned spacer on folder rows.
*/
import { describe, it, expect } from 'vitest';
+import type { ReactNode } from 'react';
import type { SceneData } from 'esengine';
import { buildOutlinerItems } from '@/outliner/OutlinerModel';
import { OUTLINER_COLUMNS, TYPE_COLUMN, LOCK_COLUMN, VIS_COLUMN, type OutlinerColumnContext } from '@/outliner/columns';
const NO_CTX: OutlinerColumnContext = {};
+/** The text a Type cell renders (it is a <span>{label}</span> element, not markup). */
+const typeLabel = (cell: ReactNode): string =>
+ String((cell as { props?: { children?: unknown } })?.props?.children ?? '');
+
// 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;
@@ -23,18 +28,33 @@ describe('outliner column registry', () => {
expect(OUTLINER_COLUMNS.map((c) => c.id)).toEqual(['type', 'lock', 'vis']);
});
- it('Type applies to every row; Lock/Vis only to entities', () => {
+ it('Type, Lock and Visibility all apply to entity rows only', () => {
const all = items();
const entity = all.find((i) => i.kind === 'entity')!;
const folder = all.find((i) => i.kind === 'folder')!;
expect(TYPE_COLUMN.applies(entity, NO_CTX)).toBe(true);
- expect(TYPE_COLUMN.applies(folder, NO_CTX)).toBe(true);
+ // A folder's type is its icon and its twist, and its item count is not a type.
+ expect(TYPE_COLUMN.applies(folder, NO_CTX)).toBe(false); // → an aligned spacer
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 classifier calls every entity it finds no distinguishing component on
+ // `empty`. Labelling those "Entity" put a word true of every row on most of
+ // them; the cell renders, so the columns stay aligned, but it says nothing.
+ it('an entity with no distinguishing kind gets a blank Type, not "Entity"', () => {
+ const entity = items().find((i) => i.kind === 'entity')!;
+ expect(entity.kind === 'entity' && entity.node.kind).toBe('empty');
+ expect(typeLabel(TYPE_COLUMN.render(entity, NO_CTX))).toBe('');
+ });
+
+ it('a prefab instance says so — the row icon cannot', () => {
+ const entity = items().find((i) => i.kind === 'entity')!;
+ expect(typeLabel(TYPE_COLUMN.render(entity, { isPrefab: () => true }))).not.toBe('');
+ });
+
// 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', () => {