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.

fix(animation): a controller loads the avatar its clips were authored on, and retargets through each rig's space

esengine4a37ffdaff09
diff --git a/examples/character-rig/assets/models/hero.esavatar b/examples/character-rig/assets/models/hero.esavatar
index a600fdf7f..abdf4355f 100644
--- a/examples/character-rig/assets/models/hero.esavatar
+++ b/examples/character-rig/assets/models/hero.esavatar
@@ -99,5 +99,185 @@
"z": 0.0003434528480283916
}
},
+ "space": {
+ "root/DEF-hips": {
+ "w": 0.7071067690849304,
+ "x": -0.7071067690849304,
+ "y": 0,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001": {
+ "w": 0.9920504802224741,
+ "x": 0.125840709431003,
+ "y": 1.4782702862155118e-8,
+ "z": 1.8751739520534662e-9
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003": {
+ "w": 0.9998731715541991,
+ "x": -0.015928951234792894,
+ "y": 7.027970658721768e-8,
+ "z": -1.1196232742446895e-9
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-neck/DEF-head": {
+ "w": 0.9954893762009059,
+ "x": 0.09487399932898441,
+ "y": 5.979753335128647e-8,
+ "z": 5.698939853194107e-9
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L": {
+ "w": 0.6136853649472832,
+ "x": -0.6140414441519573,
+ "y": -0.3508356407409364,
+ "z": -0.35108109675827587
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L/DEF-forearm.L": {
+ "w": 0.70708074697136,
+ "x": -0.006040765268700121,
+ "y": 0.006069376938414181,
+ "z": -0.7070811243748809
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L/DEF-forearm.L/DEF-hand.L": {
+ "w": 0.7070807249581842,
+ "x": 0.006095001902201371,
+ "y": -0.006095154316830085,
+ "z": -0.7070805231388853
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R": {
+ "w": 0.6136854400485765,
+ "x": -0.6140413990039163,
+ "y": 0.3508356619926334,
+ "z": 0.351081085503358
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R/DEF-forearm.R": {
+ "w": 0.7070808342237526,
+ "x": -0.006040540443391029,
+ "y": -0.006069493123151484,
+ "z": 0.7070810993767108
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R/DEF-forearm.R/DEF-hand.R": {
+ "w": 0.7070806542883269,
+ "x": 0.006095170903489939,
+ "y": 0.006095237246226347,
+ "z": 0.707080655417162
+ },
+ "root/DEF-hips/DEF-thigh.L": {
+ "w": 0.9920504802224741,
+ "x": 0.125840709431003,
+ "y": 1.4782702862155118e-8,
+ "z": 1.8751739520534662e-9
+ },
+ "root/DEF-hips/DEF-thigh.L/DEF-shin.L": {
+ "w": -0.0034973042505719283,
+ "x": 0.999993917282955,
+ "y": 3.566568530870014e-9,
+ "z": 1.5146563251741725e-8
+ },
+ "root/DEF-hips/DEF-thigh.L/DEF-shin.L/DEF-foot.L": {
+ "w": -0.04008061146571069,
+ "x": 0.9991964900644467,
+ "y": 0.0000052610070791321524,
+ "z": -0.00013115520150174822
+ },
+ "root/DEF-hips/DEF-thigh.R": {
+ "w": 0.9920504802224741,
+ "x": 0.125840709431003,
+ "y": 1.4782702862155118e-8,
+ "z": 1.8751739520534662e-9
+ },
+ "root/DEF-hips/DEF-thigh.R/DEF-shin.R": {
+ "w": -0.0034973116419241305,
+ "x": 0.9999939163453692,
+ "y": 3.4295654289848177e-9,
+ "z": 5.432179443190842e-8
+ },
+ "root/DEF-hips/DEF-thigh.R/DEF-shin.R/DEF-foot.R": {
+ "w": -0.0400806188176421,
+ "x": 0.9991964888622117,
+ "y": 0.000005261007382454338,
+ "z": -0.00013115516765141308
+ }
+ },
+ "restPosition": {
+ "root/DEF-hips": {
+ "x": 0,
+ "y": 0.05010002851486206,
+ "z": 0.916700005531311
+ },
+ "root/DEF-hips/DEF-spine.001": {
+ "x": -5.828670879282072e-16,
+ "y": 0.1381763368844986,
+ "z": 1.7695128917694092e-8
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003": {
+ "x": 5.036120679381944e-16,
+ "y": 0.14127187430858612,
+ "z": 9.313225746154785e-10
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-neck/DEF-head": {
+ "x": 3.8571792481745856e-15,
+ "y": 0.08258674293756485,
+ "z": -2.0023435354232788e-8
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L": {
+ "x": -0.030072327703237534,
+ "y": 0.21858172118663788,
+ "z": -0.016968311741948128
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L/DEF-forearm.L": {
+ "x": -1.1901104812750418e-7,
+ "y": 0.27444028854370117,
+ "z": 1.1048541637137532e-8
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L/DEF-forearm.L/DEF-hand.L": {
+ "x": 3.1413728152074327e-7,
+ "y": 0.2726406157016754,
+ "z": -7.710582394793164e-9
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R": {
+ "x": 0.030072307214140892,
+ "y": 0.21858170628547668,
+ "z": -0.016968434676527977
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R/DEF-forearm.R": {
+ "x": 8.920900995690317e-8,
+ "y": 0.2744402289390564,
+ "z": -1.4075340004637837e-8
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R/DEF-forearm.R/DEF-hand.R": {
+ "x": -1.1331076166243292e-7,
+ "y": 0.2726404368877411,
+ "z": 3.2101823421726294e-9
+ },
+ "root/DEF-hips/DEF-thigh.L": {
+ "x": 0.08899997919797897,
+ "y": 0.027770835906267166,
+ "z": 0.04602379724383354
+ },
+ "root/DEF-hips/DEF-thigh.L/DEF-shin.L": {
+ "x": 1.1145173672844066e-8,
+ "y": 0.40030965209007263,
+ "z": -1.0012035644990647e-10
+ },
+ "root/DEF-hips/DEF-thigh.L/DEF-shin.L/DEF-foot.L": {
+ "x": -7.291419024113566e-9,
+ "y": 0.4294799864292145,
+ "z": -2.9831426218152046e-10
+ },
+ "root/DEF-hips/DEF-thigh.R": {
+ "x": -0.08899997919797897,
+ "y": 0.027770835906267166,
+ "z": 0.04602379351854324
+ },
+ "root/DEF-hips/DEF-thigh.R/DEF-shin.R": {
+ "x": -2.6508853778750563e-8,
+ "y": 0.4003097712993622,
+ "z": 4.610640758073714e-10
+ },
+ "root/DEF-hips/DEF-thigh.R/DEF-shin.R/DEF-foot.R": {
+ "x": 2.250203579023946e-8,
+ "y": 0.42947983741760254,
+ "z": -5.293259164318442e-9
+ }
+ },
"scale": 1.620542033130155
}
diff --git a/examples/character-rig/assets/models/knight.esavatar b/examples/character-rig/assets/models/knight.esavatar
index ab96632ec..f741d5b83 100644
--- a/examples/character-rig/assets/models/knight.esavatar
+++ b/examples/character-rig/assets/models/knight.esavatar
@@ -116,5 +116,185 @@
"z": 2.2509516472979385e-9
}
},
+ "space": {
+ "root/DEF-hips": {
+ "w": 1,
+ "x": 0,
+ "y": 1.1920927533992653e-7,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001": {
+ "w": 1.0000000000000142,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003": {
+ "w": 1.0000000000000142,
+ "x": 0,
+ "y": 7.105427357601103e-15,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-neck/DEF-head": {
+ "w": 1.0000000000000142,
+ "x": 0,
+ "y": 7.105427357601103e-15,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L": {
+ "w": 1.0000000000000142,
+ "x": 0,
+ "y": 7.105427357601103e-15,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L/DEF-forearm.L": {
+ "w": 0.514121890068065,
+ "x": -0.5141214728355515,
+ "y": -0.48546779155731523,
+ "z": -0.48546776175499284
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L/DEF-forearm.L/DEF-hand.L": {
+ "w": 0.5000029446825832,
+ "x": -0.5000025849018902,
+ "y": -0.49999744566173104,
+ "z": -0.49999736636722913
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R": {
+ "w": 1.0000000000000142,
+ "x": 0,
+ "y": 7.105427357601103e-15,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R/DEF-forearm.R": {
+ "w": 0.5141219496727029,
+ "x": -0.5141214132308999,
+ "y": 0.4854677319526778,
+ "z": 0.48546776175500017
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R/DEF-forearm.R/DEF-hand.R": {
+ "w": 0.5000030042627621,
+ "x": -0.5000025270292873,
+ "y": 0.49999738437397245,
+ "z": 0.49999736807482303
+ },
+ "root/DEF-hips/DEF-thigh.L": {
+ "w": 1.0000000000000142,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-thigh.L/DEF-shin.L": {
+ "w": 0.01737319119274641,
+ "x": 0.9998490810394429,
+ "y": -7.132756252303909e-8,
+ "z": -1.2042738362083753e-8
+ },
+ "root/DEF-hips/DEF-thigh.L/DEF-shin.L/DEF-foot.L": {
+ "w": -0.08893421171598895,
+ "x": 0.9960376124897008,
+ "y": 2.7482138202625033e-9,
+ "z": 6.296305041347065e-8
+ },
+ "root/DEF-hips/DEF-thigh.R": {
+ "w": 1.0000000000000142,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-thigh.R/DEF-shin.R": {
+ "w": 0.01737319119274641,
+ "x": 0.9998490810394429,
+ "y": 7.426564252455243e-8,
+ "z": -3.17262731641681e-8
+ },
+ "root/DEF-hips/DEF-thigh.R/DEF-shin.R/DEF-foot.R": {
+ "w": -0.08893421171598552,
+ "x": 0.996037612489698,
+ "y": -4.4761265056627565e-9,
+ "z": -1.0679653814181822e-7
+ }
+ },
+ "restPosition": {
+ "root/DEF-hips": {
+ "x": 0,
+ "y": 0.4056634306907654,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001": {
+ "x": 0,
+ "y": 0.19197750091552734,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003": {
+ "x": 0,
+ "y": 0.37498795986175537,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-neck/DEF-head": {
+ "x": 0,
+ "y": 0.26879656314849854,
+ "z": 0
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L": {
+ "x": 0.21200737357139587,
+ "y": 0.13413214683532715,
+ "z": 8.40246201505579e-8
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L/DEF-forearm.L": {
+ "x": -3.219664979070558e-9,
+ "y": 0.24189729988574982,
+ "z": -1.1940561250867177e-7
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.L/DEF-upper_arm.L/DEF-forearm.L/DEF-hand.L": {
+ "x": 9.08162434143378e-13,
+ "y": 0.07382583618164062,
+ "z": 2.220446049250313e-16
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R": {
+ "x": -0.21200737357139587,
+ "y": 0.13413214683532715,
+ "z": 8.40246201505579e-8
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R/DEF-forearm.R": {
+ "x": -7.121856576697283e-11,
+ "y": 0.2418973296880722,
+ "z": -1.1940561250867177e-7
+ },
+ "root/DEF-hips/DEF-spine.001/DEF-spine.002/DEF-spine.003/DEF-shoulder.R/DEF-upper_arm.R/DEF-forearm.R/DEF-hand.R": {
+ "x": 1.3322676295501878e-15,
+ "y": 0.07382583618164062,
+ "z": 2.220446049250313e-16
+ },
+ "root/DEF-hips/DEF-thigh.L": {
+ "x": 0.17094506323337555,
+ "y": 0.11358726024627686,
+ "z": 1.392327231286572e-8
+ },
+ "root/DEF-hips/DEF-thigh.L/DEF-shin.L": {
+ "x": 3.5798182196344897e-9,
+ "y": 0.22707749903202057,
+ "z": -6.1398597317463555e-9
+ },
+ "root/DEF-hips/DEF-thigh.L/DEF-shin.L/DEF-foot.L": {
+ "x": 1.8322229844436322e-10,
+ "y": 0.14943702518939972,
+ "z": 9.665366285105392e-10
+ },
+ "root/DEF-hips/DEF-thigh.R": {
+ "x": -0.17094506323337555,
+ "y": 0.11358726024627686,
+ "z": 1.392327231286572e-8
+ },
+ "root/DEF-hips/DEF-thigh.R/DEF-shin.R": {
+ "x": -3.5798182196344897e-9,
+ "y": 0.22707749903202057,
+ "z": -6.1398597317463555e-9
+ },
+ "root/DEF-hips/DEF-thigh.R/DEF-shin.R/DEF-foot.R": {
+ "x": -1.832210216878849e-10,
+ "y": 0.14943702518939972,
+ "z": 9.665415134918476e-10
+ }
+ },
"scale": 1.3714490056392945
}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 4522386b9..b19d25c05 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -429,7 +429,9 @@ ComponentDef<AnimatorData>
```
joints: Record<string, string>
rest: Record<string, Quat> | undefined
+restPosition: Record<string, Vec3> | undefined
scale: number | undefined
+space: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -3567,6 +3569,7 @@ visited: Set<string> | undefined
```
entities: ProcessedEntity[]
rootId: number
+unresolved: PrefabOverride[]
```
## FlexContainer — const @experimental
@@ -10660,12 +10663,12 @@ EventBindingPlugin
## expandEntry — function @experimental
```
-(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## expandInstance — function @experimental
```
-(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## extendPlatform — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 099a681f9..d5c3880f5 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -429,7 +429,9 @@ ComponentDef<AnimatorData>
```
joints: Record<string, string>
rest: Record<string, Quat> | undefined
+restPosition: Record<string, Vec3> | undefined
scale: number | undefined
+space: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -3575,6 +3577,7 @@ visited: Set<string> | undefined
```
entities: ProcessedEntity[]
rootId: number
+unresolved: PrefabOverride[]
```
## FlexContainer — const @experimental
@@ -10893,12 +10896,12 @@ EventBindingPlugin
## expandEntry — function @experimental
```
-(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## expandInstance — function @experimental
```
-(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## extendPlatform — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index dc6f3660c..9fa2c815d 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -424,7 +424,9 @@ ComponentDef<AnimatorData>
```
joints: Record<string, string>
rest: Record<string, Quat> | undefined
+restPosition: Record<string, Vec3> | undefined
scale: number | undefined
+space: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -3562,6 +3564,7 @@ visited: Set<string> | undefined
```
entities: ProcessedEntity[]
rootId: number
+unresolved: PrefabOverride[]
```
## FlexContainer — const @experimental
@@ -10655,12 +10658,12 @@ EventBindingPlugin
## expandEntry — function @experimental
```
-(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## expandInstance — function @experimental
```
-(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## extendPlatform — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 4bf28ff91..db65f477b 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -424,7 +424,9 @@ ComponentDef<AnimatorData>
```
joints: Record<string, string>
rest: Record<string, Quat> | undefined
+restPosition: Record<string, Vec3> | undefined
scale: number | undefined
+space: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -3562,6 +3564,7 @@ visited: Set<string> | undefined
```
entities: ProcessedEntity[]
rootId: number
+unresolved: PrefabOverride[]
```
## FlexContainer — const @experimental
@@ -10929,12 +10932,12 @@ EventBindingPlugin
## expandEntry — function @experimental
```
-(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## expandInstance — function @experimental
```
-(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## extendPlatform — function @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 44252276e..055fe14d0 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -424,7 +424,9 @@ ComponentDef<AnimatorData>
```
joints: Record<string, string>
rest: Record<string, Quat> | undefined
+restPosition: Record<string, Vec3> | undefined
scale: number | undefined
+space: Record<string, Quat> | undefined
```
## AnimatorBlend1D — interface @experimental
@@ -3562,6 +3564,7 @@ visited: Set<string> | undefined
```
entities: ProcessedEntity[]
rootId: number
+unresolved: PrefabOverride[]
```
## FlexContainer — const @experimental
@@ -10684,12 +10687,12 @@ EventBindingPlugin
## expandEntry — function @experimental
```
-(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, entry: PrefabInstanceEntry, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## expandInstance — function @experimental
```
-(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; }
+(prefab: PrefabData, delta: PrefabInstanceDelta, allocateId: () => number, loadPrefab?: SyncPrefabResolver): { entities: ProcessedEntity[]; rootId: number; unresolved: PrefabOverride[]; }
```
## extendPlatform — function @experimental
diff --git a/sdk/src/animation/animatorAvatar.ts b/sdk/src/animation/animatorAvatar.ts
index dc0c445ec..2ae47cae6 100644
--- a/sdk/src/animation/animatorAvatar.ts
+++ b/sdk/src/animation/animatorAvatar.ts
@@ -42,6 +42,16 @@ export interface AnimatorAvatar {
* the same way. Absent for a rig nothing is retargeted onto.
*/
rest?: Record<string, Quat>;
+ /**
+ * Each joint's PARENT at rest, as a rotation in the rig's own space — what a
+ * joint's local values are expressed in. Two rigs whose skeletons stand on
+ * different axes (one Z-up under a turned root, one Y-up) read one clip the
+ * same way only through this. Absent is the identity.
+ */
+ space?: Record<string, Quat>;
+ /** Each joint's local position at rest: a clip that moves a joint (the hips)
+ * moves it FROM here, so another rig needs its own. */
+ restPosition?: Record<string, Vec3>;
/**
* Root to the joint furthest from it, at rest — the ONE measure every avatar
* uses, since two measured differently give a ratio that means nothing. What
@@ -52,6 +62,7 @@ export interface AnimatorAvatar {
}
interface Quat { w: number; x: number; y: number; z: number }
+interface Vec3 { 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;
@@ -93,8 +104,12 @@ export function parseAvatar(raw: unknown): AnimatorAvatar {
throw new Error('Avatar "scale" must be a positive number');
}
const rest = obj['rest'] === undefined ? undefined : readRest(obj['rest']);
+ const space = obj['space'] === undefined ? undefined : readRest(obj['space']);
+ const restPosition = obj['restPosition'] === undefined ? undefined : readPositions(obj['restPosition']);
const avatar: AnimatorAvatar = { joints: out };
if (rest) avatar.rest = rest;
+ if (space) avatar.space = space;
+ if (restPosition) avatar.restPosition = restPosition;
if (scale !== undefined) avatar.scale = scale as number;
return avatar;
}
@@ -130,6 +145,22 @@ function readRest(raw: unknown): Record<string, Quat> {
return out;
}
+/** Rest positions, one per joint; a joint listed without all three is refused. */
+function readPositions(raw: unknown): Record<string, Vec3> {
+ if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+ throw new Error('Avatar "restPosition" must be an object of joint positions');
+ }
+ const out: Record<string, Vec3> = {};
+ for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+ const v = value as Partial<Vec3> | null;
+ if (!v || ['x', 'y', 'z'].some((k) => typeof v[k as 'x'] !== 'number')) {
+ throw new Error(`Avatar rest position for "${name}" must be a vector`);
+ }
+ out[name] = { x: v.x!, y: v.y!, z: v.z! };
+ }
+ return out;
+}
+
/** A blank avatar, which translates nothing and resolves every path as itself. */
export function emptyAvatar(): AnimatorAvatar & { version: number } {
return { version: AVATAR_FORMAT_VERSION, joints: {} };
@@ -148,20 +179,21 @@ export function avatarResolver(
}
/**
- * 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.
+ * Re-state `pose` as this rig would stand it: a clip means a joint's turn off its
+ * rest in rig space, `D = Sₚ·stated·(Sₚ·rest)⁻¹`, which the target stands on its own
+ * rest as `Tₚ⁻¹·D·Tₚ·targetRest` (Sₚ, Tₚ each rig's parent space). A moved joint
+ * moves by the same rig-space displacement, scaled by the rigs' sizes.
*/
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];
+ const rests = source.rest;
+ const targetRests = target.rest;
+ if (!rests || !targetRests) return;
+ const ratio = travelRatio(source, target);
+ for (const [joint, sourceRest] of Object.entries(rests)) {
+ const targetRest = targetRests[joint];
if (!targetRest) continue;
const entity = resolveJoint(root, joint);
if (entity === null) continue;
@@ -169,8 +201,22 @@ export function rebasePose(
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));
+ const sp = source.space?.[joint] ?? IDENTITY;
+ const tp = target.space?.[joint] ?? IDENTITY;
+ const turn = q.mul(q.mul(sp, stated), q.conjugate(q.mul(sp, sourceRest)));
+ const rebased = q.normalize(q.mul(q.mul(q.conjugate(tp), q.mul(turn, tp)), targetRest));
track.data.rotation = { w: rebased.w, x: rebased.x, y: rebased.y, z: rebased.z };
+
+ const from = source.restPosition?.[joint];
+ const onto = target.restPosition?.[joint];
+ const moved = track.touched.has('position') ? track.data.position as Vec3 | undefined : undefined;
+ if (from && onto && moved) {
+ const away = q.rotate(q.conjugate(tp), q.rotate(sp, {
+ x: moved.x - from.x, y: moved.y - from.y, z: moved.z - from.z,
+ }));
+ track.data.position = { x: onto.x + away.x * ratio, y: onto.y + away.y * ratio, z: onto.z + away.z * ratio };
+ }
}
}
+
+const IDENTITY: Quat = { w: 1, x: 0, y: 0, z: 0 };
diff --git a/sdk/src/asset/loaders/AnimatorControllerAssetLoader.ts b/sdk/src/asset/loaders/AnimatorControllerAssetLoader.ts
index 7e6f8755a..64327296b 100644
--- a/sdk/src/asset/loaders/AnimatorControllerAssetLoader.ts
+++ b/sdk/src/asset/loaders/AnimatorControllerAssetLoader.ts
@@ -67,10 +67,10 @@ export class AnimatorControllerAssetLoader implements AssetLoader<AnimatorContro
}
/**
- * Load what the graph's motions play, resolving each ref IN PLACE. Discovery
- * walks components, and a clip named inside a controller is not one; resolving
- * is what makes the driver's lookup hit, since a motion asks for its clip by the
- * name it carries and that has to be the name it was registered under.
+ * Load what the graph's motions play and the avatar its clips were authored on,
+ * resolving each ref IN PLACE: discovery walks components, which a controller's
+ * refs are not, and each is looked up by the name it carries. Without the avatar
+ * no retarget ever runs.
*/
async function acquireMotionAssets(
def: AnimatorControllerDef, path: string, ctx: LoadContext,
@@ -83,6 +83,10 @@ async function acquireMotionAssets(
motion.clip = resolveDocumentRef(path, motion.clip);
wanted.set(motion.clip, type);
}
+ if (def.avatar) {
+ def.avatar = resolveDocumentRef(path, def.avatar);
+ wanted.set(def.avatar, 'avatar');
+ }
// Leases are recorded against the scope loading this controller, which is
// what releases them when the scene that wanted it goes.
await Promise.all([...wanted].map(([ref, type]) => ctx.acquireAsset(type, ref)));
diff --git a/sdk/tests/animator.test.ts b/sdk/tests/animator.test.ts
index f464671b6..b3af54aba 100644
--- a/sdk/tests/animator.test.ts
+++ b/sdk/tests/animator.test.ts
@@ -468,4 +468,24 @@ describe('AnimatorController runtime load-by-path', () => {
const def = era.published as { layers: { states: { motion: { clip: string } }[] }[] };
expect(def.layers[0]!.states[0]!.motion.clip).toBe('assets/upper.estimeline');
});
+
+ it('acquires the avatar its clips were authored on, which no component names', async () => {
+ // Without it the clip side of a retarget is never loaded, and a rig that
+ // names its own avatar plays the clips' raw values: the character-rig
+ // knight lay on its back for as long as it existed.
+ const withAvatar = {
+ version: 2, parameters: [], initialState: 'Hold', avatar: 'hero.esavatar',
+ states: [{ name: 'Hold', transitions: [], motion: { kind: 'timeline', clip: 'idle.estimeline' } }],
+ };
+ const acquired: Array<[string, string]> = [];
+ const ctx = {
+ catalog: { getBuildPath: (p: string) => p },
+ loadText: async () => JSON.stringify(withAvatar),
+ acquireAsset: async (type: string, ref: string) => { acquired.push([type, ref]); },
+ } as unknown as LoadContext;
+
+ const era = await new AnimatorControllerAssetLoader().registry.prepare('assets/models/loco.esanimator', ctx);
+ expect(acquired).toContainEqual(['avatar', 'assets/models/hero.esavatar']);
+ expect((era.published as { avatar: string }).avatar).toBe('assets/models/hero.esavatar');
+ });
});
diff --git a/sdk/tests/animatorAvatar.test.ts b/sdk/tests/animatorAvatar.test.ts
index 36cbf7f4d..9545ac810 100644
--- a/sdk/tests/animatorAvatar.test.ts
+++ b/sdk/tests/animatorAvatar.test.ts
@@ -320,6 +320,79 @@ describe('one clip over rigs bound differently', () => {
expect(turnedZ(world, 2)).toBeCloseTo(Math.SQRT1_2, 4);
});
+ /**
+ * Rigs on different axes, as the character-rig hero (Z-up under a root turned
+ * −90° about X) and knight (Y-up): turning the source's hips 30° about the
+ * vertical and lifting them 0.1 has to do both about the target's vertical.
+ */
+ it('carries a turn and a lift through each rig’s own space', () => {
+ const axis = (x: number, y: number, z: number, deg: number) => {
+ const h = (deg * Math.PI) / 360, s = Math.sin(h);
+ return { w: Math.cos(h), x: x * s, y: y * s, z: z * s };
+ };
+ const mul = (a: any, b: any) => ({
+ w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
+ x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+ y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+ z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
+ });
+ const inv = (a: any) => ({ w: a.w, x: -a.x, y: -a.y, z: -a.z });
+ const upright = axis(1, 0, 0, -90);
+ const heroHips = axis(1, 0, 0, 104);
+ const vertical30 = axis(0, 1, 0, 30);
+ // What the clip must say for the source's hips to end up turned about the
+ // rig's vertical: its local value, through its parent's space.
+ const stated = mul(mul(inv(upright), vertical30), mul(upright, heroHips));
+
+ const world = makeWorld();
+ rig(world, 1, 2, 'Hips');
+ const key = (value: number) => ([{ time: 0, value, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear }]);
+ const timeline = new TimelineAPI();
+ timeline.registerAsset('wave.estimeline', {
+ version: '1.2', type: 'timeline', duration: 10, wrapMode: WrapMode.Loop,
+ tracks: [{
+ type: TrackType.Property, component: 'Transform', childPath: 'Hips', name: 't',
+ channels: [
+ ...(['w', 'x', 'y', 'z'] as const).map((c) => ({ property: `rotation.${c}`, keyframes: key(stated[c]) })),
+ { property: 'position.x', keyframes: key(0) },
+ { property: 'position.y', keyframes: key(0.05) },
+ // Z is the source's up: its hips rest 0.9 high and the clip lifts them 0.1.
+ { property: 'position.z', keyframes: key(1.0) },
+ ],
+ }],
+ } as TimelineAsset);
+ const avatars: Record<string, AnimatorAvatar> = {
+ 'assets/clips.esavatar': parseAvatar({
+ joints: {}, rest: { Hips: heroHips }, space: { Hips: upright },
+ restPosition: { Hips: { x: 0, y: 0.05, z: 0.9 } }, scale: 2,
+ }),
+ 'assets/rig.esavatar': parseAvatar({
+ joints: {}, rest: { Hips: identityQ }, space: { Hips: identityQ },
+ restPosition: { Hips: { x: 0, y: 0.4, z: 0 } }, scale: 1,
+ }),
+ };
+ 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);
+
+ const t = world.get(2, Transform) as { rotation: any; position: any };
+ const sign = Math.sign(t.rotation.w) || 1;
+ expect(t.rotation.w * sign).toBeCloseTo(vertical30.w, 4);
+ expect(t.rotation.y * sign).toBeCloseTo(vertical30.y, 4);
+ expect(t.rotation.x).toBeCloseTo(0, 4);
+ expect(t.rotation.z).toBeCloseTo(0, 4);
+ // Lifted along ITS up, by half as much: it is half the source's size.
+ expect(t.position.x).toBeCloseTo(0, 4);
+ expect(t.position.y).toBeCloseTo(0.4 + 0.05, 4);
+ expect(t.position.z).toBeCloseTo(0, 4);
+ });
+
it('refuses a rest pose that is not a rotation', () => {
expect(() => parseAvatar({ joints: {}, rest: { Arm: { w: 1, x: 0, y: 0 } } }))
.toThrow(/quaternion/);
diff --git a/tools/make-rig-corpus.mjs b/tools/make-rig-corpus.mjs
index d33dc156b..64e551006 100644
--- a/tools/make-rig-corpus.mjs
+++ b/tools/make-rig-corpus.mjs
@@ -29,6 +29,8 @@
* corners need. Run it again to re-cut; the sources are not in the repo.
*
* node tools/make-rig-corpus.mjs --src <dir with the downloaded packs>
+ * node tools/make-rig-corpus.mjs --avatars-only (re-measure the avatars off the
+ * prefabs already in the corpus)
*/
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
@@ -451,8 +453,9 @@ function subset(json, bins, { dropNode, dropPrimitive = () => false, keepAnimati
}
const args = process.argv.slice(2);
+const avatarsOnly = args.includes('--avatars-only');
const srcDir = args[args.indexOf('--src') + 1];
-if (!srcDir || srcDir.startsWith('--')) {
+if (!avatarsOnly && (!srcDir || srcDir.startsWith('--'))) {
console.error('usage: node tools/make-rig-corpus.mjs --src <dir>\n\n'
+ 'The dir holds the two CC0 packs named in this file\'s header:\n'
+ ' AnimationLibrary_Godot_Standard.gltf + .bin (Quaternius, hero)\n'
@@ -460,6 +463,9 @@ if (!srcDir || srcDir.startsWith('--')) {
process.exit(2);
}
+if (!avatarsOnly) cutAndImport();
+
+function cutAndImport() {
mkdirSync(OUT, { recursive: true });
const hero = readSource(srcDir, 'AnimationLibrary_Godot_Standard.gltf');
@@ -499,6 +505,7 @@ for (const stem of ['hero', 'knight']) {
'--project', path.dirname(path.dirname(OUT)),
], { stdio: 'inherit' });
}
+}
// =============================================================================
// The avatars, once `estella import-model` has written the prefabs
@@ -570,7 +577,7 @@ function readRig(prefabFile) {
return { x: origin.x + turned.x, y: origin.y + turned.y, z: origin.z + turned.z };
})();
const path = prefix === null ? '' : (prefix ? `${prefix}/${e.name}` : e.name);
- if (prefix !== null) joints.set(e.name, { path, rest: local.r, at });
+ if (prefix !== null) joints.set(e.name, { path, rest: local.r, at, space: rotation, position: local.p });
const spin = prefix === null ? IDENTITY : quatMul(rotation, local.r);
for (const child of e.children) walk(child, path, at, spin);
};
@@ -596,29 +603,39 @@ function rigSize(joints) {
return far;
}
-function writeAvatar(file, { joints, rest, scale }) {
- writeFileSync(file, `${JSON.stringify({ version: 1, joints, rest, scale }, null, 2)}\n`);
+function writeAvatar(file, { joints, rest, space, restPosition, scale }) {
+ writeFileSync(file, `${JSON.stringify({ version: 1, joints, rest, space, restPosition, scale }, null, 2)}\n`);
}
const heroRig = readRig(path.join(OUT, 'hero.esprefab'));
const knightRig = readRig(path.join(OUT, 'knight.esprefab'));
if (heroRig.size > 1 && knightRig.size > 1) {
const heroRest = {};
+ const heroSpace = {};
+ const heroPosition = {};
const knightJoints = {};
const knightRest = {};
+ const knightSpace = {};
+ const knightPosition = {};
for (const [heroName, knightName] of Object.entries(JOINT_NAMES)) {
const mine = heroRig.get(heroName);
const theirs = knightRig.get(knightName);
if (!mine) throw new Error(`hero rig has no joint named ${heroName}`);
if (!theirs) throw new Error(`knight rig has no joint named ${knightName}`);
heroRest[mine.path] = mine.rest;
+ heroSpace[mine.path] = mine.space;
+ heroPosition[mine.path] = mine.position;
knightJoints[mine.path] = theirs.path;
knightRest[mine.path] = theirs.rest;
+ // The two skeletons stand on different axes (the hero Z-up under a turned
+ // root, the knight Y-up), so a joint's parent space is part of its rest.
+ knightSpace[mine.path] = theirs.space;
+ knightPosition[mine.path] = theirs.position;
}
writeAvatar(path.join(OUT, 'hero.esavatar'),
- { joints: {}, rest: heroRest, scale: rigSize(heroRig) });
+ { joints: {}, rest: heroRest, space: heroSpace, restPosition: heroPosition, scale: rigSize(heroRig) });
writeAvatar(path.join(OUT, 'knight.esavatar'),
- { joints: knightJoints, rest: knightRest, scale: rigSize(knightRig) });
+ { joints: knightJoints, rest: knightRest, space: knightSpace, restPosition: knightPosition, scale: rigSize(knightRig) });
console.log(`avatars ${Object.keys(JOINT_NAMES).length} joints mapped, `
+ `hero ${rigSize(heroRig).toFixed(2)} tall vs knight ${rigSize(knightRig).toFixed(2)}`);
} else {