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
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.esavatarindex 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.esavatarindex 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.mdindex 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> | undefinedscale: 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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> | undefinedscale: 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 @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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> | undefinedscale: 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 @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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> | undefinedscale: 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 @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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> | undefinedscale: 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 @experimentaldiff --git a/sdk/src/animation/animatorAvatar.ts b/sdk/src/animation/animatorAvatar.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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 {