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.

refactor(anim): a state says what it plays one way, from the file in

esengine181361432b1e
diff --git a/desktop b/desktop
index 3acf1b56c..ced6c9cb9 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 3acf1b56c1a85cd3cd822cc4c4c54998490cd6f1
+Subproject commit ced6c9cb96a3853cd26b6a4065669240d98870fc
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.ts
index 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.ts
index 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.ts
index 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/);