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
feat(anim): AnimatorController graph model + .esanimator asset type
esengined425020ca7af
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 0d9b2aea6..c6f5423a2 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1266 stable · 17 beta · 0 deprecated+Symbols: 1283 stable · 17 beta · 0 deprecated## ABI_LAYOUT_HASH — const```@@ -306,6 +306,15 @@ currentState: stringenabled: boolean```+## AnimatorEdge — interface+```+from: string+id: string+index: number+to: string+transition: AnimatorTransition+```+## AnimatorEvalResult — interface```consumedTriggers: string[]@@ -356,6 +365,8 @@ speed: number | undefinedspine: AnimatorSpineMotion | undefinedstateMachine: AnimatorSubMachine | undefinedtransitions: AnimatorTransition[]+x: number | undefined+y: number | undefined```## AnimatorSubMachine — interface@@ -7717,6 +7728,21 @@ TransformData(ref: FsmActionRef | undefined): string```+## addAnimatorParam — function+```+(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef+```++## addAnimatorState — function+```+(def: AnimatorControllerDef, name: string, x?: number, y?: number): AnimatorControllerDef+```++## addAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef+```+## addBtChild — function```(def: BtDefinition, parentId: string, type: BtNodeType, x?: number, y?: number): BtDefinition@@ -7802,6 +7828,11 @@ AiRegistry<AiContext>AnimationPlugin```+## animatorEdges — function+```+(def: AnimatorControllerDef): AnimatorEdge[]+```+## applyAudioProjectConfig — function```(audio: AudioAPI, config: AudioProjectConfig | undefined): void@@ -8282,6 +8313,11 @@ PluralSelectorDragPlugin```+## emptyAnimatorController — function+```+(): AnimatorControllerDef+```+## emptyBt — function```(): BtDefinition@@ -8892,6 +8928,11 @@ Mesh2DPlugin(raw: SceneData): SceneMigrationResult```+## moveAnimatorState — function+```+(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef+```+## moveBtNode — function```(def: BtDefinition, id: string, x: number, y: number): BtDefinition@@ -9217,6 +9258,21 @@ PrefabsPlugin(compData: SceneComponentData, entityMap: Map<number, Entity>): void```+## removeAnimatorParam — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## removeAnimatorState — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## removeAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef+```+## removeBtNode — function```(def: BtDefinition, id: string): BtDefinition@@ -9242,6 +9298,11 @@ PrefabsPlugin(def: FsmDefinition, from: string, index: number): FsmDefinition```+## renameAnimatorState — function+```+(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef+```+## renameState — function```(def: FsmDefinition, oldName: string, newName: string): FsmDefinition@@ -9397,6 +9458,26 @@ Plugin(asset: TimelineAsset, indent?: number): string```+## setAnimatorConditions — function+```+(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef+```++## setAnimatorInitial — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## setAnimatorStateClip — function+```+(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef+```++## setAnimatorStateProps — function+```+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; }): AnimatorControllerDef+```+## setBtNodeField — function```(def: BtDefinition, id: string, patch: Partial<BtNode>): BtDefinition@@ -9757,6 +9838,16 @@ UIRenderOrderPlugin(id: string): void```+## updateAnimatorParam — function+```+(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef+```++## updateAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef+```+## updateCameraAspectRatio — function```(world: World, aspectRatio: number): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 42fb24275..20b3394d2 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1265 stable · 19 beta · 0 deprecated+Symbols: 1282 stable · 19 beta · 0 deprecated## ANCHOR_AXES — const```@@ -301,6 +301,15 @@ currentState: stringenabled: boolean```+## AnimatorEdge — interface+```+from: string+id: string+index: number+to: string+transition: AnimatorTransition+```+## AnimatorEvalResult — interface```consumedTriggers: string[]@@ -351,6 +360,8 @@ speed: number | undefinedspine: AnimatorSpineMotion | undefinedstateMachine: AnimatorSubMachine | undefinedtransitions: AnimatorTransition[]+x: number | undefined+y: number | undefined```## AnimatorSubMachine — interface@@ -7712,6 +7723,21 @@ TransformData(ref: FsmActionRef | undefined): string```+## addAnimatorParam — function+```+(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef+```++## addAnimatorState — function+```+(def: AnimatorControllerDef, name: string, x?: number, y?: number): AnimatorControllerDef+```++## addAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef+```+## addBtChild — function```(def: BtDefinition, parentId: string, type: BtNodeType, x?: number, y?: number): BtDefinition@@ -7797,6 +7823,11 @@ AiRegistry<AiContext>AnimationPlugin```+## animatorEdges — function+```+(def: AnimatorControllerDef): AnimatorEdge[]+```+## applyAudioProjectConfig — function```(audio: AudioAPI, config: AudioProjectConfig | undefined): void@@ -8277,6 +8308,11 @@ PluralSelectorDragPlugin```+## emptyAnimatorController — function+```+(): AnimatorControllerDef+```+## emptyBt — function```(): BtDefinition@@ -8892,6 +8928,11 @@ Mesh2DPlugin(raw: SceneData): SceneMigrationResult```+## moveAnimatorState — function+```+(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef+```+## moveBtNode — function```(def: BtDefinition, id: string, x: number, y: number): BtDefinition@@ -9222,6 +9263,21 @@ PrefabsPlugin(compData: SceneComponentData, entityMap: Map<number, Entity>): void```+## removeAnimatorParam — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## removeAnimatorState — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## removeAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef+```+## removeBtNode — function```(def: BtDefinition, id: string): BtDefinition@@ -9247,6 +9303,11 @@ PrefabsPlugin(def: FsmDefinition, from: string, index: number): FsmDefinition```+## renameAnimatorState — function+```+(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef+```+## renameState — function```(def: FsmDefinition, oldName: string, newName: string): FsmDefinition@@ -9402,6 +9463,26 @@ Plugin(asset: TimelineAsset, indent?: number): string```+## setAnimatorConditions — function+```+(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef+```++## setAnimatorInitial — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## setAnimatorStateClip — function+```+(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef+```++## setAnimatorStateProps — function+```+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; }): AnimatorControllerDef+```+## setBtNodeField — function```(def: BtDefinition, id: string, patch: Partial<BtNode>): BtDefinition@@ -9762,6 +9843,16 @@ UIRenderOrderPlugin(id: string): void```+## updateAnimatorParam — function+```+(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef+```++## updateAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef+```+## updateCameraAspectRatio — function```(world: World, aspectRatio: number): voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 63779ea4c..df51ac5d6 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1276 stable · 17 beta · 0 deprecated+Symbols: 1293 stable · 17 beta · 0 deprecated## ANCHOR_AXES — const```@@ -301,6 +301,15 @@ currentState: stringenabled: boolean```+## AnimatorEdge — interface+```+from: string+id: string+index: number+to: string+transition: AnimatorTransition+```+## AnimatorEvalResult — interface```consumedTriggers: string[]@@ -351,6 +360,8 @@ speed: number | undefinedspine: AnimatorSpineMotion | undefinedstateMachine: AnimatorSubMachine | undefinedtransitions: AnimatorTransition[]+x: number | undefined+y: number | undefined```## AnimatorSubMachine — interface@@ -7736,6 +7747,21 @@ TransformData(ref: FsmActionRef | undefined): string```+## addAnimatorParam — function+```+(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef+```++## addAnimatorState — function+```+(def: AnimatorControllerDef, name: string, x?: number, y?: number): AnimatorControllerDef+```++## addAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef+```+## addBtChild — function```(def: BtDefinition, parentId: string, type: BtNodeType, x?: number, y?: number): BtDefinition@@ -7821,6 +7847,11 @@ AiRegistry<AiContext>AnimationPlugin```+## animatorEdges — function+```+(def: AnimatorControllerDef): AnimatorEdge[]+```+## applyAudioProjectConfig — function```(audio: AudioAPI, config: AudioProjectConfig | undefined): void@@ -8301,6 +8332,11 @@ PluralSelectorDragPlugin```+## emptyAnimatorController — function+```+(): AnimatorControllerDef+```+## emptyBt — function```(): BtDefinition@@ -8916,6 +8952,11 @@ Mesh2DPlugin(raw: SceneData): SceneMigrationResult```+## moveAnimatorState — function+```+(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef+```+## moveBtNode — function```(def: BtDefinition, id: string, x: number, y: number): BtDefinition@@ -9241,6 +9282,21 @@ PrefabsPlugin(compData: SceneComponentData, entityMap: Map<number, Entity>): void```+## removeAnimatorParam — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## removeAnimatorState — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## removeAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef+```+## removeBtNode — function```(def: BtDefinition, id: string): BtDefinition@@ -9266,6 +9322,11 @@ PrefabsPlugin(def: FsmDefinition, from: string, index: number): FsmDefinition```+## renameAnimatorState — function+```+(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef+```+## renameState — function```(def: FsmDefinition, oldName: string, newName: string): FsmDefinition@@ -9421,6 +9482,26 @@ Plugin(asset: TimelineAsset, indent?: number): string```+## setAnimatorConditions — function+```+(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef+```++## setAnimatorInitial — function+```+(def: AnimatorControllerDef, name: string): AnimatorControllerDef+```++## setAnimatorStateClip — function+```+(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef+```++## setAnimatorStateProps — function+```+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; }): AnimatorControllerDef+```+## setBtNodeField — function```(def: BtDefinition, id: string, patch: Partial<BtNode>): BtDefinition@@ -9781,6 +9862,16 @@ UIRenderOrderPlugin(id: string): void```+## updateAnimatorParam — function+```+(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef+```++## updateAnimatorTransition — function+```+(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef+```+## updateCameraAspectRatio — function```(world: World, aspectRatio: number): voiddiff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex a40261823..1d2fbdebb 100644--- a/sdk/src/animation/Animator.ts+++ b/sdk/src/animation/Animator.ts@@ -117,6 +117,9 @@ export interface AnimatorState {speed?: number;loop?: boolean;transitions: AnimatorTransition[];+ /** Editor-only canvas position; the interpreter ignores it. */+ x?: number;+ y?: number;}export interface AnimatorControllerDef {diff --git a/sdk/src/animation/animatorGraph.ts b/sdk/src/animation/animatorGraph.tsnew file mode 100644index 000000000..6816e0b4e--- /dev/null+++ b/sdk/src/animation/animatorGraph.ts@@ -0,0 +1,149 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file animatorGraph.ts+ * @brief Immutable graph operations on an AnimatorControllerDef — the animation+ * controller editor's model.+ *+ * Pure functions returning new definitions (never mutating), so the state-graph+ * editor drives them through AssetDocument.edit for free undo, mirroring+ * fsmGraph.ts. An `.esanimator` payload IS the runtime AnimatorControllerDef+ * (states carry optional x/y layout the interpreter ignores), so there is no+ * separate editor model to compile.+ */++import type {+ AnimatorControllerDef,+ AnimatorState,+ AnimatorTransition,+ AnimatorCondition,+ AnimatorParam,+ AnimatorParamType,+} from './Animator';++/** A flattened transition edge, for the graph canvas. */+export interface AnimatorEdge {+ /** Stable id `from->to#index`. */+ id: string;+ from: string;+ to: string;+ index: number;+ transition: AnimatorTransition;+}++/** Flatten every state's outgoing transitions into addressable edges. */+export function animatorEdges(def: AnimatorControllerDef): AnimatorEdge[] {+ const edges: AnimatorEdge[] = [];+ for (const s of def.states) {+ s.transitions.forEach((transition, index) => {+ edges.push({ id: `${s.name}->${transition.to}#${index}`, from: s.name, to: transition.to, index, transition });+ });+ }+ return edges;+}++/** A blank controller with one initial state and no parameters. */+export function emptyAnimatorController(): AnimatorControllerDef {+ return { parameters: [], states: [{ name: 'Idle', x: 80, y: 80, transitions: [] }], initialState: 'Idle' };+}++export function addState(def: AnimatorControllerDef, name: string, x = 0, y = 0): AnimatorControllerDef {+ if (def.states.some((s) => s.name === name)) return def;+ const state: AnimatorState = { name, x, y, transitions: [] };+ return {+ ...def,+ states: [...def.states, state],+ // The first state added to an empty machine becomes the initial one.+ initialState: def.states.length === 0 ? name : def.initialState,+ };+}++export function removeState(def: AnimatorControllerDef, name: string): AnimatorControllerDef {+ const states = def.states+ .filter((s) => s.name !== name)+ .map((s) => (s.transitions.some((t) => t.to === name) ? { ...s, transitions: s.transitions.filter((t) => t.to !== name) } : s));+ const initialState = def.initialState === name ? (states[0]?.name ?? '') : def.initialState;+ return { ...def, states, initialState };+}++export function moveState(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef {+ return { ...def, states: def.states.map((s) => (s.name === name ? { ...s, x, y } : s)) };+}++/** Rename a state, rewiring `initialState` and every transition that targets it. */+export function renameState(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef {+ if (oldName === newName || !newName) return def;+ if (def.states.some((s) => s.name === newName)) return def;+ const rewire = (ts: AnimatorTransition[]) => ts.map((t) => (t.to === oldName ? { ...t, to: newName } : t));+ const states = def.states.map((s) => {+ const ns = s.name === oldName ? { ...s, name: newName } : s;+ return ns.transitions.some((t) => t.to === oldName) ? { ...ns, transitions: rewire(ns.transitions) } : ns;+ });+ return {+ ...def,+ states,+ initialState: def.initialState === oldName ? newName : def.initialState,+ ...(def.anyStateTransitions ? { anyStateTransitions: rewire(def.anyStateTransitions) } : {}),+ };+}++export function setInitial(def: AnimatorControllerDef, name: string): AnimatorControllerDef {+ return def.states.some((s) => s.name === name) ? { ...def, initialState: name } : def;+}++/** Set the state's motion to a single sprite clip (clears blend/spine/nested). */+export function setStateClip(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef {+ return {+ ...def,+ states: def.states.map((s) =>+ s.name === name+ ? { name: s.name, x: s.x, y: s.y, transitions: s.transitions, speed: s.speed, loop: s.loop, ...(clip ? { clip } : {}) }+ : s,+ ),+ };+}++export function setStateProps(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean }): AnimatorControllerDef {+ return { ...def, states: def.states.map((s) => (s.name === name ? { ...s, ...patch } : s)) };+}++export function addTransition(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef {+ return {+ ...def,+ states: def.states.map((s) => (s.name === from ? { ...s, transitions: [...s.transitions, { to, conditions: [] }] } : s)),+ };+}++export function removeTransition(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef {+ return {+ ...def,+ states: def.states.map((s) => (s.name === from ? { ...s, transitions: s.transitions.filter((_, i) => i !== index) } : s)),+ };+}++export function updateTransition(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef {+ return {+ ...def,+ states: def.states.map((s) => (s.name === from ? { ...s, transitions: s.transitions.map((t, i) => (i === index ? { ...t, ...patch } : t)) } : s)),+ };+}++/** Replace the whole condition list on a transition. */+export function setConditions(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef {+ return updateTransition(def, from, index, { conditions });+}++// — Parameters —++export function addParam(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef {+ if (!name || def.parameters.some((p) => p.name === name)) return def;+ return { ...def, parameters: [...def.parameters, { name, type }] };+}++export function removeParam(def: AnimatorControllerDef, name: string): AnimatorControllerDef {+ return { ...def, parameters: def.parameters.filter((p) => p.name !== name) };+}++export function updateParam(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef {+ return { ...def, parameters: def.parameters.map((p) => (p.name === name ? { ...p, ...patch } : p)) };+}diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.tsindex 30cdbf835..938a16edb 100644--- a/sdk/src/animation/index.ts+++ b/sdk/src/animation/index.ts@@ -69,6 +69,26 @@ export {type AnimatorPathEvalResult,} from './Animator';+export {+ emptyAnimatorController,+ animatorEdges,+ addState as addAnimatorState,+ removeState as removeAnimatorState,+ moveState as moveAnimatorState,+ renameState as renameAnimatorState,+ setInitial as setAnimatorInitial,+ setStateClip as setAnimatorStateClip,+ setStateProps as setAnimatorStateProps,+ addTransition as addAnimatorTransition,+ removeTransition as removeAnimatorTransition,+ updateTransition as updateAnimatorTransition,+ setConditions as setAnimatorConditions,+ addParam as addAnimatorParam,+ removeParam as removeAnimatorParam,+ updateParam as updateAnimatorParam,+ type AnimatorEdge,+} from './animatorGraph';+export {AnimationPlugin,animationPlugin,diff --git a/sdk/src/assetTypes.ts b/sdk/src/assetTypes.tsindex 733d654d4..3a2e08a28 100644--- a/sdk/src/assetTypes.ts+++ b/sdk/src/assetTypes.ts@@ -59,6 +59,8 @@ const ASSET_TYPE_REGISTRY: readonly AssetTypeEntry[] = [{ extensions: ['eslocale'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },// State machine (registerFsm / FsmAssetLoader) — data-driven FSM definition.{ extensions: ['esfsm'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },+ // Animation controller (AnimatorControllerDef) — data-driven sprite-anim state machine.+ { extensions: ['esanimator'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },// Behavior tree (registerBt / BtAssetLoader) — data-driven BT definition.{ extensions: ['esbt'], contentType: 'json', editorType: 'json', addressableType: 'json', wechatPackInclude: true, hasTransitiveDeps: false },];@@ -95,6 +97,7 @@ const MIME_MAP: Record<string, string> = {estimeline: 'application/json',eslocale: 'application/json',esfsm: 'application/json',+ esanimator: 'application/json',esbt: 'application/json',bmfont: 'application/json',fnt: 'text/plain',diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 9b5f4a563..765b54e84 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -261,6 +261,23 @@ export {type AnimatorSubMachine,type AnimatorScope,type AnimatorPathEvalResult,+ emptyAnimatorController,+ animatorEdges,+ addAnimatorState,+ removeAnimatorState,+ moveAnimatorState,+ renameAnimatorState,+ setAnimatorInitial,+ setAnimatorStateClip,+ setAnimatorStateProps,+ addAnimatorTransition,+ removeAnimatorTransition,+ updateAnimatorTransition,+ setAnimatorConditions,+ addAnimatorParam,+ removeAnimatorParam,+ updateAnimatorParam,+ type AnimatorEdge,AnimationPlugin,animationPlugin,type TweenOptions,