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
refactor(anim): a state says what it plays one way, from the file in
esengine181361432b1e
diff --git a/desktop b/desktopindex 3acf1b56c..ced6c9cb9 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 3acf1b56c1a85cd3cd822cc4c4c54998490cd6f1+Subproject commit ced6c9cb96a3853cd26b6a4065669240d98870fcdiff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex 214eb10e2..37f0627c8 100644--- a/sdk/src/animation/Animator.ts+++ b/sdk/src/animation/Animator.ts@@ -464,23 +464,28 @@ function spriteBlendMotion(st: AnimatorState, blend: AnimatorBlend1D): AnimatorB}/**- * What a state plays, whichever way it was authored: `motion`, or the- * `clip`/`blend`/`spine` fields every controller written before motions used.- * Read here rather than rewritten on load, so those keep working untouched.+ * What `clip`, `blend` or `spine` mean as a {@link AnimatorMotion} — each is one+ * kind's own word for what `motion` says generally. Pure, so the migration and+ * the runtime's cache share one conversion rather than two that can drift.+ */+export function legacyMotionOf(st: AnimatorState): AnimatorMotion | null {+ if (st.spine) return { kind: SPINE_MOTION, clip: st.spine.animation, loop: st.spine.loop };+ if (st.blend) return spriteBlendMotion(st, st.blend);+ if (st.clip) return { kind: SPRITE_MOTION, clip: st.clip, speed: st.speed, loop: st.loop };+ return null;+}++/**+ * What a state plays. A file is normalized on load, so this converts only for a+ * controller built in code with the older fields — which nothing new writes, and+ * which stays readable rather than becoming a silent no-motion.* Null for a state with no motion of its own (a container).*/export function motionOf(st: AnimatorState): AnimatorMotion | null {+ if (st.motion) return st.motion;const cached = migratedMotions.get(st);if (cached !== undefined) return cached;-- let motion: AnimatorMotion | null = null;- if (st.motion) motion = st.motion;- else if (st.spine) {- motion = { kind: SPINE_MOTION, clip: st.spine.animation, loop: st.spine.loop };- } else if (st.blend) motion = spriteBlendMotion(st, st.blend);- else if (st.clip) {- motion = { kind: SPRITE_MOTION, clip: st.clip, speed: st.speed, loop: st.loop };- }+ const motion = legacyMotionOf(st);migratedMotions.set(st, motion);return motion;diff --git a/sdk/src/animation/animatorMigrate.ts b/sdk/src/animation/animatorMigrate.tsindex 93d03f956..b734db4f2 100644--- a/sdk/src/animation/animatorMigrate.ts+++ b/sdk/src/animation/animatorMigrate.ts@@ -13,8 +13,8 @@*/import {- ANIMATOR_FORMAT_VERSION,- type AnimatorControllerDef, type AnimatorLayer,+ ANIMATOR_FORMAT_VERSION, legacyMotionOf,+ type AnimatorControllerDef, type AnimatorLayer, type AnimatorScope, type AnimatorState,} from './Animator';/** What a pass over a controller blob came to. */@@ -75,12 +75,36 @@ export function migrateAnimatorController(raw: unknown): AnimatorMigration {if (fromVersion === ANIMATOR_FORMAT_VERSION) {return { def, migrated: false, fromVersion };}- // Version 1 is version 2 without layers, which reads correctly as a stack of- // one. Stamping it is the whole upgrade, and it is what makes a re-save land- // on a file the guard above will recognise.+ // Version 1 is version 2 without layers — a stack of one — whose states may+ // spell a motion any of four ways. Folding those into `motion` here lets+ // every later reader ask one question instead of four.return {- def: { ...def, version: ANIMATOR_FORMAT_VERSION },+ def: { ...normalizeScope(def), version: ANIMATOR_FORMAT_VERSION, layers: def.layers?.map(normalizeLayer) },migrated: true,fromVersion,};}++/** A state whose motion is spelled the one way, with the older spellings gone —+ * left in place they would be a second answer nothing reconciles. */+function normalizeState(state: AnimatorState): AnimatorState {+ const next: AnimatorState = { ...state };+ const motion = state.motion ?? legacyMotionOf(state);+ delete next.clip;+ delete next.blend;+ delete next.spine;+ if (motion) next.motion = motion;+ else delete next.motion;+ if (state.stateMachine) {+ next.stateMachine = { ...state.stateMachine, states: state.stateMachine.states.map(normalizeState) };+ }+ return next;+}++function normalizeScope<T extends AnimatorScope>(scope: T): T {+ return { ...scope, states: scope.states.map(normalizeState) };+}++function normalizeLayer(layer: AnimatorLayer): AnimatorLayer {+ return normalizeScope(layer);+}diff --git a/sdk/tests/animatorLayers.test.ts b/sdk/tests/animatorLayers.test.tsindex b253d68e5..6b3a1896a 100644--- a/sdk/tests/animatorLayers.test.ts+++ b/sdk/tests/animatorLayers.test.ts@@ -380,6 +380,56 @@ describe('the controller format guard', () => {.toThrow(/version/);});+ it('folds the four older spellings of a motion into the one', () => {+ // A v1 file could say what a state plays as `clip`, `blend` or `spine`.+ // Left alone, every later reader has to ask four questions — which is how+ // the editor's node label came to answer only three of them.+ const { def } = migrateAnimatorController({+ parameters: [{ name: 'speed', type: 'float' }],+ initialState: 'Idle',+ states: [+ { name: 'Idle', clip: 'idle', speed: 2, loop: true, transitions: [] },+ { name: 'Talk', spine: { animation: 'talk', loop: false }, transitions: [] },+ {+ name: 'Move', transitions: [],+ blend: { parameter: 'speed', thresholds: [{ value: 0, clip: 'walk' }] },+ },+ {+ name: 'Combat', transitions: [],+ stateMachine: { initialState: 'Swing', states: [{ name: 'Swing', clip: 'swing', transitions: [] }] },+ },+ ],+ });++ const byName = new Map(def.states.map((s) => [s.name, s]));+ expect(byName.get('Idle')!.motion).toEqual({ kind: 'sprite', clip: 'idle', speed: 2, loop: true });+ expect(byName.get('Talk')!.motion).toEqual({ kind: 'spine', clip: 'talk', loop: false });+ expect(byName.get('Move')!.motion).toMatchObject({ kind: 'blend1d', parameter: 'speed' });+ // Down a nested machine too, or a sub-state keeps the old shape alone.+ expect(byName.get('Combat')!.stateMachine!.states[0]!.motion)+ .toEqual({ kind: 'sprite', clip: 'swing', speed: undefined, loop: undefined });++ // And the older spellings are GONE, not merely shadowed.+ for (const state of def.states) {+ expect(state.clip).toBeUndefined();+ expect(state.blend).toBeUndefined();+ expect(state.spine).toBeUndefined();+ }+ });++ it('folds them inside a layer as well', () => {+ const { def } = migrateAnimatorController({+ parameters: [], initialState: 'Idle',+ states: [{ name: 'Idle', transitions: [] }],+ layers: [{+ name: 'Upper', initialState: 'Wave',+ states: [{ name: 'Wave', clip: 'wave', transitions: [] }],+ }],+ });+ expect(def.layers![0]!.states[0]!.motion).toMatchObject({ kind: 'sprite', clip: 'wave' });+ expect(def.layers![0]!.states[0]!.clip).toBeUndefined();+ });+it('refuses a layer that is not a machine', () => {expect(() => migrateAnimatorController({ ...v1(), layers: [{ name: 'arms' }] })).toThrow(/layer/);