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): Animator can drive Spine animations, not just sprites (T2)

yhhfd33ec02dc5d
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.ts
index 7faa559ba..17f611599 100644
--- a/sdk/src/animation/Animator.ts
+++ b/sdk/src/animation/Animator.ts
@@ -77,12 +77,29 @@ export interface AnimatorBlend1D {
thresholds: AnimatorBlendThreshold[];
}
+/** A state that drives a Spine skeletal animation instead of a sprite clip. */
+export interface AnimatorSpineMotion {
+ animation: string;
+ loop?: boolean;
+}
+
+/**
+ * Minimal channel the Animator uses to drive Spine, kept here so the animation
+ * core does not depend on the optional spine module. `SpineManager` satisfies it
+ * structurally; `SpinePlugin` injects it via `AnimatorController.setSpineDriver`.
+ */
+export interface SpineAnimationDriver {
+ setAnimation(entity: Entity, animation: string, loop: boolean): void;
+}
+
export interface AnimatorState {
name: string;
- /** Single sprite clip this state plays. Mutually exclusive with `blend`. */
+ /** Single sprite clip this state plays. Mutually exclusive with `blend`/`spine`. */
clip?: string;
- /** 1D blend selection. Mutually exclusive with `clip`. */
+ /** 1D blend selection. Mutually exclusive with `clip`/`spine`. */
blend?: AnimatorBlend1D;
+ /** Drive a Spine animation instead of a sprite clip. */
+ spine?: AnimatorSpineMotion;
speed?: number;
loop?: boolean;
transitions: AnimatorTransition[];
@@ -230,6 +247,13 @@ export class AnimatorControllerApi {
private readonly controllers = new Map<string, AnimatorControllerDef>();
private readonly params = new Map<Entity, Map<string, number | boolean>>();
private readonly triggers = new Map<Entity, Set<string>>();
+ private spineDriver_: SpineAnimationDriver | null = null;
+
+ /** Inject the Spine driver (SpinePlugin wires SpineManager here). Optional —
+ * without it, spine-targeting states are inert. */
+ setSpineDriver(driver: SpineAnimationDriver | null): void {
+ this.spineDriver_ = driver;
+ }
// -- controller registry --------------------------------------------------
@@ -319,10 +343,11 @@ export class AnimatorControllerApi {
// 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);
- const expectedClip = fromDef ? this.motionClipOf(fromDef, params).clip : '';
- const clipFinished = spNow
- ? (expectedClip !== '' && spNow.clip === expectedClip && !spNow.playing)
- : true;
+ // 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 clipFinished = expectedClip !== '' && spNow != null
+ && spNow.clip === expectedClip && !spNow.playing;
const { next, consumedTriggers } = evaluateAnimatorTransitions(
def, fromState, params, triggerSet ?? EMPTY_TRIGGERS, clipFinished,
);
@@ -352,8 +377,18 @@ export class AnimatorControllerApi {
stateName: string, params: AnimatorParamValues, forceRestart: boolean,
): void {
const st = def.states.find((s) => s.name === stateName);
- if (!st || !world.has(entity, SpriteAnimator)) return;
+ 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) {
+ if (forceRestart && this.spineDriver_) {
+ this.spineDriver_.setAnimation(entity, st.spine.animation, st.spine.loop ?? true);
+ }
+ return;
+ }
+ if (!world.has(entity, SpriteAnimator)) return;
const sel = this.motionClipOf(st, params);
const sp = world.get(entity, SpriteAnimator) as SpriteAnimatorData;
if (sp.clip === sel.clip && !forceRestart) return;
diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.ts
index 892d5722d..2be204799 100644
--- a/sdk/src/animation/index.ts
+++ b/sdk/src/animation/index.ts
@@ -50,6 +50,8 @@ export {
type AnimatorData,
type AnimatorBlend1D,
type AnimatorBlendThreshold,
+ type AnimatorSpineMotion,
+ type SpineAnimationDriver,
type AnimatorParam,
type AnimatorParamType,
type AnimatorCondition,
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 32119a0e2..f916dd320 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -221,6 +221,8 @@ export {
type AnimatorData,
type AnimatorBlend1D,
type AnimatorBlendThreshold,
+ type AnimatorSpineMotion,
+ type SpineAnimationDriver,
type AnimatorParam,
type AnimatorParamType,
type AnimatorCondition,
diff --git a/sdk/src/spine/SpinePlugin.ts b/sdk/src/spine/SpinePlugin.ts
index 57467d379..de1685cd3 100644
--- a/sdk/src/spine/SpinePlugin.ts
+++ b/sdk/src/spine/SpinePlugin.ts
@@ -9,6 +9,7 @@ import type { Entity } from '../types';
import { SpineManager, type SpineVersion } from './SpineManager';
import type { SpineModuleFactory, SpineWasmModule } from './SpineModuleLoader';
import { SPINE_VERSIONS, spineModuleId } from '../sideModules';
+import { AnimatorController } from '../animation/Animator';
export type SpineEventType = 'start' | 'interrupt' | 'end' | 'complete' | 'event';
@@ -63,6 +64,7 @@ export class SpinePlugin implements Plugin {
pipeline?.addPreFlushCallback((registry) => {
manager.submitMeshes(registry._cpp);
});
+ this.wireAnimatorDriver_(app);
}
}
@@ -114,6 +116,22 @@ export class SpinePlugin implements Plugin {
}
}
+ /**
+ * Wire the spine manager into the Animator as its Spine driver, so
+ * spine-targeting Animator states drive skeletal animations. Runs after all
+ * plugins build (the AnimatorController resource exists by then if the
+ * AnimationPlugin is installed).
+ */
+ finish(app: App): void {
+ this.wireAnimatorDriver_(app);
+ }
+
+ private wireAnimatorDriver_(app: App): void {
+ if (this.spineManager_ && app.hasResource(AnimatorController)) {
+ app.getResource(AnimatorController).setSpineDriver(this.spineManager_);
+ }
+ }
+
/**
* Drop the world.onDespawn subscription and dispose the spine manager's
* native backends. Without this, a re-init left a stale despawn listener
diff --git a/sdk/tests/animator.test.ts b/sdk/tests/animator.test.ts
index fff6520ca..d14a2a9af 100644
--- a/sdk/tests/animator.test.ts
+++ b/sdk/tests/animator.test.ts
@@ -281,6 +281,49 @@ describe('AnimatorControllerApi.update', () => {
expect((world.get(E, SpriteAnimator) as SpriteAnimatorData).clip).toBe('idle');
});
+ it('drives the Spine driver on entry to a spine state (and not every frame)', () => {
+ const setAnimation = vi.fn();
+ const ctrl = new AnimatorControllerApi();
+ ctrl.setSpineDriver({ setAnimation });
+ ctrl.registerController('caster', {
+ parameters: [{ name: 'cast', type: 'trigger' }],
+ initialState: 'idle',
+ states: [
+ { name: 'idle', spine: { animation: 'idle', loop: true }, transitions: [
+ { to: 'cast', conditions: [{ param: 'cast', op: 'trigger' }] },
+ ] },
+ { name: 'cast', spine: { animation: 'cast', loop: false }, transitions: [] },
+ ],
+ });
+ const world = makeWorld();
+ // No SpriteAnimator — a pure-spine entity.
+ world.insert(E, Animator, { controller: 'caster', currentState: '', enabled: true } as AnimatorData);
+
+ ctrl.update(world); // → idle (entry) → setAnimation('idle', true)
+ expect(setAnimation).toHaveBeenCalledWith(E, 'idle', true);
+ expect(setAnimation).toHaveBeenCalledTimes(1);
+
+ ctrl.update(world); // no state change → no re-set
+ expect(setAnimation).toHaveBeenCalledTimes(1);
+
+ ctrl.setTrigger(E, 'cast');
+ ctrl.update(world); // → cast → setAnimation('cast', false)
+ expect(setAnimation).toHaveBeenLastCalledWith(E, 'cast', false);
+ expect(setAnimation).toHaveBeenCalledTimes(2);
+ });
+
+ it('spine states are inert without a driver (no throw)', () => {
+ const ctrl = new AnimatorControllerApi();
+ ctrl.registerController('s', {
+ parameters: [], initialState: 'a',
+ states: [{ name: 'a', spine: { animation: 'a' }, transitions: [] }],
+ });
+ const world = makeWorld();
+ world.insert(E, Animator, { controller: 's', currentState: '', enabled: true } as AnimatorData);
+ expect(() => ctrl.update(world)).not.toThrow();
+ expect((world.get(E, Animator) as AnimatorData).currentState).toBe('a');
+ });
+
it('a 1D-blend state switches clip within the state as the parameter crosses thresholds', () => {
const ctrl = new AnimatorControllerApi();
ctrl.registerController('loco', {