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(anim): a clip means the same thing on a rig bound differently

esengine697ab950c97e
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 4b45a1188..0bf61720a 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -410,6 +410,7 @@ ComponentDef<AnimatorData>
## AnimatorAvatar — interface @experimental
```
joints: Record<string, string>
+rest: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -498,6 +499,7 @@ static prototype: AnimatorControllerAPI
## AnimatorControllerDef — interface @experimental
```
anyStateTransitions: AnimatorTransition[] | undefined
+avatar: string | undefined
ik: AnimatorIK[] | undefined
initialState: string
layers: AnimatorLayer[] | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index ff357a01e..94b514fd4 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -410,6 +410,7 @@ ComponentDef<AnimatorData>
## AnimatorAvatar — interface @experimental
```
joints: Record<string, string>
+rest: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -498,6 +499,7 @@ static prototype: AnimatorControllerAPI
## AnimatorControllerDef — interface @experimental
```
anyStateTransitions: AnimatorTransition[] | undefined
+avatar: string | undefined
ik: AnimatorIK[] | undefined
initialState: string
layers: AnimatorLayer[] | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 0e1c1330e..6aafb944e 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -405,6 +405,7 @@ ComponentDef<AnimatorData>
## AnimatorAvatar — interface @experimental
```
joints: Record<string, string>
+rest: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -493,6 +494,7 @@ static prototype: AnimatorControllerAPI
## AnimatorControllerDef — interface @experimental
```
anyStateTransitions: AnimatorTransition[] | undefined
+avatar: string | undefined
ik: AnimatorIK[] | undefined
initialState: string
layers: AnimatorLayer[] | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index f310d3ad3..3d9e7bb64 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -405,6 +405,7 @@ ComponentDef<AnimatorData>
## AnimatorAvatar — interface @experimental
```
joints: Record<string, string>
+rest: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -493,6 +494,7 @@ static prototype: AnimatorControllerAPI
## AnimatorControllerDef — interface @experimental
```
anyStateTransitions: AnimatorTransition[] | undefined
+avatar: string | undefined
ik: AnimatorIK[] | undefined
initialState: string
layers: AnimatorLayer[] | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 83aa4e15c..7997b9d15 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -405,6 +405,7 @@ ComponentDef<AnimatorData>
## AnimatorAvatar — interface @experimental
```
joints: Record<string, string>
+rest: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -493,6 +494,7 @@ static prototype: AnimatorControllerAPI
## AnimatorControllerDef — interface @experimental
```
anyStateTransitions: AnimatorTransition[] | undefined
+avatar: string | undefined
ik: AnimatorIK[] | undefined
initialState: string
layers: AnimatorLayer[] | undefined
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.ts
index bd0dfd710..dc8c30ffd 100644
--- a/sdk/src/animation/Animator.ts
+++ b/sdk/src/animation/Animator.ts
@@ -32,7 +32,9 @@ import { Pose } from './pose';
import { mixPoses, type WeightedPose } from './poseMix';
import { overlayPose, addPoseOver } from './layerStack';
import { MaskReach, type AnimatorMask } from './animatorMask';
-import { avatarResolver, type AnimatorAvatar, type JointResolver } from './animatorAvatar';
+import {
+ avatarResolver, rebasePose, type AnimatorAvatar, type JointResolver,
+} from './animatorAvatar';
import { solveAnimatorIK, type AnimatorIK } from './animatorIK';
import { AnimatorRootMotion, type AnimatorRootMotionData } from './animatorRootMotion';
import type { AnimatorEventSink } from './animatorEvent';
@@ -190,6 +192,13 @@ export interface AnimatorControllerDef {
initialState: string;
/** Transitions evaluated from every state, before the current state's own. */
anyStateTransitions?: AnimatorTransition[];
+ /**
+ * The `.esavatar` this controller's CLIPS were authored against. With one on
+ * the rig as well, a pose is restated from that rig's bind pose to this one;
+ * without it a name map alone is only right between rigs that share a bind
+ * pose.
+ */
+ avatar?: string;
/** Layers over the base one, laid down in order. */
layers?: AnimatorLayer[];
/**
@@ -674,11 +683,9 @@ export class AnimatorControllerAPI {
this.assetAvatars_ = source;
}
- /** The resolver this rig's joints are found through this frame. */
- private jointsOf(world: World, data: AnimatorData): JointResolver {
- const ref = data.avatar;
- const avatar = ref ? this.assetAvatars_?.(ref) ?? null : null;
- return avatarResolver(world, avatar);
+ /** This rig's avatar, or null where its clips need no translating. */
+ private avatarOf(ref: string | undefined): AnimatorAvatar | null {
+ return ref ? this.assetAvatars_?.(ref) ?? null : null;
}
getController(name: string): AnimatorControllerDef | undefined {
@@ -757,7 +764,9 @@ export class AnimatorControllerAPI {
const count = animatorLayerCount(def);
const params = resolveParams(def, this.params.get(entity) ?? EMPTY_PARAMS);
- const joints = this.jointsOf(world, a);
+ const rig = this.avatarOf(a.avatar);
+ const clips = this.avatarOf(def.avatar);
+ const joints = avatarResolver(world, rig);
const ctx = this.motions_.context(world, entity, params, joints);
const rt = this.runtimeFor(entity, count);
rt.composed.reset();
@@ -772,6 +781,11 @@ export class AnimatorControllerAPI {
// machines answer cannot depend on which was stepped first.
const triggers = this.triggers.get(entity);
if (triggers) for (const t of this.spentTriggers_) triggers.delete(t);
+ // Restating the stack for THIS rig comes before the constraints:
+ // they measure where joints are, and this is what moves them.
+ if (wrote && rig && clips) {
+ rebasePose(rt.composed, entity, clips, rig, joints, world);
+ }
// Constraints read the stack's answer and bend it, so they run
// between composing and writing — on the pose this frame stated,
// never on the world's record of the last one.
diff --git a/sdk/src/animation/animatorAvatar.ts b/sdk/src/animation/animatorAvatar.ts
index fcbb3586d..596dff4d4 100644
--- a/sdk/src/animation/animatorAvatar.ts
+++ b/sdk/src/animation/animatorAvatar.ts
@@ -22,8 +22,12 @@
import type { Entity } from '../types';
import type { World } from '../ecs/world';
import { resolveChildEntity } from '../ecs/childPath';
+import { Transform } from '../ecs/component';
+import { q } from '../math/quat';
+import type { Pose, PoseWorld } from './pose';
+import type { QuatLike } from './quatMix';
-/** A rig's own spelling for each joint a clip may name. */
+/** A rig's own spelling for each joint a clip may name, and how it stands at rest. */
export interface AnimatorAvatar {
/**
* The name a clip uses → the `childPath` this rig reaches that joint by. A
@@ -31,8 +35,17 @@ export interface AnimatorAvatar {
* keeps working and an avatar can translate only what differs.
*/
joints: Record<string, string>;
+ /**
+ * Each joint's rotation in the BIND pose, by the name `joints` uses. What a
+ * clip states is where a joint is, and what it MEANS is the offset from where
+ * that joint rests — two rigs bound differently need this to read one clip
+ * the same way. Absent for a rig nothing is retargeted onto.
+ */
+ rest?: Record<string, Quat>;
}
+interface Quat { w: number; x: number; y: number; z: number }
+
/** Finding a joint on a rig, whichever way a clip spelled it. */
export type JointResolver = (root: Entity, path: string) => Entity | null;
@@ -68,7 +81,26 @@ export function parseAvatar(raw: unknown): AnimatorAvatar {
// An entry mapping a name to itself is what having no entry already means.
if (path && path !== name) out[name] = path;
}
- return { joints: out };
+ const rest = obj['rest'] === undefined ? undefined : readRest(obj['rest']);
+ return rest ? { joints: out, rest } : { joints: out };
+}
+
+/** The bind pose, one rotation per joint. A joint listed without a usable
+ * rotation is refused rather than defaulted: an identity nobody meant would
+ * rebase every clip through a pose the rig is not in. */
+function readRest(raw: unknown): Record<string, Quat> {
+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+ throw new Error('Avatar "rest" must be an object of joint rotations');
+ }
+ const out: Record<string, Quat> = {};
+ for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+ const q = value as Partial<Quat> | null;
+ if (!q || ['w', 'x', 'y', 'z'].some((k) => typeof q[k as 'w'] !== 'number')) {
+ throw new Error(`Avatar rest pose for "${name}" must be a quaternion`);
+ }
+ out[name] = { w: q.w!, x: q.x!, y: q.y!, z: q.z! };
+ }
+ return out;
}
/** A blank avatar, which translates nothing and resolves every path as itself. */
@@ -87,3 +119,31 @@ export function avatarResolver(
if (!avatar) return (root, path) => resolveChildEntity(world, root, path);
return (root, path) => resolveChildEntity(world, root, avatar.joints[path] ?? path);
}
+
+/**
+ * Re-state `pose` as this rig would stand it: a clip says where a joint IS and
+ * MEANS the offset from its rest, so another bind pose needs
+ * `targetRest · sourceRest⁻¹`. Once on the stack's answer — composing commutes
+ * with a left multiplication — and before the constraints, which read positions.
+ */
+export function rebasePose(
+ pose: Pose, root: Entity, source: AnimatorAvatar, target: AnimatorAvatar,
+ resolveJoint: JointResolver, world: PoseWorld,
+): void {
+ const from = source.rest;
+ const to = target.rest;
+ if (!from || !to) return;
+ for (const [joint, sourceRest] of Object.entries(from)) {
+ const targetRest = to[joint];
+ if (!targetRest) continue;
+ const entity = resolveJoint(root, joint);
+ if (entity === null) continue;
+ const track = pose.track(world, entity, Transform);
+ if (!track || !track.touched.has('rotation')) continue;
+ const stated = track.data.rotation as QuatLike | undefined;
+ if (!stated) continue;
+ const offset = q.mul(q.conjugate(sourceRest), stated);
+ const rebased = q.normalize(q.mul(targetRest, offset));
+ track.data.rotation = { w: rebased.w, x: rebased.x, y: rebased.y, z: rebased.z };
+ }
+}
diff --git a/sdk/tests/animatorAvatar.test.ts b/sdk/tests/animatorAvatar.test.ts
index 5aff4fe64..2a91bb17d 100644
--- a/sdk/tests/animatorAvatar.test.ts
+++ b/sdk/tests/animatorAvatar.test.ts
@@ -230,3 +230,98 @@ describe('one clip over two rigs', () => {
expect(facingY).toBeCloseTo(100 / Math.hypot(50, 100), 3);
});
});
+
+// ---------------------------------------------------------------------------
+// Rigs bound in different poses
+// ---------------------------------------------------------------------------
+
+/** A quarter turn about Z, as a quaternion. */
+const quarterZ = { w: Math.SQRT1_2, x: 0, y: 0, z: Math.SQRT1_2 };
+const identityQ = { w: 1, x: 0, y: 0, z: 0 };
+
+describe('one clip over rigs bound differently', () => {
+ /**
+ * The source rig rests with its arm down (identity); the target rests with it
+ * already out (a quarter turn). The clip says "arm at a quarter turn", which
+ * on the source rig means "raised by a quarter turn" — and that is what the
+ * target has to end up doing, from ITS rest, not the absolute value.
+ */
+ function rebased(withRest: boolean) {
+ const world = makeWorld();
+ rig(world, 1, 2, 'Arm');
+ world.update(2, Transform, (t: any) => { t.rotation = { ...quarterZ }; });
+
+ const clips = parseAvatar({ joints: {}, rest: { Arm: identityQ } });
+ const target = parseAvatar({ joints: {}, rest: { Arm: quarterZ } });
+ const avatars: Record<string, AnimatorAvatar> = {
+ 'assets/clips.esavatar': withRest ? clips : parseAvatar({ joints: {} }),
+ 'assets/rig.esavatar': withRest ? target : parseAvatar({ joints: {} }),
+ };
+
+ const timeline = new TimelineAPI();
+ timeline.registerAsset('wave.estimeline', turn('Arm'));
+ const ctrl = new AnimatorControllerAPI();
+ ctrl.registerMotionDriver(TIMELINE_MOTION, createTimelineMotionDriver(timeline));
+ ctrl.useAssetAvatars((ref) => avatars[ref]);
+ ctrl.registerController('rig', {
+ version: 2, parameters: [], initialState: 'Wave',
+ avatar: 'assets/clips.esavatar',
+ states: [{
+ name: 'Wave', transitions: [],
+ motion: { kind: TIMELINE_MOTION, clip: 'wave.estimeline', loop: true },
+ }],
+ } as AnimatorControllerDef);
+ attach(world, 1, 'assets/rig.esavatar');
+ ctrl.update(world, 0.016);
+ return (world.get(2, Transform) as { rotation: { z: number; w: number } }).rotation;
+ }
+
+ it('restates the clip from the target rig’s own rest pose', () => {
+ // The clip's quarter turn is a quarter turn OFF the source rest, so off a
+ // target resting at a quarter turn it lands at a half — z = 1.
+ const r = rebased(true);
+ expect(r.z).toBeCloseTo(1, 4);
+ expect(r.w).toBeCloseTo(0, 4);
+ });
+
+ it('takes the clip literally when neither rig states a rest pose', () => {
+ // The older behaviour, and the right one for rigs that share a bind pose:
+ // no rest is not an identity rest, it is nothing to rebase against.
+ const r = rebased(false);
+ expect(r.z).toBeCloseTo(Math.SQRT1_2, 4);
+ });
+
+ it('leaves a joint alone when only one side states its rest', () => {
+ // The source rest is deliberately NOT the identity: a missing target rest
+ // defaulted to one would rebase by its inverse, and with both at identity
+ // that mistake reads exactly like doing nothing.
+ const world = makeWorld();
+ rig(world, 1, 2, 'Arm');
+ const avatars: Record<string, AnimatorAvatar> = {
+ 'assets/clips.esavatar': parseAvatar({ joints: {}, rest: { Arm: quarterZ } }),
+ 'assets/rig.esavatar': parseAvatar({ joints: {}, rest: { Leg: quarterZ } }),
+ };
+ const timeline = new TimelineAPI();
+ timeline.registerAsset('wave.estimeline', turn('Arm'));
+ const ctrl = new AnimatorControllerAPI();
+ ctrl.registerMotionDriver(TIMELINE_MOTION, createTimelineMotionDriver(timeline));
+ ctrl.useAssetAvatars((ref) => avatars[ref]);
+ ctrl.registerController('rig', {
+ version: 2, parameters: [], initialState: 'Wave',
+ avatar: 'assets/clips.esavatar',
+ states: [{
+ name: 'Wave', transitions: [],
+ motion: { kind: TIMELINE_MOTION, clip: 'wave.estimeline', loop: true },
+ }],
+ } as AnimatorControllerDef);
+ attach(world, 1, 'assets/rig.esavatar');
+ ctrl.update(world, 0.016);
+ expect(turnedZ(world, 2)).toBeCloseTo(Math.SQRT1_2, 4);
+ });
+
+ it('refuses a rest pose that is not a rotation', () => {
+ expect(() => parseAvatar({ joints: {}, rest: { Arm: { w: 1, x: 0, y: 0 } } }))
+ .toThrow(/quaternion/);
+ expect(() => parseAvatar({ joints: {}, rest: [] })).toThrow(/rest/);
+ });
+});