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): 1D blend (threshold clip selection) for Animator states (T2)

yhh531fa3a191aa
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.ts
index 78a2424a1..85e83fcc3 100644
--- a/sdk/src/animation/Animator.ts
+++ b/sdk/src/animation/Animator.ts
@@ -51,10 +51,32 @@ export interface AnimatorTransition {
conditions: AnimatorCondition[];
}
+/** One stop on a 1D blend: at/above `value`, play `clip`. */
+export interface AnimatorBlendThreshold {
+ value: number;
+ clip: string;
+ speed?: number;
+ loop?: boolean;
+}
+
+/**
+ * 1D parameter-driven clip selection. The sprite channel plays one clip at a
+ * time, so a "blend" here is a *selection* by threshold (idle→walk→run as a
+ * speed parameter rises), not a weighted pose blend (that's the skeletal/Spine
+ * follow-on). Thresholds may be given in any order.
+ */
+export interface AnimatorBlend1D {
+ /** Float parameter that drives the selection. */
+ parameter: string;
+ thresholds: AnimatorBlendThreshold[];
+}
+
export interface AnimatorState {
name: string;
- /** Sprite clip name this state plays (registered with SpriteAnimation). */
- clip: string;
+ /** Single sprite clip this state plays. Mutually exclusive with `blend`. */
+ clip?: string;
+ /** 1D blend selection. Mutually exclusive with `clip`. */
+ blend?: AnimatorBlend1D;
speed?: number;
loop?: boolean;
transitions: AnimatorTransition[];
@@ -134,6 +156,22 @@ export function evaluateAnimatorTransitions(
: { next: null, consumedTriggers: [] };
}
+/**
+ * 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.
+ * Pure. Returns `{ clip: '' }` for an empty blend.
+ */
+export function selectBlendClip(blend: AnimatorBlend1D, value: number): AnimatorBlendThreshold {
+ const sorted = [...blend.thresholds].sort((a, b) => a.value - b.value);
+ if (sorted.length === 0) return { value: 0, clip: '' };
+ let chosen = sorted[0];
+ for (const t of sorted) {
+ if (value >= t.value) chosen = t;
+ else break;
+ }
+ return chosen;
+}
+
/** Merge a controller's declared parameter defaults with per-entity overrides. */
export function resolveParams(
def: AnimatorControllerDef,
@@ -266,22 +304,41 @@ export class AnimatorControllerApi {
if (triggerSet) for (const t of consumedTriggers) triggerSet.delete(t);
const target = next ?? fromState;
- if (target !== a.currentState) {
+ const stateChanged = target !== a.currentState;
+ if (stateChanged) {
a.currentState = target;
- this.applyState(world, entity, def, 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);
}
}
- /** Switch the entity's SpriteAnimator to the state's clip (restart from frame 0). */
- private applyState(world: World, entity: Entity, def: AnimatorControllerDef, stateName: string): void {
+ /**
+ * 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.
+ */
+ private applyMotion(
+ world: World, entity: Entity, def: AnimatorControllerDef,
+ stateName: string, params: AnimatorParamValues, forceRestart: boolean,
+ ): void {
const st = def.states.find((s) => s.name === stateName);
if (!st || !world.has(entity, SpriteAnimator)) return;
+
+ const sel: AnimatorBlendThreshold = st.blend
+ ? selectBlendClip(st.blend, Number(params[st.blend.parameter] ?? 0))
+ : { value: 0, clip: st.clip ?? '', speed: st.speed, loop: st.loop };
+
const sp = world.get(entity, SpriteAnimator) as SpriteAnimatorData;
- sp.clip = st.clip;
- sp.speed = st.speed ?? 1.0;
- sp.loop = st.loop ?? true;
+ if (sp.clip === sel.clip && !forceRestart) return;
+
+ sp.clip = sel.clip;
+ sp.speed = sel.speed ?? st.speed ?? 1.0;
+ sp.loop = sel.loop ?? st.loop ?? true;
sp.currentFrame = 0;
sp.frameTimer = 0;
sp.playing = true;
diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.ts
index ddfb9828c..892d5722d 100644
--- a/sdk/src/animation/index.ts
+++ b/sdk/src/animation/index.ts
@@ -46,7 +46,10 @@ export {
AnimatorControllerApi,
evaluateAnimatorTransitions,
resolveParams,
+ selectBlendClip,
type AnimatorData,
+ type AnimatorBlend1D,
+ type AnimatorBlendThreshold,
type AnimatorParam,
type AnimatorParamType,
type AnimatorCondition,
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index a57d91fe2..32119a0e2 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -217,7 +217,10 @@ export {
AnimatorControllerApi,
evaluateAnimatorTransitions,
resolveParams,
+ selectBlendClip,
type AnimatorData,
+ type AnimatorBlend1D,
+ type AnimatorBlendThreshold,
type AnimatorParam,
type AnimatorParamType,
type AnimatorCondition,
diff --git a/sdk/tests/animator.test.ts b/sdk/tests/animator.test.ts
index ed2e9bb44..8f404e642 100644
--- a/sdk/tests/animator.test.ts
+++ b/sdk/tests/animator.test.ts
@@ -6,6 +6,8 @@ import {
AnimatorControllerApi,
evaluateAnimatorTransitions,
resolveParams,
+ selectBlendClip,
+ type AnimatorBlend1D,
type AnimatorControllerDef,
type AnimatorData,
} from '../src/animation/Animator';
@@ -100,6 +102,39 @@ describe('resolveParams', () => {
});
});
+// ---------------------------------------------------------------------------
+// 1D blend selection (pure)
+// ---------------------------------------------------------------------------
+
+describe('selectBlendClip', () => {
+ const blend: AnimatorBlend1D = {
+ parameter: 'speed',
+ // intentionally unordered to exercise the sort
+ thresholds: [
+ { value: 7, clip: 'run' },
+ { value: 0, clip: 'idle' },
+ { value: 3, clip: 'walk' },
+ ],
+ };
+
+ it('floors to the greatest threshold <= value', () => {
+ expect(selectBlendClip(blend, 0).clip).toBe('idle');
+ expect(selectBlendClip(blend, 2.9).clip).toBe('idle');
+ expect(selectBlendClip(blend, 3).clip).toBe('walk');
+ expect(selectBlendClip(blend, 6.9).clip).toBe('walk');
+ expect(selectBlendClip(blend, 7).clip).toBe('run');
+ expect(selectBlendClip(blend, 100).clip).toBe('run');
+ });
+
+ it('clamps up to the first stop below all thresholds', () => {
+ expect(selectBlendClip(blend, -5).clip).toBe('idle');
+ });
+
+ it('returns an empty clip for an empty blend', () => {
+ expect(selectBlendClip({ parameter: 'x', thresholds: [] }, 1).clip).toBe('');
+ });
+});
+
// ---------------------------------------------------------------------------
// AnimatorControllerApi.update drives SpriteAnimator (mock World)
// ---------------------------------------------------------------------------
@@ -195,4 +230,41 @@ describe('AnimatorControllerApi.update', () => {
ctrl.removeEntity(E);
expect(ctrl.getFloat(E, 'speed')).toBe(0);
});
+
+ it('a 1D-blend state switches clip within the state as the parameter crosses thresholds', () => {
+ const ctrl = new AnimatorControllerApi();
+ ctrl.registerController('loco', {
+ parameters: [{ name: 'speed', type: 'float', default: 0 }],
+ initialState: 'move',
+ states: [{
+ name: 'move',
+ blend: { parameter: 'speed', thresholds: [
+ { value: 0, clip: 'idle' },
+ { value: 3, clip: 'walk' },
+ { value: 7, clip: 'run', speed: 2 },
+ ] },
+ transitions: [],
+ }],
+ });
+ const world = makeWorld();
+ world.insert(E, Animator, { controller: 'loco', currentState: '', enabled: true } as AnimatorData);
+ world.insert(E, SpriteAnimator, spriteData());
+
+ ctrl.update(world); // seed 'move', speed 0 → idle
+ expect((world.get(E, SpriteAnimator) as SpriteAnimatorData).clip).toBe('idle');
+
+ ctrl.setFloat(E, 'speed', 4); ctrl.update(world);
+ let sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;
+ expect(sp.clip).toBe('walk');
+ // No state change occurred — still 'move'.
+ expect((world.get(E, Animator) as AnimatorData).currentState).toBe('move');
+
+ ctrl.setFloat(E, 'speed', 9); ctrl.update(world);
+ sp = world.get(E, SpriteAnimator) as SpriteAnimatorData;
+ expect(sp.clip).toBe('run');
+ expect(sp.speed).toBe(2); // per-threshold speed
+
+ ctrl.setFloat(E, 'speed', 1); ctrl.update(world);
+ expect((world.get(E, SpriteAnimator) as SpriteAnimatorData).clip).toBe('idle');
+ });
});