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(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.mdindex 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 | undefinedik: AnimatorIK[] | undefinedinitialState: stringlayers: AnimatorLayer[] | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 | undefinedik: AnimatorIK[] | undefinedinitialState: stringlayers: AnimatorLayer[] | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 | undefinedik: AnimatorIK[] | undefinedinitialState: stringlayers: AnimatorLayer[] | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 | undefinedik: AnimatorIK[] | undefinedinitialState: stringlayers: AnimatorLayer[] | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 | undefinedik: AnimatorIK[] | undefinedinitialState: stringlayers: AnimatorLayer[] | undefineddiff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex 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.tsindex 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.tsindex 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/);+ });+});