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): 1D blend (threshold clip selection) for Animator states (T2)
yhh531fa3a191aa
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex 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.tsindex 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.tsindex 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.tsindex 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');+ });});