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(animation): nested (sub-) state machines for the Animator (2D-parity A2)
esengine5cf5d4ccfe85
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex 17f611599..65ac7d8c6 100644--- a/sdk/src/animation/Animator.ts+++ b/sdk/src/animation/Animator.ts@@ -92,14 +92,28 @@ export interface SpineAnimationDriver {setAnimation(entity: Entity, animation: string, loop: boolean): void;}+/**+ * A nested state machine. A state carrying one is a *container* (it plays no+ * motion of its own); on entry the machine descends to `initialState`, and the+ * container state's own `transitions` are the edges that exit the whole machine.+ */+export interface AnimatorSubMachine {+ states: AnimatorState[];+ initialState: string;+ /** Transitions evaluated from every sub-state in this machine. */+ anyStateTransitions?: AnimatorTransition[];+}+export interface AnimatorState {name: string;- /** Single sprite clip this state plays. Mutually exclusive with `blend`/`spine`. */+ /** Single sprite clip this state plays. Mutually exclusive with `blend`/`spine`/`stateMachine`. */clip?: string;- /** 1D blend selection. Mutually exclusive with `clip`/`spine`. */+ /** 1D blend selection. Mutually exclusive with `clip`/`spine`/`stateMachine`. */blend?: AnimatorBlend1D;/** Drive a Spine animation instead of a sprite clip. */spine?: AnimatorSpineMotion;+ /** Nested machine — makes this a container state (no motion of its own). */+ stateMachine?: AnimatorSubMachine;speed?: number;loop?: boolean;transitions: AnimatorTransition[];@@ -113,6 +127,12 @@ export interface AnimatorControllerDef {anyStateTransitions?: AnimatorTransition[];}+/**+ * The shape shared by the top-level controller and every nested machine: a set of+ * states, an entry point, and machine-wide any-state transitions.+ */+export type AnimatorScope = Pick<AnimatorControllerDef, 'states' | 'initialState' | 'anyStateTransitions'>;+// =============================================================================// Pure transition evaluator (no World, no side effects → unit-testable)// =============================================================================@@ -185,6 +205,103 @@ export function evaluateAnimatorTransitions(: { next: null, consumedTriggers: [] };}+// =============================================================================+// Nested state machines — path resolution + recursive evaluator (pure)+// =============================================================================++/** The active state is a `/`-separated path of state names (e.g. `Combat/Attack1`). */+export const STATE_PATH_SEP = '/';++/**+ * Descend from state `name` in `scope` to a concrete leaf, returning the path+ * segments. A container state (one with a `stateMachine`) recurses into its+ * `initialState`; a normal state ends the path.+ */+export function enterStatePath(scope: AnimatorScope, name: string): string[] {+ const st = scope.states.find((s) => s.name === name);+ if (!st || !st.stateMachine) return [name];+ return [name, ...enterStatePath(st.stateMachine, st.stateMachine.initialState)];+}++interface ResolvedPath {+ /** The scope that contains `states[i]` (top-level for i=0). */+ scopes: AnimatorScope[];+ /** The state chain from the outermost container down to the leaf. */+ states: AnimatorState[];+}++/** Resolve a path to its scope/state chain, or null if any segment is unknown. */+function resolveStatePath(top: AnimatorScope, segments: readonly string[]): ResolvedPath | null {+ if (segments.length === 0) return null;+ const scopes: AnimatorScope[] = [];+ const states: AnimatorState[] = [];+ let scope: AnimatorScope = top;+ for (const seg of segments) {+ const st = scope.states.find((s) => s.name === seg);+ if (!st) return null;+ scopes.push(scope);+ states.push(st);+ if (!st.stateMachine) break;+ scope = st.stateMachine;+ }+ return { scopes, states };+}++export interface AnimatorPathEvalResult {+ /** Target path if a transition fired, else null (stay). */+ nextPath: string | null;+ consumedTriggers: string[];+}++/**+ * Evaluate one step of a (possibly nested) state machine over a path. Transitions+ * are checked highest-priority first: top-level any-state, then each enclosing+ * machine's any-state from outermost in, then the leaf's own transitions, then the+ * container exit transitions from innermost out. A fired transition's `to` is+ * resolved within the machine that owns it (descending into a sub-machine's+ * initial state when needed). `clipFinished` reflects the leaf clip. Pure.+ */+export function evaluateAnimatorPath(+ def: AnimatorControllerDef,+ currentPath: string,+ params: AnimatorParamValues,+ triggers: ReadonlySet<string>,+ clipFinished: boolean = true,+): AnimatorPathEvalResult {+ const segments = currentPath ? currentPath.split(STATE_PATH_SEP) : [];+ const resolved = resolveStatePath(def, segments);+ if (!resolved) return { nextPath: null, consumedTriggers: [] };+ const { scopes, states } = resolved;+ const depth = states.length;++ // (list, owning scope, path to that scope) in priority order.+ const lists: { list: readonly AnimatorTransition[]; scope: AnimatorScope; base: string[] }[] = [];+ lists.push({ list: def.anyStateTransitions ?? [], scope: def, base: [] });+ for (let i = 0; i < depth - 1; i++) {+ const sm = states[i].stateMachine!;+ lists.push({ list: sm.anyStateTransitions ?? [], scope: sm, base: segments.slice(0, i + 1) });+ }+ lists.push({ list: states[depth - 1].transitions ?? [], scope: scopes[depth - 1], base: segments.slice(0, depth - 1) });+ for (let i = depth - 2; i >= 0; i--) {+ lists.push({ list: states[i].transitions ?? [], scope: scopes[i], base: segments.slice(0, i) });+ }++ for (const entry of lists) {+ const fired = firstReady(entry.list, params, triggers, clipFinished);+ if (fired) {+ const next = [...entry.base, ...enterStatePath(entry.scope, fired.to)];+ return { nextPath: next.join(STATE_PATH_SEP), consumedTriggers: fired.usedTriggers };+ }+ }+ return { nextPath: null, consumedTriggers: [] };+}++/** The leaf (motion-bearing) state of a resolved path, or null if unresolvable. */+export function leafStateOf(def: AnimatorControllerDef, path: string): AnimatorState | null {+ const resolved = resolveStatePath(def, path ? path.split(STATE_PATH_SEP) : []);+ return resolved ? resolved.states[resolved.states.length - 1] : null;+}+/*** Select a 1D blend's clip for a parameter value: the threshold with the* greatest `value` ≤ `value`, clamped up to the first stop when below all.@@ -328,57 +445,57 @@ export class AnimatorControllerApi {const def = this.controllers.get(a.controller);if (!def || def.states.length === 0) continue;- // Seed / repair the active state.- const known = a.currentState && def.states.some((s) => s.name === a.currentState);- const fromState = known ? a.currentState : def.initialState;+ // Seed / repair the active state path. The path descends into a+ // sub-machine's initial state when the entry point is a container.+ let fromPath = a.currentState;+ let leaf = fromPath ? leafStateOf(def, fromPath) : null;+ if (!leaf) {+ fromPath = enterStatePath(def, def.initialState).join(STATE_PATH_SEP);+ leaf = leafStateOf(def, fromPath);+ if (!leaf) continue;+ }const params = resolveParams(def, this.params.get(entity) ?? EMPTY_PARAMS);const triggerSet = this.triggers.get(entity);- // The current clip has finished when its SpriteAnimator stopped (a- // non-looping clip reached its end). Gates hasExitTime transitions.+ // The leaf clip has finished when its SpriteAnimator is playing exactly+ // that clip and has stopped — not merely stopped (also true before the+ // clip is ever applied, e.g. the frame a state is entered). Only a+ // sprite leaf reports this; a spine leaf's completion is SpineManager's.const spNow = world.has(entity, SpriteAnimator)? (world.get(entity, SpriteAnimator) as SpriteAnimatorData): null;- // "Finished" means the SpriteAnimator is playing *this* state's clip- // and has stopped — not merely stopped (which is also true before the- // clip is ever applied, e.g. the frame a state is entered).- const fromDef = def.states.find((s) => s.name === fromState);- // Only a sprite state can report "clip finished"; a spine state's- // completion is owned by SpineManager (exit time for spine is future).- const expectedClip = fromDef && !fromDef.spine ? this.motionClipOf(fromDef, params).clip : '';+ const expectedClip = !leaf.spine ? this.motionClipOf(leaf, params).clip : '';const clipFinished = expectedClip !== '' && spNow != null&& spNow.clip === expectedClip && !spNow.playing;- const { next, consumedTriggers } = evaluateAnimatorTransitions(- def, fromState, params, triggerSet ?? EMPTY_TRIGGERS, clipFinished,++ const { nextPath, consumedTriggers } = evaluateAnimatorPath(+ def, fromPath, params, triggerSet ?? EMPTY_TRIGGERS, clipFinished,);if (triggerSet) for (const t of consumedTriggers) triggerSet.delete(t);- const target = next ?? fromState;+ const target = nextPath ?? fromPath;const stateChanged = target !== a.currentState;if (stateChanged) {a.currentState = target;world.insert(entity, Animator, a);}- // Apply the active state's motion every frame: a 1D-blend state's- // selected clip can change as its parameter crosses a threshold- // without any state change. A single-clip state in steady state is a- // no-op (the desired clip already matches), so this is cheap.- this.applyMotion(world, entity, def, target, params, stateChanged);+ const targetLeaf = nextPath ? leafStateOf(def, target) : leaf;+ // Apply the active leaf's motion every frame: a 1D-blend leaf's selected+ // clip can change as its parameter crosses a threshold without any state+ // change. A single-clip leaf in steady state is a no-op (cheap).+ if (targetLeaf) this.applyMotion(world, entity, targetLeaf, params, stateChanged);}}/**- * Drive the entity's SpriteAnimator from the active state's motion (single- * clip or 1D-blend selection). Writes only when the desired clip differs or- * the state just changed — restarting from frame 0 on a switch.+ * Drive the entity's SpriteAnimator from a leaf state's motion (single clip or+ * 1D-blend selection). Writes only when the desired clip differs or the state+ * just changed — restarting from frame 0 on a switch.*/private applyMotion(- world: World, entity: Entity, def: AnimatorControllerDef,- stateName: string, params: AnimatorParamValues, forceRestart: boolean,+ world: World, entity: Entity, st: AnimatorState,+ params: AnimatorParamValues, forceRestart: boolean,): void {- const st = def.states.find((s) => s.name === stateName);- if (!st) return;-// Spine state: set the skeletal animation on entry (SpineManager owns the// track playback/mixing); don't re-set every frame or touch SpriteAnimator.if (st.spine) {diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.tsindex 2be204799..c4d9a5c52 100644--- a/sdk/src/animation/index.ts+++ b/sdk/src/animation/index.ts@@ -45,12 +45,18 @@ export {AnimatorController,AnimatorControllerApi,evaluateAnimatorTransitions,+ evaluateAnimatorPath,+ enterStatePath,+ leafStateOf,resolveParams,selectBlendClip,+ STATE_PATH_SEP,type AnimatorData,type AnimatorBlend1D,type AnimatorBlendThreshold,type AnimatorSpineMotion,+ type AnimatorSubMachine,+ type AnimatorScope,type SpineAnimationDriver,type AnimatorParam,type AnimatorParamType,@@ -60,6 +66,7 @@ export {type AnimatorControllerDef,type AnimatorParamValues,type AnimatorEvalResult,+ type AnimatorPathEvalResult,} from './Animator';export {diff --git a/sdk/tests/animator-substate.test.ts b/sdk/tests/animator-substate.test.tsnew file mode 100644index 000000000..133481f61--- /dev/null+++ b/sdk/tests/animator-substate.test.ts@@ -0,0 +1,197 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import {+ Animator,+ AnimatorControllerApi,+ evaluateAnimatorPath,+ enterStatePath,+ leafStateOf,+ type AnimatorControllerDef,+ type AnimatorData,+} from '../src/animation/Animator';+import { SpriteAnimator, type SpriteAnimatorData } from '../src/animation/SpriteAnimator';++// A controller with a nested Combat machine. `Combat` is a container (it carries a+// stateMachine) whose own `transitions` are the edges that exit it; `Dead` is a+// top-level escape reachable from anywhere.+function nestedController(): AnimatorControllerDef {+ return {+ parameters: [+ { name: 'attack', type: 'trigger' },+ { name: 'block', type: 'bool', default: false },+ { name: 'done', type: 'bool', default: false },+ { name: 'dead', type: 'bool', default: false },+ ],+ initialState: 'Locomotion',+ states: [+ { name: 'Locomotion', clip: 'loco', transitions: [+ { to: 'Combat', conditions: [{ param: 'attack', op: 'trigger' }] },+ ] },+ {+ name: 'Combat',+ stateMachine: {+ initialState: 'Swing',+ anyStateTransitions: [+ { to: 'Block', conditions: [{ param: 'block', op: 'true' }] },+ ],+ states: [+ { name: 'Swing', clip: 'swing', loop: false, transitions: [+ { to: 'Recover', conditions: [], hasExitTime: true },+ ] },+ { name: 'Recover', clip: 'recover', transitions: [] },+ { name: 'Block', clip: 'block', transitions: [] },+ ],+ },+ // Exit edges (resolved in the top scope).+ transitions: [+ { to: 'Locomotion', conditions: [{ param: 'done', op: 'true' }] },+ ],+ },+ { name: 'Dead', clip: 'dead', transitions: [] },+ ],+ anyStateTransitions: [+ { to: 'Dead', conditions: [{ param: 'dead', op: 'true' }] },+ ],+ };+}++describe('enterStatePath', () => {+ const def = nestedController();+ it('a leaf state is its own path', () => {+ expect(enterStatePath(def, 'Locomotion')).toEqual(['Locomotion']);+ });+ it('a container descends to its initial sub-state', () => {+ expect(enterStatePath(def, 'Combat')).toEqual(['Combat', 'Swing']);+ });+});++describe('leafStateOf', () => {+ const def = nestedController();+ it('returns the leaf of a nested path', () => {+ expect(leafStateOf(def, 'Combat/Swing')?.name).toBe('Swing');+ expect(leafStateOf(def, 'Combat/Swing')?.clip).toBe('swing');+ });+ it('returns null for an unknown path', () => {+ expect(leafStateOf(def, 'Combat/Nope')).toBeNull();+ expect(leafStateOf(def, 'Ghost')).toBeNull();+ });+});++describe('evaluateAnimatorPath', () => {+ const def = nestedController();++ it('entering a container descends to its initial sub-state', () => {+ const r = evaluateAnimatorPath(def, 'Locomotion', {}, new Set(['attack']));+ expect(r.nextPath).toBe('Combat/Swing');+ expect(r.consumedTriggers).toEqual(['attack']);+ });++ it('a leaf transition stays within the sub-machine', () => {+ // Swing → Recover on exit time (clipFinished=true).+ const r = evaluateAnimatorPath(def, 'Combat/Swing', {}, new Set(), true);+ expect(r.nextPath).toBe('Combat/Recover');+ });++ it('gates a leaf hasExitTime transition on the leaf clip finishing', () => {+ expect(evaluateAnimatorPath(def, 'Combat/Swing', {}, new Set(), false).nextPath).toBeNull();+ });++ it('a sub-machine any-state transition fires from any sub-state', () => {+ const r = evaluateAnimatorPath(def, 'Combat/Swing', { block: true }, new Set());+ expect(r.nextPath).toBe('Combat/Block');+ });++ it("a container's own transition exits the sub-machine (parent scope)", () => {+ const r = evaluateAnimatorPath(def, 'Combat/Recover', { done: true }, new Set());+ expect(r.nextPath).toBe('Locomotion');+ });++ it('sub-machine any-state outranks the container exit edge', () => {+ // block AND done both hold: Block (sub any-state) is higher priority than+ // the Combat exit edge.+ const r = evaluateAnimatorPath(def, 'Combat/Swing', { block: true, done: true }, new Set(), true);+ expect(r.nextPath).toBe('Combat/Block');+ });++ it('top-level any-state outranks everything nested', () => {+ const r = evaluateAnimatorPath(def, 'Combat/Swing', { block: true, done: true, dead: true }, new Set(), true);+ expect(r.nextPath).toBe('Dead');+ });++ it('stays put when nothing fires', () => {+ expect(evaluateAnimatorPath(def, 'Combat/Recover', {}, new Set()).nextPath).toBeNull();+ });+});++// ---------------------------------------------------------------------------+// Integration: AnimatorControllerApi.update drives the leaf clip through nesting+// ---------------------------------------------------------------------------++function makeWorld() {+ const store = new Map<unknown, Map<number, unknown>>();+ const mapOf = (c: unknown) => {+ let m = store.get(c);+ if (!m) { m = new Map(); store.set(c, m); }+ return m;+ };+ return {+ insert(e: number, c: unknown, data: unknown) { mapOf(c).set(e, data); },+ get(e: number, c: unknown) { return mapOf(c).get(e); },+ has(e: number, c: unknown) { return mapOf(c).has(e); },+ getEntitiesWithComponents(comps: unknown[]) {+ const [first, ...rest] = comps;+ return [...mapOf(first).keys()].filter((e) => rest.every((c) => mapOf(c).has(e)));+ },+ } as any;+}++describe('AnimatorControllerApi.update — nested machine', () => {+ const E = 1;+ function setup() {+ const ctrl = new AnimatorControllerApi();+ ctrl.registerController('hero', nestedController());+ const world = makeWorld();+ world.insert(E, Animator, { controller: 'hero', currentState: '', enabled: true } as AnimatorData);+ world.insert(E, SpriteAnimator, {+ clip: '', speed: 1, playing: false, loop: true, enabled: true, currentFrame: 5, frameTimer: 0.3,+ } as SpriteAnimatorData);+ return { ctrl, world };+ }+ const animPath = (world: any) => (world.get(E, Animator) as AnimatorData).currentState;+ const clip = (world: any) => (world.get(E, SpriteAnimator) as SpriteAnimatorData).clip;++ it('seeds the top initial leaf and applies its clip', () => {+ const { ctrl, world } = setup();+ ctrl.update(world);+ expect(animPath(world)).toBe('Locomotion');+ expect(clip(world)).toBe('loco');+ });++ it('enters a sub-machine and plays its initial sub-state clip', () => {+ const { ctrl, world } = setup();+ ctrl.update(world); // Locomotion+ ctrl.setTrigger(E, 'attack');+ ctrl.update(world);+ expect(animPath(world)).toBe('Combat/Swing');+ expect(clip(world)).toBe('swing');+ });++ it('advances within the sub-machine, then exits via the container edge', () => {+ const { ctrl, world } = setup();+ ctrl.update(world);+ ctrl.setTrigger(E, 'attack');+ ctrl.update(world); // → Combat/Swing (swing clip applied, loop:false)+ // Simulate the swing clip finishing so its exit-time edge can fire.+ const sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;+ sp.playing = false;+ ctrl.update(world);+ expect(animPath(world)).toBe('Combat/Recover');+ expect(clip(world)).toBe('recover');+ // Exit the whole sub-machine back to Locomotion.+ ctrl.setBool(E, 'done', true);+ ctrl.update(world);+ expect(animPath(world)).toBe('Locomotion');+ expect(clip(world)).toBe('loco');+ });+});