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): Animator can drive Spine animations, not just sprites (T2)
yhhfd33ec02dc5d
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex 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.tsindex 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.tsindex 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.tsindex 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 listenerdiff --git a/sdk/tests/animator.test.ts b/sdk/tests/animator.test.tsindex 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', {