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
refactor(editor): one semantic per column, one surface per control
esengine8c12650185de
diff --git a/desktop/src/components/NineSliceEditor.tsx b/desktop/src/components/NineSliceEditor.tsxindex 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.tsxindex 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 CanvasEdgeconst 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>(propif (!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>(propconst 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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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) => (<spankey={`${g.dir}-${g.i}`}diff --git a/desktop/src/theme/flipbook.css b/desktop/src/theme/flipbook.cssindex 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.cssindex 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.cssindex 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.cssindex 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.tsindex 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 spacerexpect(LOCK_COLUMN.applies(entity, NO_CTX)).toBe(true);expect(LOCK_COLUMN.applies(folder, NO_CTX)).toBe(false); // → an aligned spacer on folder rowsexpect(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', () => {