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(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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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');
+ });
+});