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): .esanimator animation-controller editor

esengine11a28ced3c5d
diff --git a/desktop/src/animator/AnimatorGraphDocument.ts b/desktop/src/animator/AnimatorGraphDocument.ts
new file mode 100644
index 000000000..a3898a7a3
--- /dev/null
+++ b/desktop/src/animator/AnimatorGraphDocument.ts
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AnimatorGraphDocument.ts
+ * @brief Reactive, undoable document for a `.esanimator` — the animation
+ * controller editor's model. Same AssetDocument contract as the FSM /
+ * material graph docs: panels subscribe via useSyncExternalStore
+ * (subscribe, getRevision); edits go through the SDK's pure animatorGraph
+ * ops via {@link edit} (one undo step each). A `.esanimator` IS the
+ * runtime AnimatorControllerDef, so there is no compile step on save.
+ */
+import type { AnimatorControllerDef } from 'esengine';
+import { AssetDocument } from '@/document/AssetDocument';
+
+class AnimatorGraphDocumentImpl extends AssetDocument<AnimatorControllerDef> {
+ open(def: AnimatorControllerDef, filePath: string | null): void {
+ this.openAsset(def, filePath);
+ }
+ openJson(raw: unknown, filePath: string | null): void {
+ this.open(raw as AnimatorControllerDef, filePath);
+ }
+ close(): void {
+ this.closeAsset();
+ }
+}
+
+export const AnimatorGraphDocument = new AnimatorGraphDocumentImpl('animator');
diff --git a/desktop/src/animator/openAnimatorController.ts b/desktop/src/animator/openAnimatorController.ts
new file mode 100644
index 000000000..24d08dc07
--- /dev/null
+++ b/desktop/src/animator/openAnimatorController.ts
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file openAnimatorController.ts
+ * @brief Open / create a `.esanimator` (the animation controller state machine).
+ * @details A `.esanimator` IS the runtime AnimatorControllerDef (states carry x/y
+ * layout the interpreter ignores), so there is no compile step — Save
+ * just writes the JSON. Create writes the definition + .meta.
+ */
+import { emptyAnimatorController } from 'esengine';
+import { AnimatorGraphDocument } from './AnimatorGraphDocument';
+import { ProjectStore } from '@/project/ProjectStore';
+import { confirmDiscardDoc } from '@/project/discardGuard';
+import { dockApi } from '@/layout/dockApi';
+import { baseName } from '@/project/assetMeta';
+import { Toasts } from '@/store/Toasts';
+import { t } from '@/i18n';
+
+/** Open an existing `.esanimator` into the controller editor and reveal the panel. */
+export async function openAnimatorController(path: string): Promise<void> {
+ // Already-open file: just front the panel — a reload would clobber unsaved edits.
+ if (AnimatorGraphDocument.isOpen && AnimatorGraphDocument.filePath === path) {
+ dockApi.openDocument('animatorcontroller', 'animatorcontroller', t('anim.tabTitle'));
+ return;
+ }
+ if (!(await confirmDiscardDoc(AnimatorGraphDocument.dirty, t('discard.openAsset', { name: baseName(path) })))) return;
+ try {
+ const text = await window.estella.fs.read(path);
+ AnimatorGraphDocument.openJson(JSON.parse(text), path);
+ dockApi.openDocument('animatorcontroller', 'animatorcontroller', t('anim.tabTitle'));
+ } catch (e) {
+ Toasts.push(t('anim.toastOpenFailed', { error: String(e) }), 'error');
+ }
+}
+
+/** Create a new `.esanimator` (+ .meta) in @p dir, then open it. */
+export async function createAnimatorController(dir: string): Promise<void> {
+ const folder = dir ? (dir.endsWith('/') ? dir : `${dir}/`) : '';
+ let rel = `${folder}NewAnimator.esanimator`;
+ for (let n = 1; ProjectStore.assetRef(rel); n++) rel = `${folder}NewAnimator-${n}.esanimator`;
+
+ const def = emptyAnimatorController();
+ try {
+ await window.estella.fs.write(rel, JSON.stringify(def, null, 2) + '\n');
+ await window.estella.fs.write(
+ rel + '.meta',
+ JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'animatorcontroller', importer: { autoMigrate: true } }, null, 2) + '\n',
+ );
+ } catch (e) {
+ Toasts.push(t('anim.toastCreateFailed', { error: String(e) }), 'error');
+ return;
+ }
+ await ProjectStore.refreshAssets();
+ Toasts.push(t('anim.toastCreated', { name: baseName(rel) }), 'info');
+ await openAnimatorController(rel);
+}
diff --git a/desktop/src/i18n/messages/animator.ts b/desktop/src/i18n/messages/animator.ts
new file mode 100644
index 000000000..ff1ce7c29
--- /dev/null
+++ b/desktop/src/i18n/messages/animator.ts
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file animator.ts — strings for the `.esanimator` animation-controller editor
+ * (AnimatorEditor.tsx). Shared node-graph chrome uses the `ng.*` keys.
+ */
+import { defineMessages } from './types';
+
+export const animatorMessages = defineMessages({
+ 'anim.tabTitle': { en: 'Animator', zh: '动画控制器' },
+ 'anim.emptyHint': { en: 'Right-click to add a state, drag between states to connect', zh: '右键添加状态,状态间拖拽连线' },
+ 'anim.stateBtn': { en: 'State', zh: '状态' },
+ 'anim.addStateTip': { en: 'Add a state', zh: '添加状态' },
+ 'anim.menuAddState': { en: 'Add state here', zh: '在此添加状态' },
+ 'anim.menuSetInitial': { en: 'Set as initial', zh: '设为初始态' },
+ 'anim.menuDeleteState': { en: 'Delete state', zh: '删除状态' },
+ 'anim.initialState': { en: 'Initial state', zh: '初始状态' },
+ 'anim.noMotion': { en: 'no motion', zh: '无动作' },
+ 'anim.always': { en: 'always', zh: '始终' },
+ 'anim.motionBlend': { en: 'blend', zh: '混合' },
+ 'anim.motionSpine': { en: 'spine', zh: '骨骼' },
+ 'anim.motionNested': { en: 'nested', zh: '子状态机' },
+
+ 'anim.inspStateTitle': { en: 'State', zh: '状态' },
+ 'anim.inspTransitionTitle': { en: 'Transition', zh: '转换' },
+ 'anim.clip': { en: 'Clip', zh: '剪辑' },
+ 'anim.phClip': { en: 'animation clip ref', zh: '动画剪辑引用' },
+ 'anim.speed': { en: 'Speed', zh: '速度' },
+ 'anim.loop': { en: 'Loop', zh: '循环' },
+ 'anim.target': { en: 'To', zh: '目标' },
+ 'anim.targetState': { en: 'Target state', zh: '目标状态' },
+ 'anim.hasExitTime': { en: 'Has exit time', zh: '播完再转' },
+ 'anim.conditions': { en: 'Conditions', zh: '条件' },
+ 'anim.addCondition': { en: 'Add condition', zh: '添加条件' },
+ 'anim.removeCondition': { en: 'Remove condition', zh: '移除条件' },
+ 'anim.param': { en: 'Parameter', zh: '参数' },
+ 'anim.op': { en: 'Op', zh: '运算' },
+
+ 'anim.params': { en: 'Parameters', zh: '参数' },
+ 'anim.addParam': { en: 'Add parameter', zh: '添加参数' },
+ 'anim.removeParam': { en: 'Remove parameter', zh: '移除参数' },
+ 'anim.noParams': { en: 'No parameters', zh: '暂无参数' },
+ 'anim.paramType': { en: 'Type', zh: '类型' },
+ 'anim.type.float': { en: 'Float', zh: '浮点' },
+ 'anim.type.bool': { en: 'Bool', zh: '布尔' },
+ 'anim.type.trigger': { en: 'Trigger', zh: '触发器' },
+
+ 'anim.toastOpenFailed': { en: 'Failed to open controller: {error}', zh: '打开控制器失败:{error}' },
+ 'anim.toastCreateFailed': { en: 'Failed to create controller: {error}', zh: '创建控制器失败:{error}' },
+ 'anim.toastCreated': { en: 'Created {name}', zh: '已创建 {name}' },
+});
diff --git a/desktop/src/i18n/messages/content.ts b/desktop/src/i18n/messages/content.ts
index 77bd6a35a..a3c8bdb88 100644
--- a/desktop/src/i18n/messages/content.ts
+++ b/desktop/src/i18n/messages/content.ts
@@ -66,6 +66,7 @@ export const contentMessages = defineMessages({
'cb.menuNewMaterial': { en: 'New Material', zh: '新建材质' },
'cb.menuNewMaterialGraph': { en: 'New Material Graph', zh: '新建材质图' },
'cb.menuNewStateMachine': { en: 'New State Machine', zh: '新建状态机' },
+ 'cb.menuNewAnimatorController': { en: 'New Animation Controller', zh: '新建动画控制器' },
'cb.menuNewBehaviorTree': { en: 'New Behavior Tree', zh: '新建行为树' },
'cb.menuShowInExplorer': { en: 'Show in Explorer', zh: '在资源管理器中显示' },
'cb.menuOpen': { en: 'Open', zh: '打开' },
diff --git a/desktop/src/i18n/messages/index.ts b/desktop/src/i18n/messages/index.ts
index 79b3cf093..c522b5826 100644
--- a/desktop/src/i18n/messages/index.ts
+++ b/desktop/src/i18n/messages/index.ts
@@ -37,6 +37,7 @@ import { mixerMessages } from './mixer';
import { materialMessages } from './material';
import { projectMessages } from './project';
import { controllerMessages } from './controllers';
+import { animatorMessages } from './animator';
/** Every per-area module, for the uniqueness guard in i18n.test.ts. */
export const messageModules = {
@@ -59,6 +60,7 @@ export const messageModules = {
material: materialMessages,
project: projectMessages,
controllers: controllerMessages,
+ animator: animatorMessages,
} as const;
export const editorMessages = {
@@ -81,4 +83,5 @@ export const editorMessages = {
...materialMessages,
...projectMessages,
...controllerMessages,
+ ...animatorMessages,
} as const;
diff --git a/desktop/src/layout/DockLayout.tsx b/desktop/src/layout/DockLayout.tsx
index bc494c910..9d811dc3e 100644
--- a/desktop/src/layout/DockLayout.tsx
+++ b/desktop/src/layout/DockLayout.tsx
@@ -28,6 +28,7 @@ import { UIWidgetsPanel } from '@/panels/UIWidgetsPanel';
import { ControllersPanel } from '@/panels/ControllersPanel';
import { MaterialGraphEditor } from '@/panels/MaterialGraphEditor';
import { StateMachineEditor } from '@/panels/StateMachineEditor';
+import { AnimatorEditor } from '@/panels/AnimatorEditor';
import { BtTreeEditor } from '@/panels/BtTreeEditor';
import { ProfilerPanel } from '@/panels/ProfilerPanel';
import { Perf } from '@/components/Perf';
@@ -63,6 +64,7 @@ const components: Record<string, FC<IDockviewPanelProps>> = {
controllers: (p) => panel('controllers', p.api, <ControllersPanel />),
materialgraph: (p) => panel('materialgraph', p.api, <MaterialGraphEditor />),
statemachine: (p) => panel('statemachine', p.api, <StateMachineEditor />),
+ animatorcontroller: (p) => panel('animatorcontroller', p.api, <AnimatorEditor />),
behaviortree: (p) => panel('behaviortree', p.api, <BtTreeEditor />),
// Profiler skips the Perf wrapper (it must not profile its own render).
profiler: (p) => (
@@ -169,6 +171,7 @@ const PANEL_TITLES: Record<string, () => string> = {
controllers: () => t('panel.controllers'),
materialgraph: () => t('mat.panelTitle'),
statemachine: () => t('fsm.tabTitle'),
+ animatorcontroller: () => t('anim.tabTitle'),
behaviortree: () => t('bt.tabTitle'),
};
diff --git a/desktop/src/layout/panelDirty.ts b/desktop/src/layout/panelDirty.ts
index 04d7cdb84..7555e1ab8 100644
--- a/desktop/src/layout/panelDirty.ts
+++ b/desktop/src/layout/panelDirty.ts
@@ -7,6 +7,7 @@
* an AssetDocument singleton (uniform subscribe + dirty).
*/
import { FsmGraphDocument } from '@/fsm/FsmGraphDocument';
+import { AnimatorGraphDocument } from '@/animator/AnimatorGraphDocument';
import { BtDocument } from '@/bt/BtDocument';
import { MaterialGraphDocument } from '@/material/MaterialGraphDocument';
import { TilesetDocument } from '@/tileset/TilesetDocument';
@@ -24,6 +25,7 @@ export interface DirtySource {
const SOURCES: Record<string, DirtySource> = {
statemachine: { subscribe: FsmGraphDocument.subscribe, isDirty: () => FsmGraphDocument.dirty, discard: () => FsmGraphDocument.close() },
+ animatorcontroller: { subscribe: AnimatorGraphDocument.subscribe, isDirty: () => AnimatorGraphDocument.dirty, discard: () => AnimatorGraphDocument.close() },
behaviortree: { subscribe: BtDocument.subscribe, isDirty: () => BtDocument.dirty, discard: () => BtDocument.close() },
materialgraph: { subscribe: MaterialGraphDocument.subscribe, isDirty: () => MaterialGraphDocument.dirty, discard: () => MaterialGraphDocument.close() },
tileset: { subscribe: TilesetDocument.subscribe, isDirty: () => TilesetDocument.dirty, discard: () => TilesetDocument.close() },
diff --git a/desktop/src/panels/AnimatorEditor.tsx b/desktop/src/panels/AnimatorEditor.tsx
new file mode 100644
index 000000000..e7a516d59
--- /dev/null
+++ b/desktop/src/panels/AnimatorEditor.tsx
@@ -0,0 +1,303 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AnimatorEditor.tsx
+ * @brief The `.esanimator` animation-controller editor — states as nodes,
+ * transitions as condition-guarded edges, on the shared <NodeGraphCanvas>.
+ * All mutation goes through the pure, tested SDK animatorGraph ops on the
+ * reactive AnimatorGraphDocument (one undo step each). A `.esanimator` IS
+ * the runtime AnimatorControllerDef (states carry x/y layout the
+ * interpreter ignores), so Save just writes JSON.
+ *
+ * Animator specifics vs the FSM editor: a global Parameters list, a state
+ * motion (sprite clip + speed/loop) instead of hooks, and transitions
+ * carrying an AND-list of typed parameter conditions + an exit-time flag.
+ */
+import { useRef, useState, useSyncExternalStore } from 'react';
+import { Plus, Trash2, Save, X } from 'lucide-react';
+import {
+ animatorEdges,
+ addAnimatorState, removeAnimatorState, moveAnimatorState, renameAnimatorState, setAnimatorInitial,
+ setAnimatorStateClip, setAnimatorStateProps,
+ addAnimatorTransition, removeAnimatorTransition, updateAnimatorTransition, setAnimatorConditions,
+ addAnimatorParam, removeAnimatorParam, updateAnimatorParam,
+ type AnimatorControllerDef, type AnimatorState, type AnimatorEdge,
+ type AnimatorCondition, type AnimatorTransition, type AnimatorParamType,
+} from 'esengine';
+import { AnimatorGraphDocument } from '@/animator/AnimatorGraphDocument';
+import { t } from '@/i18n';
+import { NodeGraphCanvas, type CanvasNode } from '@/components/NodeGraphCanvas';
+import { Select } from '@/components/Select';
+import { DirtyDot } from '@/components/DirtyDot';
+
+type AnimatorCanvasNode = AnimatorState & CanvasNode;
+
+const NODE_W = 156;
+const NODE_H = 60;
+const NUM_OPS = ['gt', 'lt', 'eq', 'neq'] as const;
+const ALL_OPS = ['gt', 'lt', 'eq', 'neq', 'true', 'false', 'trigger'] as const;
+const OP_SYM: Record<string, string> = { gt: '>', lt: '<', eq: '=', neq: '≠', true: '=true', false: '=false', trigger: '⚡' };
+const PARAM_TYPES: AnimatorParamType[] = ['float', 'bool', 'trigger'];
+
+function condLabel(c: AnimatorCondition): string {
+ if (c.op === 'gt' || c.op === 'lt' || c.op === 'eq' || c.op === 'neq') return `${c.param}${OP_SYM[c.op]}${c.value}`;
+ if (c.op === 'trigger') return `⚡${c.param}`;
+ return `${c.param}${OP_SYM[c.op]}`;
+}
+
+/** A short human summary of a transition's enabling conditions, for the edge label. */
+function edgeSummary(tr: AnimatorTransition): string {
+ const parts = tr.conditions.map(condLabel);
+ if (tr.hasExitTime) parts.push('⏱');
+ return parts.join(' ') || t('anim.always');
+}
+
+/** Short display for a state's motion (a sprite clip's file name, or the kind). */
+function motionLabel(s: AnimatorState): string {
+ if (s.clip) return s.clip.split('/').pop()?.replace(/\.[^.]+$/, '') ?? s.clip;
+ if (s.blend) return t('anim.motionBlend');
+ if (s.spine) return t('anim.motionSpine');
+ if (s.stateMachine) return t('anim.motionNested');
+ return '';
+}
+
+export function AnimatorEditor() {
+ useSyncExternalStore(AnimatorGraphDocument.subscribe, AnimatorGraphDocument.getRevision);
+ const def = AnimatorGraphDocument.asset;
+ const filePath = AnimatorGraphDocument.filePath;
+ const dirty = AnimatorGraphDocument.dirty;
+
+ const [selState, setSelState] = useState<string | null>(null);
+ const [selEdge, setSelEdge] = useState<string | null>(null);
+ const dragBefore = useRef<AnimatorControllerDef | null>(null);
+
+ if (!def || !filePath) {
+ return <div className="panel ng-placeholder"><p>{t('ng.openHintPre')}<code>.esanimator</code>{t('ng.openHintPost')}</p></div>;
+ }
+
+ const nodes: AnimatorCanvasNode[] = def.states.map((s) => ({ ...s, id: s.name }));
+ const edges: AnimatorEdge[] = animatorEdges(def);
+ const byName = new Map(def.states.map((s) => [s.name, s]));
+
+ const addStateAt = () => {
+ const name = uniqueName(def, 'State');
+ AnimatorGraphDocument.edit('Add state', (d) => Object.assign(d, addAnimatorState(d, name, 200, 120)));
+ setSelState(name);
+ setSelEdge(null);
+ };
+ const deleteSelected = () => {
+ if (selState) { AnimatorGraphDocument.edit('Delete state', (d) => Object.assign(d, removeAnimatorState(d, selState))); setSelState(null); }
+ else if (selEdge) { const p = parseEdgeId(selEdge); if (p) AnimatorGraphDocument.edit('Delete transition', (d) => Object.assign(d, removeAnimatorTransition(d, p.from, p.index))); setSelEdge(null); }
+ };
+ const save = () => {
+ void window.estella.fs.write(filePath, JSON.stringify(def, null, 2) + '\n').then(() => AnimatorGraphDocument.markSaved());
+ };
+
+ const toolbar = (
+ <>
+ <button type="button" className="ng-btn" onClick={addStateAt} title={t('anim.addStateTip')}><Plus size={13} strokeWidth={2} /> {t('anim.stateBtn')}</button>
+ {(selState || selEdge) && <button type="button" className="ng-btn" title={t('ng.deleteSelected')} onClick={deleteSelected}><Trash2 size={13} strokeWidth={1.9} /></button>}
+ <span className="ng-doc-title">{filePath.split('/').pop()}{dirty && <DirtyDot />}</span>
+ <span style={{ flex: 1 }} />
+ <button type="button" className="ng-btn primary" disabled={!dirty} onClick={save}><Save size={13} strokeWidth={1.9} /> {t('ng.save')}</button>
+ </>
+ );
+
+ return (
+ <div className="ng-editor">
+ <div className="ng-editor-body">
+ <div style={{ flex: 1, minWidth: 0 }}>
+ <NodeGraphCanvas<AnimatorCanvasNode, AnimatorEdge>
+ nodes={nodes}
+ edges={edges}
+ selectedNode={selState}
+ selectedEdge={selEdge}
+ nodeSize={() => ({ width: NODE_W, height: NODE_H })}
+ allowSelfLoop
+ onSelectNode={setSelState}
+ onSelectEdge={setSelEdge}
+ onMoveNodeStart={() => { dragBefore.current = def; }}
+ onMoveNode={(id, x, y) => AnimatorGraphDocument.replaceAsset(moveAnimatorState(def, id, x, y), { dirty: true })}
+ onMoveNodeEnd={() => {
+ const after = AnimatorGraphDocument.asset;
+ const before = dragBefore.current;
+ if (after && before) AnimatorGraphDocument.recordEdit('Move state', before, after);
+ }}
+ onConnect={(from, to) => AnimatorGraphDocument.edit('Add transition', (d) => Object.assign(d, addAnimatorTransition(d, from, to)))}
+ onDeleteNode={(id) => { AnimatorGraphDocument.edit('Delete state', (d) => Object.assign(d, removeAnimatorState(d, id))); setSelState(null); }}
+ onDeleteEdge={(id) => { const p = parseEdgeId(id); if (p) AnimatorGraphDocument.edit('Delete transition', (d) => Object.assign(d, removeAnimatorTransition(d, p.from, p.index))); setSelEdge(null); }}
+ menuItems={(target) => target.kind === 'canvas'
+ ? [{ label: t('anim.menuAddState'), onClick: () => { const name = uniqueName(def, 'State'); AnimatorGraphDocument.edit('Add state', (d) => Object.assign(d, addAnimatorState(d, name, target.x, target.y))); setSelState(name); setSelEdge(null); } }]
+ : [
+ { label: t('anim.menuSetInitial'), disabled: def.initialState === target.nodeId, onClick: () => AnimatorGraphDocument.edit('Set initial', (d) => Object.assign(d, setAnimatorInitial(d, target.nodeId!))) },
+ { sep: true },
+ { label: t('anim.menuDeleteState'), danger: true, onClick: () => { AnimatorGraphDocument.edit('Delete state', (d) => Object.assign(d, removeAnimatorState(d, target.nodeId!))); setSelState(null); } },
+ ]}
+ toolbar={toolbar}
+ emptyHint={t('anim.emptyHint')}
+ renderEdgeLabel={(e) => <>{edgeSummary(e.transition)}</>}
+ renderNode={(n, sel) => {
+ const isInitial = def.initialState === n.name;
+ const motion = motionLabel(n);
+ return (
+ <div className={`ng-node-box${sel ? ' sel' : ''}`} style={!sel && isInitial ? { borderColor: 'var(--run)' } : undefined}>
+ <div className="ng-node-head">
+ {isInitial && <span title={t('anim.initialState')} className="ng-node-badge" style={{ color: 'var(--run)' }}>▶</span>}
+ <span className="ng-node-name">{n.name}</span>
+ </div>
+ <div className="ng-node-sub">{motion || <span style={{ opacity: 0.4 }}>{t('anim.noMotion')}</span>}</div>
+ </div>
+ );
+ }}
+ />
+ </div>
+
+ <div className="ng-inspector">
+ <ParametersInspector def={def} />
+ {selState && byName.get(selState) && <StateInspector def={def} state={byName.get(selState)!} onRename={setSelState} />}
+ {selEdge && parseEdgeId(selEdge) && <TransitionInspector def={def} edgeId={selEdge} />}
+ </div>
+ </div>
+ </div>
+ );
+}
+
+function ParametersInspector({ def }: { def: AnimatorControllerDef }) {
+ const add = () => AnimatorGraphDocument.edit('Add parameter', (d) => Object.assign(d, addAnimatorParam(d, uniqueParam(def), 'float')));
+ return (
+ <div>
+ <div className="ng-insp-title">
+ {t('anim.params')}
+ <button type="button" className="ng-btn" style={{ marginLeft: 'auto' }} title={t('anim.addParam')} onClick={add}><Plus size={12} /></button>
+ </div>
+ {def.parameters.length === 0 && <div className="ng-insp-sub" style={{ opacity: 0.5 }}>{t('anim.noParams')}</div>}
+ {def.parameters.map((p) => (
+ <div className="ng-row" key={p.name}>
+ <input
+ className="ng-input" style={{ flex: 1 }} defaultValue={p.name} key={`pn-${p.name}`} spellCheck={false}
+ onBlur={(e) => { const v = e.target.value.trim(); if (v && v !== p.name) AnimatorGraphDocument.edit('Rename parameter', (d) => Object.assign(d, updateAnimatorParam(d, p.name, { name: v }))); }}
+ />
+ <Select
+ ariaLabel={t('anim.paramType')}
+ style={{ width: 84 }}
+ value={p.type}
+ options={PARAM_TYPES.map((ty) => ({ value: ty, label: t(`anim.type.${ty}` as 'anim.type.float') }))}
+ onChange={(ty) => AnimatorGraphDocument.edit('Set parameter type', (d) => Object.assign(d, updateAnimatorParam(d, p.name, { type: ty as AnimatorParamType })))}
+ />
+ <button type="button" className="ng-btn" title={t('anim.removeParam')} onClick={() => AnimatorGraphDocument.edit('Remove parameter', (d) => Object.assign(d, removeAnimatorParam(d, p.name)))}><X size={12} /></button>
+ </div>
+ ))}
+ </div>
+ );
+}
+
+function StateInspector({ def, state, onRename }: { def: AnimatorControllerDef; state: AnimatorState; onRename: (n: string) => void }) {
+ const isInitial = def.initialState === state.name;
+ return (
+ <div>
+ <div className="ng-insp-title">{t('anim.inspStateTitle')}</div>
+ <label className="ng-field">{t('ng.name')}
+ <input className="ng-input" defaultValue={state.name} key={state.name}
+ onBlur={(e) => { const v = e.target.value.trim(); if (v && v !== state.name) { AnimatorGraphDocument.edit('Rename state', (d) => Object.assign(d, renameAnimatorState(d, state.name, v))); onRename(v); } }} />
+ </label>
+ <label className="ng-check-row">
+ <input type="checkbox" checked={isInitial} disabled={isInitial}
+ onChange={() => AnimatorGraphDocument.edit('Set initial', (d) => Object.assign(d, setAnimatorInitial(d, state.name)))} />
+ {t('anim.initialState')}
+ </label>
+ <label className="ng-field">{t('anim.clip')}
+ <input className="ng-input" defaultValue={state.clip ?? ''} key={`clip-${state.name}-${state.clip ?? ''}`} spellCheck={false}
+ placeholder={t('anim.phClip')}
+ onBlur={(e) => { const v = e.target.value.trim(); if (v !== (state.clip ?? '')) AnimatorGraphDocument.edit('Set clip', (d) => Object.assign(d, setAnimatorStateClip(d, state.name, v))); }} />
+ </label>
+ <div className="ng-row">
+ <label className="ng-field" style={{ flex: 1 }}>{t('anim.speed')}
+ <input className="ng-input" type="number" step={0.1} defaultValue={state.speed ?? 1} key={`sp-${state.name}`}
+ onBlur={(e) => { const v = Number(e.target.value); if (Number.isFinite(v)) AnimatorGraphDocument.edit('Set speed', (d) => Object.assign(d, setAnimatorStateProps(d, state.name, { speed: v }))); }} />
+ </label>
+ <label className="ng-check-row">
+ <input type="checkbox" checked={state.loop ?? false}
+ onChange={(e) => AnimatorGraphDocument.edit('Set loop', (d) => Object.assign(d, setAnimatorStateProps(d, state.name, { loop: e.target.checked })))} />
+ {t('anim.loop')}
+ </label>
+ </div>
+ </div>
+ );
+}
+
+function TransitionInspector({ def, edgeId }: { def: AnimatorControllerDef; edgeId: string }) {
+ const parsed = parseEdgeId(edgeId);
+ if (!parsed) return null;
+ const src = def.states.find((s) => s.name === parsed.from);
+ const tr = src?.transitions[parsed.index];
+ if (!tr) return null;
+ const patch = (p: Partial<AnimatorTransition>) => AnimatorGraphDocument.edit('Edit transition', (d) => Object.assign(d, updateAnimatorTransition(d, parsed.from, parsed.index, p)));
+ const setConds = (conds: AnimatorCondition[]) => AnimatorGraphDocument.edit('Edit conditions', (d) => Object.assign(d, setAnimatorConditions(d, parsed.from, parsed.index, conds)));
+ const firstParam = def.parameters[0]?.name ?? '';
+ return (
+ <div>
+ <div className="ng-insp-title">{t('anim.inspTransitionTitle')}</div>
+ <label className="ng-field">{t('anim.target')}
+ <Select ariaLabel={t('anim.targetState')} value={tr.to} options={def.states.map((s) => ({ value: s.name }))} onChange={(v) => patch({ to: v })} />
+ </label>
+ <label className="ng-check-row">
+ <input type="checkbox" checked={tr.hasExitTime ?? false} onChange={(e) => patch({ hasExitTime: e.target.checked || undefined })} />
+ {t('anim.hasExitTime')}
+ </label>
+ <div className="ng-insp-sub">
+ {t('anim.conditions')}
+ <button type="button" className="ng-btn" style={{ marginLeft: 'auto' }} title={t('anim.addCondition')} disabled={!firstParam}
+ onClick={() => setConds([...tr.conditions, { param: firstParam, op: 'trigger' }])}><Plus size={12} /></button>
+ </div>
+ {tr.conditions.length === 0 && <div className="ng-insp-sub" style={{ opacity: 0.5 }}>{t('anim.always')}</div>}
+ {tr.conditions.map((c, ci) => (
+ <div className="ng-row" key={ci}>
+ <Select
+ ariaLabel={t('anim.param')} style={{ flex: 1 }} value={c.param}
+ options={def.parameters.map((p) => ({ value: p.name }))}
+ onChange={(v) => setConds(tr.conditions.map((x, i) => (i === ci ? { ...x, param: v } : x)))}
+ />
+ <Select
+ ariaLabel={t('anim.op')} style={{ width: 72 }} value={c.op}
+ options={ALL_OPS.map((op) => ({ value: op, label: OP_SYM[op] }))}
+ onChange={(op) => setConds(tr.conditions.map((x, i) => (i === ci ? makeCond(x.param, op as typeof ALL_OPS[number], 'value' in x ? x.value : 0) : x)))}
+ />
+ {(NUM_OPS as readonly string[]).includes(c.op) && (
+ <input className="ng-input" style={{ width: 54 }} type="number" step={0.1} defaultValue={'value' in c ? c.value : 0} key={`cv-${ci}-${c.op}`}
+ onBlur={(e) => { const v = Number(e.target.value); if (Number.isFinite(v)) setConds(tr.conditions.map((x, i) => (i === ci ? makeCond(x.param, x.op as typeof NUM_OPS[number], v) : x))); }} />
+ )}
+ <button type="button" className="ng-btn" title={t('anim.removeCondition')} onClick={() => setConds(tr.conditions.filter((_, i) => i !== ci))}><X size={12} /></button>
+ </div>
+ ))}
+ </div>
+ );
+}
+
+// -- helpers ----------------------------------------------------------------
+
+function makeCond(param: string, op: typeof ALL_OPS[number], value: number): AnimatorCondition {
+ if (op === 'true' || op === 'false' || op === 'trigger') return { param, op };
+ return { param, op, value: Number.isFinite(value) ? value : 0 };
+}
+
+function parseEdgeId(id: string): { from: string; index: number } | null {
+ const m = /^(.*)->.*#(\d+)$/.exec(id);
+ return m ? { from: m[1], index: Number(m[2]) } : null;
+}
+
+function uniqueName(def: AnimatorControllerDef, base: string): string {
+ if (!def.states.some((s) => s.name === base)) return base;
+ for (let i = 1; ; i++) {
+ const n = `${base}${i}`;
+ if (!def.states.some((s) => s.name === n)) return n;
+ }
+}
+
+function uniqueParam(def: AnimatorControllerDef): string {
+ const base = 'Param';
+ if (!def.parameters.some((p) => p.name === base)) return base;
+ for (let i = 1; ; i++) {
+ const n = `${base}${i}`;
+ if (!def.parameters.some((p) => p.name === n)) return n;
+ }
+}
diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsx
index e7742a8c3..55eb00ca7 100644
--- a/desktop/src/panels/ContentBrowser.tsx
+++ b/desktop/src/panels/ContentBrowser.tsx
@@ -26,6 +26,7 @@ import { BUILTIN_SHADER_TEMPLATES } from 'esengine';
import { createMaterial, createMaterialInstance } from '@/material/openMaterial';
import { createMaterialGraph } from '@/material/openMaterialGraph';
import { createStateMachine } from '@/fsm/openStateMachine';
+import { createAnimatorController } from '@/animator/openAnimatorController';
import { onAssetReveal } from '@/project/assetReveal';
import { createBehaviorTree } from '@/bt/openBehaviorTree';
import { createAnimationClip } from '@/timeline/openClip';
@@ -875,6 +876,7 @@ export function ContentBrowser() {
},
{ label: t('cb.menuNewMaterialGraph'), onClick: () => void createMaterialGraph(cwd) },
{ label: t('cb.menuNewStateMachine'), onClick: () => void createStateMachine(cwd) },
+ { label: t('cb.menuNewAnimatorController'), onClick: () => void createAnimatorController(cwd) },
{ label: t('cb.menuNewBehaviorTree'), onClick: () => void createBehaviorTree(cwd) },
{ sep: true },
{ label: t('cb.menuShowInExplorer'), onClick: () => void showInExplorer(cwd) },
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index f04fd9ade..f2b6ce820 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -118,6 +118,7 @@ function metaTypeToSlot(metaType: string | undefined): string | null {
case 'tilemap': return 'tilemap';
case 'tileset': return 'tileset';
case 'statemachine': return 'statemachine';
+ case 'animatorcontroller': return 'animatorcontroller';
case 'behaviortree': return 'behaviortree';
default: return null;
}
diff --git a/desktop/src/project/assetOpen.ts b/desktop/src/project/assetOpen.ts
index 95ff641ac..0869c6e9e 100644
--- a/desktop/src/project/assetOpen.ts
+++ b/desktop/src/project/assetOpen.ts
@@ -18,6 +18,7 @@ import { openTileset } from '@/tileset/openTileset';
import { openMaterial } from '@/material/openMaterial';
import { openMaterialGraph } from '@/material/openMaterialGraph';
import { openStateMachine } from '@/fsm/openStateMachine';
+import { openAnimatorController } from '@/animator/openAnimatorController';
import { openBehaviorTree } from '@/bt/openBehaviorTree';
/** Open action per asset type; types absent here aren't double-click-openable. */
@@ -33,5 +34,6 @@ export const ASSET_OPEN: Partial<Record<AssetType, (path: string, name: string)
material: (path) => void openMaterial(path),
materialgraph: (path) => void openMaterialGraph(path),
statemachine: (path) => void openStateMachine(path),
+ animatorcontroller: (path) => void openAnimatorController(path),
behaviortree: (path) => void openBehaviorTree(path),
};
diff --git a/desktop/src/project/assetTypes.ts b/desktop/src/project/assetTypes.ts
index c4a9d9a2b..954ecd72a 100644
--- a/desktop/src/project/assetTypes.ts
+++ b/desktop/src/project/assetTypes.ts
@@ -13,7 +13,7 @@
*/
import {
Folder, Film, Image, FileImage, PersonStanding, Music,
- Component, Blend, FileCode2, Clapperboard, Grid3x3, File, Workflow, Gamepad2, GitBranch, ListTree, Languages, Images, Video,
+ Component, Blend, FileCode2, Clapperboard, Grid3x3, File, Workflow, Gamepad2, GitBranch, ListTree, Languages, Images, Video, Waypoints,
type LucideIcon,
} from 'lucide-react';
import type { AssetType } from '@/types';
@@ -52,6 +52,7 @@ export const ASSET_TYPES: Record<AssetType, AssetTypeDef> = {
tilemap: { extensions: ['estilemap'], badge: 'TMP', icon: Grid3x3, tint: '#7fa6c4' },
inputmap: { extensions: ['inputmap'], badge: 'INP', icon: Gamepad2, tint: '#a0b88f' },
statemachine: { extensions: ['esfsm'], badge: 'FSM', icon: GitBranch, tint: '#8fb0a0' },
+ animatorcontroller: { extensions: ['esanimator'], badge: 'ANC', icon: Waypoints, tint: '#c0a08f' },
behaviortree: { extensions: ['esbt'], badge: 'BT', icon: ListTree, tint: '#8fa0c4' },
locale: { extensions: ['eslocale'], badge: 'LOC', icon: Languages, tint: '#b8a98a' },
file: { badge: '', icon: File, tint: 'var(--text-dim)' },
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index 7077092e0..43090b2ad 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -189,6 +189,7 @@ export type AssetType =
| 'tilemap'
| 'inputmap'
| 'statemachine'
+ | 'animatorcontroller'
| 'behaviortree'
| 'locale'
| 'file';
diff --git a/examples/sprite-animation/assets/animations/player.esanimator b/examples/sprite-animation/assets/animations/player.esanimator
new file mode 100644
index 000000000..1172fa0bd
--- /dev/null
+++ b/examples/sprite-animation/assets/animations/player.esanimator
@@ -0,0 +1,13 @@
+{
+ "parameters": [
+ { "name": "Speed", "type": "float" },
+ { "name": "Jump", "type": "trigger" }
+ ],
+ "states": [
+ { "name": "Idle", "x": 120, "y": 130, "clip": "assets/animations/idle.esanim", "loop": true, "transitions": [ { "to": "Run", "conditions": [ { "param": "Speed", "op": "gt", "value": 0.1 } ] } ] },
+ { "name": "Run", "x": 380, "y": 130, "clip": "assets/animations/walk.esanim", "loop": true, "transitions": [ { "to": "Idle", "conditions": [ { "param": "Speed", "op": "lt", "value": 0.1 } ] } ] },
+ { "name": "Jump", "x": 250, "y": 320, "transitions": [ { "to": "Idle", "hasExitTime": true, "conditions": [] } ] }
+ ],
+ "initialState": "Idle",
+ "anyStateTransitions": [ { "to": "Jump", "conditions": [ { "param": "Jump", "op": "trigger" } ] } ]
+}
diff --git a/examples/sprite-animation/assets/animations/player.esanimator.meta b/examples/sprite-animation/assets/animations/player.esanimator.meta
new file mode 100644
index 000000000..db19cffbd
--- /dev/null
+++ b/examples/sprite-animation/assets/animations/player.esanimator.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "bc4b1031-3d5b-451c-8bb1-1fd64ff86f19",
+ "version": "1.0",
+ "type": "animatorcontroller",
+ "importer": { "autoMigrate": true }
+}