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): unify the node-graph editor family (framing, add, empty state)

yhh4a07c9d263f2
diff --git a/desktop/src/components/NodeGraphCanvas.tsx b/desktop/src/components/NodeGraphCanvas.tsx
index b3b1a2b3d..604a318a3 100644
--- a/desktop/src/components/NodeGraphCanvas.tsx
+++ b/desktop/src/components/NodeGraphCanvas.tsx
@@ -50,6 +50,13 @@ export interface CanvasPort {
* the canvas context menu without owning the viewport math). */
export interface NodeGraphCanvasApi {
openMenuAt(screenX: number, screenY: number): void;
+ /** Frame all nodes (zoom-to-fit with padding) — bound to F and auto-run on open. */
+ fitToContent(): void;
+ /** Reset pan to origin at 100% zoom — bound to 0 / Home. */
+ resetView(): void;
+ /** World coord at the canvas centre — where a toolbar "Add" should drop a node
+ * so it lands on-screen (not at a hardcoded off-screen coord). */
+ centerWorld(): { x: number; y: number };
}
export interface ContextTarget {
@@ -155,6 +162,9 @@ export function NodeGraphCanvas<N extends CanvasNode, E extends CanvasEdge>(prop
const p = toCanvas(screenX, screenY);
setMenu({ screenX, screenY, target: { kind: 'canvas', x: p.x, y: p.y } });
},
+ fitToContent,
+ resetView,
+ centerWorld,
}));
// Screen point → world coord (inverse of the viewport transform).
@@ -173,6 +183,43 @@ export function NodeGraphCanvas<N extends CanvasNode, E extends CanvasEdge>(prop
return null;
};
+ // World-coord bounding box over all nodes (null when empty).
+ const contentBounds = () => {
+ if (nodes.length === 0) return null;
+ let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+ for (const n of nodes) {
+ const s = nodeSize(n);
+ minX = Math.min(minX, nx(n)); minY = Math.min(minY, ny(n));
+ maxX = Math.max(maxX, nx(n) + s.width); maxY = Math.max(maxY, ny(n) + s.height);
+ }
+ return { minX, minY, maxX, maxY };
+ };
+ // Frame all nodes centred, with padding, zoom clamped to a sane range.
+ const fitToContent = () => {
+ const el = canvasRef.current, b = contentBounds();
+ 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)));
+ 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 });
+ const centerWorld = () => {
+ const el = canvasRef.current;
+ if (!el) return { x: 0, y: 0 };
+ const r = el.getBoundingClientRect();
+ return toCanvas(r.left + r.width / 2, r.top + r.height / 2);
+ };
+ // Auto-frame the graph the first time nodes are present (opening an editor whose
+ // nodes were authored far from origin otherwise shows a blank canvas).
+ const didFit = useRef(false);
+ useEffect(() => {
+ if (didFit.current || nodes.length === 0) return;
+ didFit.current = true;
+ fitToContent();
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [nodes.length]);
+
useEffect(() => {
const onMove = (e: PointerEvent) => {
if (pan.current) {
@@ -288,6 +335,18 @@ export function NodeGraphCanvas<N extends CanvasNode, E extends CanvasEdge>(prop
else if (selectedEdge) onDeleteEdge(selectedEdge);
return;
}
+ if (e.key === 'f' || e.key === 'F') {
+ e.preventDefault();
+ e.stopPropagation();
+ fitToContent(); // frame all nodes
+ return;
+ }
+ if (e.key === '0' || e.key === 'Home') {
+ e.preventDefault();
+ e.stopPropagation();
+ resetView(); // 100% at origin
+ return;
+ }
const dir = KEY_DIR[e.key];
if (!dir) return;
e.preventDefault();
diff --git a/desktop/src/i18n/messages/material.ts b/desktop/src/i18n/messages/material.ts
index 1305045bf..149d5e171 100644
--- a/desktop/src/i18n/messages/material.ts
+++ b/desktop/src/i18n/messages/material.ts
@@ -10,6 +10,7 @@ export const materialMessages = defineMessages({
'mat.panelTitle': { en: 'Material Graph', zh: '材质图' },
'mat.openHintPrefix': { en: 'Open a ', zh: '从内容浏览器打开 ' },
'mat.openHintSuffix': { en: ' from the Content Browser to edit it.', zh: ' 文件进行编辑。' },
+ 'mat.graphEmpty': { en: 'No material graph open', zh: '未打开材质图' },
'mat.add': { en: 'Add', zh: '添加' },
'mat.addNode': { en: 'Add node', zh: '添加节点' },
'mat.deleteNode': { en: 'Delete node', zh: '删除节点' },
diff --git a/desktop/src/i18n/messages/nodegraph.ts b/desktop/src/i18n/messages/nodegraph.ts
index 7cf2b9772..68fddb453 100644
--- a/desktop/src/i18n/messages/nodegraph.ts
+++ b/desktop/src/i18n/messages/nodegraph.ts
@@ -11,6 +11,10 @@ export const nodegraphMessages = defineMessages({
// markup survives translation (pre + <code>.ext</code> + post).
'ng.openHintPre': { en: 'Open a ', zh: '从内容浏览器打开 ' },
'ng.openHintPost': { en: ' from the Content Browser to edit it.', zh: ' 文件进行编辑。' },
+ // Empty-panel titles (shared shared-graph editors); the hint reuses ng.openHint* above.
+ '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.save': { en: 'Save', zh: '保存' },
'ng.deleteSelected': { en: 'Delete selected', zh: '删除所选' },
'ng.name': { en: 'Name', zh: '名称' },
@@ -84,6 +88,8 @@ export const nodegraphMessages = defineMessages({
'bt.unnamed': { en: '(unnamed)', zh: '(未命名)' },
'bt.deleteNode': { en: 'Delete node', zh: '删除节点' },
'bt.menuAdd': { en: 'Add {type}', zh: '添加{type}' },
+ 'bt.addNode': { en: 'Node', zh: '节点' },
+ 'bt.addNodeTip': { en: 'Add a node', zh: '添加节点' },
'bt.menuAddChild': { en: 'Add child: {type}', zh: '添加子节点:{type}' },
'bt.emptyHint': {
en: 'Drag from a node\'s handle to another to set parent → child.',
diff --git a/desktop/src/panels/AnimatorEditor.tsx b/desktop/src/panels/AnimatorEditor.tsx
index 3b3426cda..bf46664f1 100644
--- a/desktop/src/panels/AnimatorEditor.tsx
+++ b/desktop/src/panels/AnimatorEditor.tsx
@@ -14,7 +14,7 @@
* carrying an AND-list of typed parameter conditions + an exit-time flag.
*/
import { useRef, useState, useSyncExternalStore } from 'react';
-import { Plus, Trash2, X } from 'lucide-react';
+import { Plus, Trash2, X, Film } from 'lucide-react';
import {
animatorEdges,
addAnimatorState, removeAnimatorState, moveAnimatorState, renameAnimatorState, setAnimatorInitial,
@@ -26,7 +26,8 @@ import {
} from 'esengine';
import { AnimatorGraphDocument } from '@/animator/AnimatorGraphDocument';
import { t } from '@/i18n';
-import { NodeGraphCanvas, type CanvasNode } from '@/components/NodeGraphCanvas';
+import { NodeGraphCanvas, type CanvasNode, type NodeGraphCanvasApi } from '@/components/NodeGraphCanvas';
+import { EmptyState } from '@/components/EmptyState';
import { Select } from '@/components/Select';
import { SaveButton } from '@/components/SaveButton';
@@ -70,9 +71,18 @@ export function AnimatorEditor() {
const [selState, setSelState] = useState<string | null>(null);
const [selEdge, setSelEdge] = useState<string | null>(null);
const dragBefore = useRef<AnimatorControllerDef | null>(null);
+ const canvas = useRef<NodeGraphCanvasApi>(null);
if (!def || !filePath) {
- return <div className="panel ng-placeholder"><p>{t('ng.openHintPre')}<code>.esanimator</code>{t('ng.openHintPost')}</p></div>;
+ return (
+ <div className="panel">
+ <EmptyState
+ icon={Film}
+ title={t('ng.animatorEmpty')}
+ hint={<>{t('ng.openHintPre')}<code>.esanimator</code>{t('ng.openHintPost')}</>}
+ />
+ </div>
+ );
}
const nodes: AnimatorCanvasNode[] = def.states.map((s) => ({ ...s, id: s.name }));
@@ -81,7 +91,10 @@ export function AnimatorEditor() {
const addStateAt = () => {
const name = uniqueName(def, 'State');
- AnimatorGraphDocument.edit('Add state', (d) => Object.assign(d, addAnimatorState(d, name, 200, 120)));
+ // View-centre drop + per-state cascade (see StateMachineEditor).
+ const c = canvas.current?.centerWorld() ?? { x: 200, y: 120 };
+ const k = (def.states.length % 6) * 26;
+ AnimatorGraphDocument.edit('Add state', (d) => Object.assign(d, addAnimatorState(d, name, Math.round(c.x - NODE_W / 2 + k), Math.round(c.y - NODE_H / 2 + k))));
setSelState(name);
setSelEdge(null);
};
@@ -108,6 +121,7 @@ export function AnimatorEditor() {
<div className="ng-editor-body">
<div style={{ flex: 1, minWidth: 0 }}>
<NodeGraphCanvas<AnimatorCanvasNode, AnimatorEdge>
+ apiRef={canvas}
nodes={nodes}
edges={edges}
selectedNode={selState}
diff --git a/desktop/src/panels/BtTreeEditor.tsx b/desktop/src/panels/BtTreeEditor.tsx
index f72bba730..6467b7d44 100644
--- a/desktop/src/panels/BtTreeEditor.tsx
+++ b/desktop/src/panels/BtTreeEditor.tsx
@@ -11,7 +11,7 @@
* drag-to-connect reparents a node under the drop target.
*/
import { useRef, useState, useSyncExternalStore } from 'react';
-import { Trash2 } from 'lucide-react';
+import { Plus, Trash2, Network } from 'lucide-react';
import {
btNodes, btEdges, addBtChild, addBtOrphan, removeBtNode, moveBtNode, setBtNodeField, reparentBtNode,
canHaveChildren, maxChildren,
@@ -19,7 +19,8 @@ import {
} from 'esengine';
import { BtDocument } from '@/bt/BtDocument';
import { t } from '@/i18n';
-import { NodeGraphCanvas, type CanvasNode, type MenuItem } from '@/components/NodeGraphCanvas';
+import { NodeGraphCanvas, type CanvasNode, type MenuItem, type NodeGraphCanvasApi } from '@/components/NodeGraphCanvas';
+import { EmptyState } from '@/components/EmptyState';
import { Select } from '@/components/Select';
import { SaveButton } from '@/components/SaveButton';
import { SuggestInput } from '@/components/SuggestInput';
@@ -64,9 +65,18 @@ export function BtTreeEditor() {
const [selected, setSelected] = useState<string | null>(null);
const [addType, setAddType] = useState<BtNodeType>('action');
const dragBefore = useRef<BtDefinition | null>(null);
+ const canvas = useRef<NodeGraphCanvasApi>(null);
if (!def || !filePath) {
- return <div className="panel ng-placeholder"><p>{t('ng.openHintPre')}<code>.esbt</code>{t('ng.openHintPost')}</p></div>;
+ return (
+ <div className="panel">
+ <EmptyState
+ icon={Network}
+ title={t('ng.btEmpty')}
+ hint={<>{t('ng.openHintPre')}<code>.esbt</code>{t('ng.openHintPost')}</>}
+ />
+ </div>
+ );
}
const nodes = btNodes(def).filter((n): n is BtCanvasNode => !!n.id);
@@ -86,6 +96,10 @@ export function BtTreeEditor() {
const toolbar = (
<>
+ <button type="button" className="ng-btn" title={t('bt.addNodeTip')}
+ onClick={(e) => { const r = e.currentTarget.getBoundingClientRect(); canvas.current?.openMenuAt(r.left, r.bottom + 2); }}>
+ <Plus size={13} strokeWidth={2} /> {t('bt.addNode')}
+ </button>
<span className="ng-doc-title">{filePath.split('/').pop()}</span>
<span style={{ flex: 1 }} />
{selected && def.root.id !== selected && (
@@ -103,6 +117,7 @@ export function BtTreeEditor() {
<div className="ng-editor-body">
<div style={{ flex: 1, minWidth: 0 }}>
<NodeGraphCanvas<BtCanvasNode, BtEdge>
+ apiRef={canvas}
nodes={nodes}
edges={edges}
selectedNode={selected}
diff --git a/desktop/src/panels/MaterialGraphEditor.tsx b/desktop/src/panels/MaterialGraphEditor.tsx
index 80bbe2068..fbd49f2fd 100644
--- a/desktop/src/panels/MaterialGraphEditor.tsx
+++ b/desktop/src/panels/MaterialGraphEditor.tsx
@@ -14,7 +14,7 @@
* them like any edge.
*/
import { useRef, useState, useSyncExternalStore } from 'react';
-import { Plus, Trash2 } from 'lucide-react';
+import { Plus, Trash2, Waypoints } from 'lucide-react';
import {
NODE_SPECS,
addNode,
@@ -30,6 +30,7 @@ import { t } from '@/i18n';
import { MaterialGraphDocument } from '@/material/MaterialGraphDocument';
import { saveMaterialGraph } from '@/material/openMaterialGraph';
import { ColorControl } from '@/components/ColorControl';
+import { EmptyState } from '@/components/EmptyState';
import { SaveButton } from '@/components/SaveButton';
import { NumField } from '@/components/NumField';
import {
@@ -88,7 +89,15 @@ export function MaterialGraphEditor() {
const canvas = useRef<NodeGraphCanvasApi>(null);
if (!graph || !filePath) {
- return <div className="panel ng-placeholder"><p>{t('mat.openHintPrefix')}<code>.esmatgraph</code>{t('mat.openHintSuffix')}</p></div>;
+ return (
+ <div className="panel">
+ <EmptyState
+ icon={Waypoints}
+ title={t('mat.graphEmpty')}
+ hint={<>{t('mat.openHintPrefix')}<code>.esmatgraph</code>{t('mat.openHintSuffix')}</>}
+ />
+ </div>
+ );
}
const nodes = graph.nodes as MatCanvasNode[];
diff --git a/desktop/src/panels/StateMachineEditor.tsx b/desktop/src/panels/StateMachineEditor.tsx
index 2f9e4fe5d..67bf4c651 100644
--- a/desktop/src/panels/StateMachineEditor.tsx
+++ b/desktop/src/panels/StateMachineEditor.tsx
@@ -14,7 +14,7 @@
* generic component shared with the behavior-tree editor.
*/
import { useMemo, useRef, useState, useSyncExternalStore } from 'react';
-import { Plus, Trash2 } from 'lucide-react';
+import { Plus, Trash2, Workflow } from 'lucide-react';
import {
fsmEdges, addState, removeState, moveState, renameState, setStateHook, setInitial,
addTransition, removeTransition, updateTransition, actionRefName, actionRefArg,
@@ -22,7 +22,8 @@ import {
} from 'esengine';
import { FsmGraphDocument } from '@/fsm/FsmGraphDocument';
import { t } from '@/i18n';
-import { NodeGraphCanvas, type CanvasNode } from '@/components/NodeGraphCanvas';
+import { NodeGraphCanvas, type CanvasNode, type NodeGraphCanvasApi } from '@/components/NodeGraphCanvas';
+import { EmptyState } from '@/components/EmptyState';
import { Select } from '@/components/Select';
import { SaveButton } from '@/components/SaveButton';
import { SuggestInput } from '@/components/SuggestInput';
@@ -59,9 +60,18 @@ export function StateMachineEditor() {
const [selState, setSelState] = useState<string | null>(null);
const [selEdge, setSelEdge] = useState<string | null>(null);
const dragBefore = useRef<FsmDefinition | null>(null);
+ const canvas = useRef<NodeGraphCanvasApi>(null);
if (!def || !filePath) {
- return <div className="panel ng-placeholder"><p>{t('ng.openHintPre')}<code>.esfsm</code>{t('ng.openHintPost')}</p></div>;
+ return (
+ <div className="panel">
+ <EmptyState
+ icon={Workflow}
+ title={t('ng.fsmEmpty')}
+ hint={<>{t('ng.openHintPre')}<code>.esfsm</code>{t('ng.openHintPost')}</>}
+ />
+ </div>
+ );
}
const nodes: FsmCanvasNode[] = def.states.map(s => ({ ...s, id: s.name }));
@@ -70,7 +80,12 @@ export function StateMachineEditor() {
const addStateAt = () => {
const name = uniqueName(def, 'State');
- FsmGraphDocument.edit('Add state', d => Object.assign(d, addState(d, name, 200, 120)));
+ // Drop the new state at the current view centre (not a hardcoded world coord
+ // that's off-screen after panning), with a small per-state cascade so repeated
+ // clicks don't stack every state on the same spot.
+ const c = canvas.current?.centerWorld() ?? { x: 200, y: 120 };
+ const k = (def.states.length % 6) * 26;
+ FsmGraphDocument.edit('Add state', d => Object.assign(d, addState(d, name, Math.round(c.x - NODE_W / 2 + k), Math.round(c.y - NODE_H / 2 + k))));
setSelState(name);
setSelEdge(null);
};
@@ -97,6 +112,7 @@ export function StateMachineEditor() {
<div className="ng-editor-body">
<div style={{ flex: 1, minWidth: 0 }}>
<NodeGraphCanvas<FsmCanvasNode, FsmEdge>
+ apiRef={canvas}
nodes={nodes}
edges={edges}
selectedNode={selState}