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): one clip drives rigs that do not share its bone names

esengine793157a0aee1
diff --git a/desktop b/desktop
index ced6c9cb9..5b6070623 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit ced6c9cb96a3853cd26b6a4065669240d98870fc
+Subproject commit 5b6070623a4dd0993b1914f2ebc8ff42d142a586
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 0db91b948..19b1037ef 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 114,
"beta": 101,
- "experimental": 1873,
+ "experimental": 1879,
"deprecated": 3
},
- "total": 2088,
+ "total": 2094,
"subsystems": [
{
"id": "ecs",
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index b5fa37ef3..15ebb3cc3 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -11,6 +11,11 @@
"type": "Asset<animatorcontroller>",
"default": "none"
},
+ {
+ "key": "avatar",
+ "type": "Asset<avatar>",
+ "default": "none"
+ },
{
"key": "currentState",
"type": "string",
diff --git a/pipeline/src/assets/assetDb.ts b/pipeline/src/assets/assetDb.ts
index 71a09f85b..dd19711fb 100644
--- a/pipeline/src/assets/assetDb.ts
+++ b/pipeline/src/assets/assetDb.ts
@@ -232,7 +232,7 @@ const BITMAP_FONT = 'bitmapfont';
// inside a document, so an unscanned type 404s what the document needs.
const JSON_REF_TYPES = new Set([
'scene', 'prefab', 'material', 'tileset', 'tilemap', 'animclip', 'animation', 'statemachine', 'behaviortree',
- 'environment', 'animatorcontroller',
+ 'environment', 'animatorcontroller', 'avatar',
'json',
]);
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 2dc9dc34f..4b45a1188 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1712 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1718 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -33,6 +33,11 @@ readonly ["local", "subpackage", "remote"]
"KeyJ"
```
+## AVATAR_FORMAT_VERSION — const @experimental
+```
+1
+```
+
## AchievementProvider — interface @experimental
```
getStat: (name: string) => number
@@ -402,6 +407,11 @@ static prototype: AnimationPlugin
ComponentDef<AnimatorData>
```
+## AnimatorAvatar — interface @experimental
+```
+joints: Record<string, string>
+```
+
## AnimatorBlend1D — interface @experimental
```
parameter: string
@@ -480,6 +490,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => void
setTrigger: (entity: Entity, name: string) => void
unregisterController: (name: string) => void
update: (world: World, dt?: number, events?: AnimatorEventSink) => void
+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => void
static new (): AnimatorControllerAPI
static prototype: AnimatorControllerAPI
```
@@ -497,6 +508,7 @@ version: number | undefined
## AnimatorData — interface @beta
```
+avatar: string
controller: string
currentState: string
enabled: boolean
@@ -807,7 +819,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'avatar' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -4371,6 +4383,11 @@ enabled: boolean
type: string
```
+## JointResolver — type @experimental
+```
+(root: Entity, path: string) => Entity | null
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -4895,7 +4912,7 @@ Stencil = 1
## MaskReach — class @experimental
```
admits: (track: PoseTrack) => boolean
-resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask) => void
+resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask, resolveJoint: JointResolver) => void
static new (): MaskReach
static prototype: MaskReach
```
@@ -5222,6 +5239,7 @@ params: Readonly<Record<string, number | boolean>>
releaseDelta: (delta: RootMotionDelta) => void
releaseMix: (mix: WeightedPose[]) => void
releasePose: (pose: Pose) => void
+resolveJoint: JointResolver
rootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => boolean
sample: (motion: AnimatorMotion, time: number, pose: Pose) => boolean
world: World
@@ -5247,7 +5265,7 @@ value: number
## MotionRegistry — class @experimental
```
-context: (world: World, entity: Entity, params: MotionParams) => MotionContext
+context: (world: World, entity: Entity, params: MotionParams, resolveJoint?: JointResolver) => MotionContext
driverFor: (motion: AnimatorMotion) => MotionDriver | undefined
has: (kind: string) => boolean
register: <M extends AnimatorMotion>(kind: M["kind"], driver: MotionDriver<M>) => void
@@ -10915,6 +10933,11 @@ AudioPlugin
() => Dimension
```
+## avatarResolver — function @experimental
+```
+(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
@@ -11690,6 +11713,11 @@ DragPlugin
(): AnimatorControllerDef
```
+## emptyAvatar — function @experimental
+```
+(): AnimatorAvatar & { version: number; }
+```
+
## emptyBt — function @experimental
```
(): BtDefinition
@@ -12715,6 +12743,11 @@ NavPlugin
(raw: unknown): AudioProjectConfig
```
+## parseAvatar — function @experimental
+```
+(raw: unknown): AnimatorAvatar
+```
+
## parseBusEffects — function @experimental
```
(raw: unknown): BusEffectDef[]
@@ -13682,7 +13715,7 @@ ServicesPlugin
## solveAnimatorIK — function @experimental
```
-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams): void
+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void
```
## spatialDistance — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index b90e6f1a0..ff357a01e 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 99 beta · 1731 experimental · 3 deprecated
+Symbols: 114 public · 99 beta · 1737 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -33,6 +33,11 @@ readonly ["local", "subpackage", "remote"]
"KeyJ"
```
+## AVATAR_FORMAT_VERSION — const @experimental
+```
+1
+```
+
## AchievementProvider — interface @experimental
```
getStat: (name: string) => number
@@ -402,6 +407,11 @@ static prototype: AnimationPlugin
ComponentDef<AnimatorData>
```
+## AnimatorAvatar — interface @experimental
+```
+joints: Record<string, string>
+```
+
## AnimatorBlend1D — interface @experimental
```
parameter: string
@@ -480,6 +490,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => void
setTrigger: (entity: Entity, name: string) => void
unregisterController: (name: string) => void
update: (world: World, dt?: number, events?: AnimatorEventSink) => void
+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => void
static new (): AnimatorControllerAPI
static prototype: AnimatorControllerAPI
```
@@ -497,6 +508,7 @@ version: number | undefined
## AnimatorData — interface @beta
```
+avatar: string
controller: string
currentState: string
enabled: boolean
@@ -807,7 +819,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'avatar' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -4379,6 +4391,11 @@ enabled: boolean
type: string
```
+## JointResolver — type @experimental
+```
+(root: Entity, path: string) => Entity | null
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -4903,7 +4920,7 @@ Stencil = 1
## MaskReach — class @experimental
```
admits: (track: PoseTrack) => boolean
-resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask) => void
+resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask, resolveJoint: JointResolver) => void
static new (): MaskReach
static prototype: MaskReach
```
@@ -5235,6 +5252,7 @@ params: Readonly<Record<string, number | boolean>>
releaseDelta: (delta: RootMotionDelta) => void
releaseMix: (mix: WeightedPose[]) => void
releasePose: (pose: Pose) => void
+resolveJoint: JointResolver
rootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => boolean
sample: (motion: AnimatorMotion, time: number, pose: Pose) => boolean
world: World
@@ -5260,7 +5278,7 @@ value: number
## MotionRegistry — class @experimental
```
-context: (world: World, entity: Entity, params: MotionParams) => MotionContext
+context: (world: World, entity: Entity, params: MotionParams, resolveJoint?: JointResolver) => MotionContext
driverFor: (motion: AnimatorMotion) => MotionDriver | undefined
has: (kind: string) => boolean
register: <M extends AnimatorMotion>(kind: M["kind"], driver: MotionDriver<M>) => void
@@ -11123,6 +11141,11 @@ AudioPlugin
() => Dimension
```
+## avatarResolver — function @experimental
+```
+(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
@@ -11923,6 +11946,11 @@ DragPlugin
(): AnimatorControllerDef
```
+## emptyAvatar — function @experimental
+```
+(): AnimatorAvatar & { version: number; }
+```
+
## emptyBt — function @experimental
```
(): BtDefinition
@@ -12958,6 +12986,11 @@ NavPlugin
(raw: unknown): AudioProjectConfig
```
+## parseAvatar — function @experimental
+```
+(raw: unknown): AnimatorAvatar
+```
+
## parseBusEffects — function @experimental
```
(raw: unknown): BusEffectDef[]
@@ -13925,7 +13958,7 @@ ServicesPlugin
## solveAnimatorIK — function @experimental
```
-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams): void
+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void
```
## spatialDistance — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index aa01a50cb..0e1c1330e 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 96 beta · 1711 experimental · 3 deprecated
+Symbols: 114 public · 96 beta · 1717 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -28,6 +28,11 @@ readonly ["local", "subpackage", "remote"]
"KeyJ"
```
+## AVATAR_FORMAT_VERSION — const @experimental
+```
+1
+```
+
## AchievementProvider — interface @experimental
```
getStat: (name: string) => number
@@ -397,6 +402,11 @@ static prototype: AnimationPlugin
ComponentDef<AnimatorData>
```
+## AnimatorAvatar — interface @experimental
+```
+joints: Record<string, string>
+```
+
## AnimatorBlend1D — interface @experimental
```
parameter: string
@@ -475,6 +485,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => void
setTrigger: (entity: Entity, name: string) => void
unregisterController: (name: string) => void
update: (world: World, dt?: number, events?: AnimatorEventSink) => void
+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => void
static new (): AnimatorControllerAPI
static prototype: AnimatorControllerAPI
```
@@ -492,6 +503,7 @@ version: number | undefined
## AnimatorData — interface @beta
```
+avatar: string
controller: string
currentState: string
enabled: boolean
@@ -802,7 +814,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'avatar' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -4366,6 +4378,11 @@ enabled: boolean
type: string
```
+## JointResolver — type @experimental
+```
+(root: Entity, path: string) => Entity | null
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -4890,7 +4907,7 @@ Stencil = 1
## MaskReach — class @experimental
```
admits: (track: PoseTrack) => boolean
-resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask) => void
+resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask, resolveJoint: JointResolver) => void
static new (): MaskReach
static prototype: MaskReach
```
@@ -5217,6 +5234,7 @@ params: Readonly<Record<string, number | boolean>>
releaseDelta: (delta: RootMotionDelta) => void
releaseMix: (mix: WeightedPose[]) => void
releasePose: (pose: Pose) => void
+resolveJoint: JointResolver
rootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => boolean
sample: (motion: AnimatorMotion, time: number, pose: Pose) => boolean
world: World
@@ -5242,7 +5260,7 @@ value: number
## MotionRegistry — class @experimental
```
-context: (world: World, entity: Entity, params: MotionParams) => MotionContext
+context: (world: World, entity: Entity, params: MotionParams, resolveJoint?: JointResolver) => MotionContext
driverFor: (motion: AnimatorMotion) => MotionDriver | undefined
has: (kind: string) => boolean
register: <M extends AnimatorMotion>(kind: M["kind"], driver: MotionDriver<M>) => void
@@ -10910,6 +10928,11 @@ AudioPlugin
() => Dimension
```
+## avatarResolver — function @experimental
+```
+(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
@@ -11685,6 +11708,11 @@ DragPlugin
(): AnimatorControllerDef
```
+## emptyAvatar — function @experimental
+```
+(): AnimatorAvatar & { version: number; }
+```
+
## emptyBt — function @experimental
```
(): BtDefinition
@@ -12720,6 +12748,11 @@ NodePlatformAdapter
(raw: unknown): AudioProjectConfig
```
+## parseAvatar — function @experimental
+```
+(raw: unknown): AnimatorAvatar
+```
+
## parseBusEffects — function @experimental
```
(raw: unknown): BusEffectDef[]
@@ -13687,7 +13720,7 @@ ServicesPlugin
## solveAnimatorIK — function @experimental
```
-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams): void
+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void
```
## spatialDistance — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 57f54069c..f310d3ad3 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1733 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1739 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -28,6 +28,11 @@ readonly ["local", "subpackage", "remote"]
"KeyJ"
```
+## AVATAR_FORMAT_VERSION — const @experimental
+```
+1
+```
+
## AchievementProvider — interface @experimental
```
getStat: (name: string) => number
@@ -397,6 +402,11 @@ static prototype: AnimationPlugin
ComponentDef<AnimatorData>
```
+## AnimatorAvatar — interface @experimental
+```
+joints: Record<string, string>
+```
+
## AnimatorBlend1D — interface @experimental
```
parameter: string
@@ -475,6 +485,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => void
setTrigger: (entity: Entity, name: string) => void
unregisterController: (name: string) => void
update: (world: World, dt?: number, events?: AnimatorEventSink) => void
+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => void
static new (): AnimatorControllerAPI
static prototype: AnimatorControllerAPI
```
@@ -492,6 +503,7 @@ version: number | undefined
## AnimatorData — interface @beta
```
+avatar: string
controller: string
currentState: string
enabled: boolean
@@ -802,7 +814,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'avatar' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -4366,6 +4378,11 @@ enabled: boolean
type: string
```
+## JointResolver — type @experimental
+```
+(root: Entity, path: string) => Entity | null
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -4890,7 +4907,7 @@ Stencil = 1
## MaskReach — class @experimental
```
admits: (track: PoseTrack) => boolean
-resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask) => void
+resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask, resolveJoint: JointResolver) => void
static new (): MaskReach
static prototype: MaskReach
```
@@ -5465,6 +5482,7 @@ params: Readonly<Record<string, number | boolean>>
releaseDelta: (delta: RootMotionDelta) => void
releaseMix: (mix: WeightedPose[]) => void
releasePose: (pose: Pose) => void
+resolveJoint: JointResolver
rootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => boolean
sample: (motion: AnimatorMotion, time: number, pose: Pose) => boolean
world: World
@@ -5490,7 +5508,7 @@ value: number
## MotionRegistry — class @experimental
```
-context: (world: World, entity: Entity, params: MotionParams) => MotionContext
+context: (world: World, entity: Entity, params: MotionParams, resolveJoint?: JointResolver) => MotionContext
driverFor: (motion: AnimatorMotion) => MotionDriver | undefined
has: (kind: string) => boolean
register: <M extends AnimatorMotion>(kind: M["kind"], driver: MotionDriver<M>) => void
@@ -11164,6 +11182,11 @@ AudioPlugin
() => Dimension
```
+## avatarResolver — function @experimental
+```
+(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
@@ -11944,6 +11967,11 @@ DragPlugin
(): AnimatorControllerDef
```
+## emptyAvatar — function @experimental
+```
+(): AnimatorAvatar & { version: number; }
+```
+
## emptyBt — function @experimental
```
(): BtDefinition
@@ -12979,6 +13007,11 @@ NavPlugin
(raw: unknown): AudioProjectConfig
```
+## parseAvatar — function @experimental
+```
+(raw: unknown): AnimatorAvatar
+```
+
## parseBusEffects — function @experimental
```
(raw: unknown): BusEffectDef[]
@@ -13946,7 +13979,7 @@ ServicesPlugin
## solveAnimatorIK — function @experimental
```
-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams): void
+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void
```
## spatialDistance — function @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 8e4909365..83aa4e15c 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1723 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1729 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -28,6 +28,11 @@ readonly ["local", "subpackage", "remote"]
"KeyJ"
```
+## AVATAR_FORMAT_VERSION — const @experimental
+```
+1
+```
+
## AchievementProvider — interface @experimental
```
getStat: (name: string) => number
@@ -397,6 +402,11 @@ static prototype: AnimationPlugin
ComponentDef<AnimatorData>
```
+## AnimatorAvatar — interface @experimental
+```
+joints: Record<string, string>
+```
+
## AnimatorBlend1D — interface @experimental
```
parameter: string
@@ -475,6 +485,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => void
setTrigger: (entity: Entity, name: string) => void
unregisterController: (name: string) => void
update: (world: World, dt?: number, events?: AnimatorEventSink) => void
+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => void
static new (): AnimatorControllerAPI
static prototype: AnimatorControllerAPI
```
@@ -492,6 +503,7 @@ version: number | undefined
## AnimatorData — interface @beta
```
+avatar: string
controller: string
currentState: string
enabled: boolean
@@ -802,7 +814,7 @@ type: AssetFieldType
## AssetFieldType — type @public
```
-'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment'
+'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'avatar' | 'mesh' | 'environment'
```
## AssetGroupDef — interface @experimental
@@ -4373,6 +4385,11 @@ enabled: boolean
type: string
```
+## JointResolver — type @experimental
+```
+(root: Entity, path: string) => Entity | null
+```
+
## JsonResult — interface @experimental
```
data: T
@@ -4897,7 +4914,7 @@ Stencil = 1
## MaskReach — class @experimental
```
admits: (track: PoseTrack) => boolean
-resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask) => void
+resolve: (world: Pick<World, "tryGet">, root: Entity, mask: AnimatorMask, resolveJoint: JointResolver) => void
static new (): MaskReach
static prototype: MaskReach
```
@@ -5224,6 +5241,7 @@ params: Readonly<Record<string, number | boolean>>
releaseDelta: (delta: RootMotionDelta) => void
releaseMix: (mix: WeightedPose[]) => void
releasePose: (pose: Pose) => void
+resolveJoint: JointResolver
rootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => boolean
sample: (motion: AnimatorMotion, time: number, pose: Pose) => boolean
world: World
@@ -5249,7 +5267,7 @@ value: number
## MotionRegistry — class @experimental
```
-context: (world: World, entity: Entity, params: MotionParams) => MotionContext
+context: (world: World, entity: Entity, params: MotionParams, resolveJoint?: JointResolver) => MotionContext
driverFor: (motion: AnimatorMotion) => MotionDriver | undefined
has: (kind: string) => boolean
register: <M extends AnimatorMotion>(kind: M["kind"], driver: MotionDriver<M>) => void
@@ -10938,6 +10956,11 @@ AudioPlugin
() => Dimension
```
+## avatarResolver — function @experimental
+```
+(world: Pick<World, "tryGet">, avatar: AnimatorAvatar | null): JointResolver
+```
+
## bind — function @experimental
```
<C extends object, K extends keyof C>(world: World, entity: Entity, component: ComponentDef<C>, field: K, source: ReadonlySignal<C[K]>): () => void
@@ -11713,6 +11736,11 @@ DragPlugin
(): AnimatorControllerDef
```
+## emptyAvatar — function @experimental
+```
+(): AnimatorAvatar & { version: number; }
+```
+
## emptyBt — function @experimental
```
(): BtDefinition
@@ -12743,6 +12771,11 @@ NavPlugin
(raw: unknown): AudioProjectConfig
```
+## parseAvatar — function @experimental
+```
+(raw: unknown): AnimatorAvatar
+```
+
## parseBusEffects — function @experimental
```
(raw: unknown): BusEffectDef[]
@@ -13710,7 +13743,7 @@ ServicesPlugin
## solveAnimatorIK — function @experimental
```
-(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams): void
+(world: World, rigRoot: Entity, pose: Pose, constraints: readonly AnimatorIK[], params: MotionParams, resolveJoint?: JointResolver): void
```
## spatialDistance — function @experimental
diff --git a/sdk/src/animation/AnimationPlugin.ts b/sdk/src/animation/AnimationPlugin.ts
index 54a10fdf3..5381c89ea 100644
--- a/sdk/src/animation/AnimationPlugin.ts
+++ b/sdk/src/animation/AnimationPlugin.ts
@@ -19,6 +19,7 @@ import type { AnimCore } from './Tween';
import { Tween, TweenAPI } from './Tween';
import { SpriteAnimation, SpriteAnimationAPI, type SpriteAnimClip } from './SpriteAnimator';
import { AnimatorController, AnimatorControllerAPI, type AnimatorControllerDef } from './Animator';
+import type { AnimatorAvatar } from './animatorAvatar';
import { appRegistryAsset } from '../asset/registryLookup';
import { playModeOnly } from '../ecs/env';
import { SystemLabel } from '../ecs/systemLabels';
@@ -62,6 +63,7 @@ export class AnimationPlugin implements Plugin {
// answer to the authored ref as well as the resolved path. A code
// registration still wins over one.
anim.useAssetClips((ref) => appRegistryAsset<SpriteAnimClip>(app, 'anim-clip', ref));
+ animator.useAssetAvatars((ref) => appRegistryAsset<AnimatorAvatar>(app, 'avatar', ref));
animator.useAssetControllers(
(ref) => appRegistryAsset<AnimatorControllerDef>(app, 'animatorcontroller', ref),
);
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.ts
index b87e790b5..bd0dfd710 100644
--- a/sdk/src/animation/Animator.ts
+++ b/sdk/src/animation/Animator.ts
@@ -32,6 +32,7 @@ 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 { solveAnimatorIK, type AnimatorIK } from './animatorIK';
import { AnimatorRootMotion, type AnimatorRootMotionData } from './animatorRootMotion';
import type { AnimatorEventSink } from './animatorEvent';
@@ -516,6 +517,9 @@ export interface AnimatorData {
controller: string;
/** The base layer's active state; empty until the first update seeds it. */
currentState: string;
+ /** A `.esavatar` saying how THIS rig spells the joints the clips name. Empty
+ * where the clips were authored against this rig and need no translation. */
+ avatar: string;
/** The active state of each layer ABOVE the base one, by that layer's index
* minus one — the base layer's is {@link currentState}, for the same reason
* the base layer has no weight. */
@@ -532,20 +536,30 @@ export interface AnimatorData {
*/
export const Animator: ComponentDef<AnimatorData> = defineComponent('Animator', {
controller: '',
+ avatar: '',
currentState: '',
layerStates: [] as string[],
enabled: true,
}, {
- assetFields: [{ field: 'controller', type: 'animatorcontroller' }],
+ assetFields: [
+ { field: 'controller', type: 'animatorcontroller' },
+ { field: 'avatar', type: 'avatar' },
+ ],
// Preload a `.esanimator` path (or an editor-serialized uuid ref) with the
// scene so the controller is registered before the first tick. A plain
// `registerController` name (code path) is left alone — this callback is the
// discovery authority; the assetField above only drives the editor picker.
discoverAssets: data => {
+ const found: { type: string; path: string }[] = [];
const c = data.controller;
- return typeof c === 'string' && (c.endsWith('.esanimator') || isUuidRef(c))
- ? [{ type: 'animatorcontroller', path: c }]
- : [];
+ if (typeof c === 'string' && (c.endsWith('.esanimator') || isUuidRef(c))) {
+ found.push({ type: 'animatorcontroller', path: c });
+ }
+ const a = data.avatar;
+ if (typeof a === 'string' && (a.endsWith('.esavatar') || isUuidRef(a))) {
+ found.push({ type: 'avatar', path: a });
+ }
+ return found;
},
});
@@ -584,6 +598,7 @@ export function clearAnimatorControllerStore(): void {
*/
export class AnimatorControllerAPI {
private assetControllers_: ((ref: string) => AnimatorControllerDef | undefined) | null = null;
+ private assetAvatars_: ((ref: string) => AnimatorAvatar | undefined) | null = null;
private readonly controllers = new Map<string, AnimatorControllerDef>();
private readonly params = new Map<Entity, Map<string, number | boolean>>();
private readonly triggers = new Map<Entity, Set<string>>();
@@ -653,6 +668,19 @@ export class AnimatorControllerAPI {
this.assetControllers_ = source;
}
+ /** Where a `.esavatar` comes from. Same shape as the controller source, and
+ * optional for the same reason: without one, every path resolves as itself. */
+ useAssetAvatars(source: (ref: string) => AnimatorAvatar | undefined): void {
+ 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);
+ }
+
getController(name: string): AnimatorControllerDef | undefined {
// A code-registered name wins, then this realm's asset, then a
// controller registered by path through the module door.
@@ -729,7 +757,8 @@ export class AnimatorControllerAPI {
const count = animatorLayerCount(def);
const params = resolveParams(def, this.params.get(entity) ?? EMPTY_PARAMS);
- const ctx = this.motions_.context(world, entity, params);
+ const joints = this.jointsOf(world, a);
+ const ctx = this.motions_.context(world, entity, params, joints);
const rt = this.runtimeFor(entity, count);
rt.composed.reset();
@@ -747,7 +776,7 @@ export class AnimatorControllerAPI {
// between composing and writing — on the pose this frame stated,
// never on the world's record of the last one.
if (wrote && def.ik?.length) {
- solveAnimatorIK(world, entity, rt.composed, def.ik, params);
+ solveAnimatorIK(world, entity, rt.composed, def.ik, params, joints);
}
// One write for the whole stack: a layer states values, and what the
// entity ends up as is the stack's answer, not the topmost writer's.
@@ -852,7 +881,7 @@ export class AnimatorControllerAPI {
}
const layer = def.layers![index - 1]!;
const weight = layer.weight ?? 1;
- const reach = this.reachFor(world, ctx.entity, rt.layers[index]!, layer.mask);
+ const reach = this.reachFor(world, ctx.entity, rt.layers[index]!, layer.mask, ctx.resolveJoint);
if (layer.blend !== 'additive') {
overlayPose(rt.composed, pose, weight, world, reach);
return;
@@ -961,10 +990,11 @@ export class AnimatorControllerAPI {
/** This layer's mask against this rig, or null where it writes all of it. */
private reachFor(
world: World, entity: Entity, rt: LayerRuntime, mask: AnimatorMask | undefined,
+ resolveJoint: JointResolver,
): MaskReach | null {
if (!mask) return null;
const reach = rt.reach ?? (rt.reach = new MaskReach());
- reach.resolve(world, entity, mask);
+ reach.resolve(world, entity, mask, resolveJoint);
return reach;
}
diff --git a/sdk/src/animation/animatorAvatar.ts b/sdk/src/animation/animatorAvatar.ts
new file mode 100644
index 000000000..fcbb3586d
--- /dev/null
+++ b/sdk/src/animation/animatorAvatar.ts
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file animatorAvatar.ts
+ * @brief How one rig spells the joints another rig's clips name.
+ *
+ * @details A clip addresses what it animates by `childPath`, which is the name
+ * whoever exported the model chose. Two characters rigged by two people
+ * therefore share no clip at all, and the corpus shows the cost: an
+ * enemy has to be rigged with the names its clips already use.
+ *
+ * An avatar is the translation, and it is a property of the RIG, not of
+ * the controller: one controller drives many characters, and what each
+ * of them calls its left hand is each of their own business.
+ *
+ * It applies at the one place a path becomes an entity. There is no
+ * retarget stage and no rewritten clip — a clip is data several rigs can
+ * read at once, and rewriting it on load would make one copy per rig and
+ * a question about which copy a change reached.
+ */
+
+import type { Entity } from '../types';
+import type { World } from '../ecs/world';
+import { resolveChildEntity } from '../ecs/childPath';
+
+/** A rig's own spelling for each joint a clip may name. */
+export interface AnimatorAvatar {
+ /**
+ * The name a clip uses → the `childPath` this rig reaches that joint by. A
+ * name with no entry resolves as itself, so a clip authored against this rig
+ * keeps working and an avatar can translate only what differs.
+ */
+ joints: Record<string, string>;
+}
+
+/** Finding a joint on a rig, whichever way a clip spelled it. */
+export type JointResolver = (root: Entity, path: string) => Entity | null;
+
+/** What a `.esavatar` this build writes claims. */
+export const AVATAR_FORMAT_VERSION = 1;
+
+/**
+ * Read a parsed `.esavatar`. Throws for a shape that is not one and for a
+ * version this build does not know — the same upward guard a controller has, for
+ * the same reason: a translation half-read animates the wrong joints in silence.
+ */
+export function parseAvatar(raw: unknown): AnimatorAvatar {
+ if (typeof raw !== 'object' || raw === null) throw new Error('Avatar data must be an object');
+ const obj = raw as Record<string, unknown>;
+ const version = obj['version'];
+ if (version !== undefined && (typeof version !== 'number' || !Number.isInteger(version))) {
+ throw new Error('Avatar "version" must be an integer');
+ }
+ if ((version as number | undefined ?? AVATAR_FORMAT_VERSION) > AVATAR_FORMAT_VERSION) {
+ throw new Error(
+ `Avatar is version ${version}; this build reads up to ${AVATAR_FORMAT_VERSION}.`,
+ );
+ }
+ const joints = obj['joints'];
+ if (typeof joints !== 'object' || joints === null || Array.isArray(joints)) {
+ throw new Error('An avatar needs a "joints" object mapping clip names to childPaths');
+ }
+ const out: Record<string, string> = {};
+ for (const [name, path] of Object.entries(joints as Record<string, unknown>)) {
+ if (typeof path !== 'string') {
+ throw new Error(`Avatar joint "${name}" must map to a childPath string`);
+ }
+ // An entry mapping a name to itself is what having no entry already means.
+ if (path && path !== name) out[name] = path;
+ }
+ return { joints: 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: {} };
+}
+
+/**
+ * The resolver a rig with `avatar` uses. Null for no avatar rather than an
+ * identity one, so the common case reaches {@link resolveChildEntity} with
+ * nothing in between.
+ */
+export function avatarResolver(
+ world: Pick<World, 'tryGet'>, avatar: AnimatorAvatar | null,
+): JointResolver {
+ if (!avatar) return (root, path) => resolveChildEntity(world, root, path);
+ return (root, path) => resolveChildEntity(world, root, avatar.joints[path] ?? path);
+}
diff --git a/sdk/src/animation/animatorIK.ts b/sdk/src/animation/animatorIK.ts
index 806c8d9a9..9b56e72c6 100644
--- a/sdk/src/animation/animatorIK.ts
+++ b/sdk/src/animation/animatorIK.ts
@@ -25,6 +25,7 @@ import type { Entity } from '../types';
import type { World } from '../ecs/world';
import { Parent, Transform, type TransformData } from '../ecs/component';
import { resolveChildEntity } from '../ecs/childPath';
+import type { JointResolver } from './animatorAvatar';
import { q } from '../math/quat';
import { leanQuat } from './quatMix';
import type { Pose } from './pose';
@@ -229,9 +230,10 @@ const scale = (v: Vec3, k: number): Vec3 => ({ x: v.x * k, y: v.y * k, z: v.z *
*/
function solveTwoBone(
world: World, pose: Pose, rigRoot: Entity, ik: AnimatorIK, weight: number,
+ resolveJoint: JointResolver,
): boolean {
- const tip = resolveChildEntity(world, rigRoot, ik.tip);
- const target = resolveChildEntity(world, rigRoot, ik.target);
+ const tip = resolveJoint(rigRoot, ik.tip);
+ const target = resolveJoint(rigRoot, ik.target);
if (tip === null || target === null) return false;
const mid = parentOf(world, tip);
const root = mid === null ? null : parentOf(world, mid);
@@ -255,7 +257,7 @@ function solveTwoBone(
// Which way the elbow leaves the line. A pole names it; without one the limb
// keeps the bend it already has; and a limb that is dead straight has no bend
// to keep, so any direction off the line will do.
- const pole = ik.pole ? resolveChildEntity(world, rigRoot, ik.pole) : null;
+ const pole = ik.pole ? resolveJoint(rigRoot, ik.pole) : null;
const poleAt = pole === null ? null : place(world, pose, rigRoot, pole);
const bendTowards = pickBend(along, [
poleAt ? orthogonal(sub(poleAt.position, pRoot.position), along) : null,
@@ -294,9 +296,10 @@ function pickBend(along: Vec3, candidates: (Vec3 | null)[]): Vec3 {
/** Look-at: the tip turns so its own `axis` points at the target. */
function solveLookAt(
world: World, pose: Pose, rigRoot: Entity, ik: AnimatorIK, weight: number,
+ resolveJoint: JointResolver,
): boolean {
- const tip = resolveChildEntity(world, rigRoot, ik.tip);
- const target = resolveChildEntity(world, rigRoot, ik.target);
+ const tip = resolveJoint(rigRoot, ik.tip);
+ const target = resolveJoint(rigRoot, ik.target);
if (tip === null || target === null) return false;
const pTip = place(world, pose, rigRoot, tip);
const pTarget = place(world, pose, rigRoot, target);
@@ -318,11 +321,12 @@ function solveLookAt(
export function solveAnimatorIK(
world: World, rigRoot: Entity, pose: Pose,
constraints: readonly AnimatorIK[], params: MotionParams,
+ resolveJoint: JointResolver = (root, path) => resolveChildEntity(world, root, path),
): void {
for (const ik of constraints) {
const weight = weightOf(ik, params);
if (weight <= 0) continue;
- if (ik.kind === 'look-at') solveLookAt(world, pose, rigRoot, ik, weight);
- else solveTwoBone(world, pose, rigRoot, ik, weight);
+ if (ik.kind === 'look-at') solveLookAt(world, pose, rigRoot, ik, weight, resolveJoint);
+ else solveTwoBone(world, pose, rigRoot, ik, weight, resolveJoint);
}
}
diff --git a/sdk/src/animation/animatorMask.ts b/sdk/src/animation/animatorMask.ts
index ea7855fef..b7d665b6d 100644
--- a/sdk/src/animation/animatorMask.ts
+++ b/sdk/src/animation/animatorMask.ts
@@ -13,17 +13,18 @@
import type { Entity } from '../types';
import type { World } from '../ecs/world';
-import { resolveChildEntity, collectSubtree } from '../ecs/childPath';
+import { collectSubtree } from '../ecs/childPath';
+import type { JointResolver } from './animatorAvatar';
import type { PoseTrack } from './pose';
import type { LayerReach } from './layerStack';
/** Which subtrees of the animated entity a layer may write. */
export interface AnimatorMask {
/**
- * Each names a subtree by `childPath`, the subtree's own root included; the
- * empty path is the whole rig. A mask with no paths admits nothing, which is
- * a layer switched off rather than a layer with no restriction — that is
- * spelled by having no mask at all.
+ * Each names a subtree by `childPath`, its own root included; the empty path
+ * is the whole rig, and no paths admits nothing — a layer switched off, which
+ * having no mask at all does not mean. Named the CLIP's way like everything
+ * a controller says, and translated by the rig's avatar.
*/
paths: string[];
}
@@ -37,10 +38,13 @@ export interface AnimatorMask {
export class MaskReach implements LayerReach {
private readonly admitted_ = new Set<Entity>();
- resolve(world: Pick<World, 'tryGet'>, root: Entity, mask: AnimatorMask): void {
+ resolve(
+ world: Pick<World, 'tryGet'>, root: Entity, mask: AnimatorMask,
+ resolveJoint: JointResolver,
+ ): void {
this.admitted_.clear();
for (const path of mask.paths) {
- const at = resolveChildEntity(world, root, path);
+ const at = resolveJoint(root, path);
if (at !== null) collectSubtree(world, at, this.admitted_);
}
}
diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.ts
index 07edc48f9..f0a984d8b 100644
--- a/sdk/src/animation/index.ts
+++ b/sdk/src/animation/index.ts
@@ -149,6 +149,15 @@ export {
type AnimClipSizing,
} from './AnimClipLoader';
+export {
+ parseAvatar,
+ emptyAvatar,
+ avatarResolver,
+ AVATAR_FORMAT_VERSION,
+ type AnimatorAvatar,
+ type JointResolver,
+} from './animatorAvatar';
+
export {
solveAnimatorIK,
type AnimatorIK,
diff --git a/sdk/src/animation/motion.ts b/sdk/src/animation/motion.ts
index dc672adc3..bf4f34ed2 100644
--- a/sdk/src/animation/motion.ts
+++ b/sdk/src/animation/motion.ts
@@ -23,6 +23,8 @@ import type { Entity, Quat, Vec3 } from '../types';
import type { World } from '../ecs/world';
import { Pose } from './pose';
import { mixPoses, type WeightedPose } from './poseMix';
+import { resolveChildEntity } from '../ecs/childPath';
+import type { JointResolver } from './animatorAvatar';
import { accumulateQuat, leanQuat, normalizeQuat } from './quatMix';
/** Parameter values a graph exposes to its motions (floats and bools). */
@@ -164,6 +166,13 @@ export interface MotionContext {
/** Borrow a displacement to combine nested ones into; hand it back. */
borrowDelta(): RootMotionDelta;
releaseDelta(delta: RootMotionDelta): void;
+ /**
+ * The joint `path` names on the rig being animated. A driver goes through
+ * here rather than resolving a childPath itself: a rig with an avatar spells
+ * its joints its own way, and that translation has to reach every reader of
+ * a path or a clip drives half a skeleton.
+ */
+ resolveJoint: JointResolver;
/**
* Whether the animator is taking this motion's root track as DISPLACEMENT.
* A driver that can state a root pose must then leave the root's position and
@@ -252,12 +261,15 @@ export class MotionRegistry {
* alternative is an object and three closures per animated entity per frame.
* A driver must not keep it — it describes only the call it was handed to.
*/
- context(world: World, entity: Entity, params: MotionParams): MotionContext {
+ context(
+ world: World, entity: Entity, params: MotionParams, resolveJoint?: JointResolver,
+ ): MotionContext {
const ctx = this.ctx_;
ctx.world = world;
ctx.entity = entity;
ctx.params = params;
ctx.extractRootMotion = false;
+ ctx.resolveJoint = resolveJoint ?? ((root, path) => resolveChildEntity(world, root, path));
return ctx;
}
@@ -285,6 +297,7 @@ export class MotionRegistry {
position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 },
},
releaseDelta: (delta) => { this.deltaPool_.push(delta); },
+ resolveJoint: (root, path) => resolveChildEntity(this.ctx_.world, root, path),
};
}
diff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.ts
index 06ed819bd..7e5ca76ea 100644
--- a/sdk/src/asset/AssetLoader.ts
+++ b/sdk/src/asset/AssetLoader.ts
@@ -70,6 +70,10 @@ export interface AnimatorControllerResult {
controllerId: string;
}
+export interface AvatarResult {
+ avatarId: string;
+}
+
export interface LocaleResult {
/** The locale the table's entries were merged into. */
locale: string;
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 64bde709b..3646c4c4a 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -41,6 +41,7 @@ import { TimelineAssetLoader } from './loaders/TimelineAssetLoader';
import { PrefabAssetLoader } from './loaders/PrefabAssetLoader';
import { FsmAssetLoader } from './loaders/FsmAssetLoader';
import { AnimatorControllerAssetLoader } from './loaders/AnimatorControllerAssetLoader';
+import { AvatarAssetLoader } from './loaders/AvatarAssetLoader';
import { BtAssetLoader } from './loaders/BtAssetLoader';
import { LocaleAssetLoader } from './loaders/LocaleAssetLoader';
import { JsonAssetLoader } from './loaders/JsonAssetLoader';
@@ -1300,6 +1301,7 @@ export class Assets {
const fsmPaths = discovered.byType.get('statemachine') ?? new Set<string>();
const btPaths = discovered.byType.get('behaviortree') ?? new Set<string>();
const animatorPaths = discovered.byType.get('animatorcontroller') ?? new Set<string>();
+ const avatarPaths = discovered.byType.get('avatar') ?? new Set<string>();
const meshPaths = discovered.byType.get('mesh') ?? new Set<string>();
const environmentPaths = discovered.byType.get('environment') ?? new Set<string>();
const spinePairs = discovered.spines;
@@ -1402,6 +1404,7 @@ export class Assets {
pushAcquire(fsmPaths, p => this.acquireTyped('statemachine', p), 'statemachine');
pushAcquire(btPaths, p => this.acquireTyped('behaviortree', p), 'behaviortree');
pushAcquire(animatorPaths, p => this.acquireTyped('animatorcontroller', p), 'animatorcontroller');
+ pushAcquire(avatarPaths, p => this.acquireTyped('avatar', p), 'avatar');
const totalCount = tasks.length;
onProgress?.(0, totalCount);
@@ -2225,6 +2228,7 @@ export class Assets {
this.register(new PrefabAssetLoader());
this.register(new FsmAssetLoader());
this.register(new AnimatorControllerAssetLoader());
+ this.register(new AvatarAssetLoader());
this.register(new BtAssetLoader());
this.register(new LocaleAssetLoader());
this.register(new JsonAssetLoader());
diff --git a/sdk/src/asset/loaders/AvatarAssetLoader.ts b/sdk/src/asset/loaders/AvatarAssetLoader.ts
new file mode 100644
index 000000000..52214d8ca
--- /dev/null
+++ b/sdk/src/asset/loaders/AvatarAssetLoader.ts
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AvatarAssetLoader.ts
+ * @brief Loads a `.esavatar` — how one rig spells the joints a clip names.
+ *
+ * Mirrors {@link file://./FsmAssetLoader.ts}: published by its slot, so a
+ * retiring era cannot take the newer one out from under the same name.
+ */
+import type {
+ AssetLoader, LoadContext, AvatarResult, RegistryAssetLoader,
+} from '../AssetLoader';
+import type { RegistryEra } from '../registryAssets';
+import { parseAvatar, type AnimatorAvatar } from '../../animation/animatorAvatar';
+
+export class AvatarAssetLoader implements AssetLoader<AvatarResult> {
+ readonly type = 'avatar';
+ readonly extensions = ['.esavatar'];
+
+ readonly registry: RegistryAssetLoader<AvatarResult> = {
+ prepare: async (path: string, ctx: LoadContext): Promise<RegistryEra<AvatarResult>> => {
+ const text = await ctx.loadText(ctx.catalog.getBuildPath(path));
+ const avatar: AnimatorAvatar = parseAvatar(JSON.parse(text));
+ return { published: avatar, value: { avatarId: path } };
+ },
+ };
+}
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 5670a0e5d..b66106b99 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -473,6 +473,10 @@ export {
migrateAnimatorController,
MaskReach,
solveAnimatorIK,
+ parseAvatar,
+ emptyAvatar,
+ avatarResolver,
+ AVATAR_FORMAT_VERSION,
overlayPose,
addPoseOver,
STATE_PATH_SEP,
@@ -483,6 +487,8 @@ export {
type AnimatorMask,
type AnimatorIK,
type AnimatorIKKind,
+ type AnimatorAvatar,
+ type JointResolver,
type AnimatorMigration,
type LayerReach,
type AnimatorPathEvalResult,
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index f41756967..395aa0d66 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -151,7 +151,7 @@ export class MissingAssetsError extends Error {
*
* @public
*/
-export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'mesh' | 'environment';
+export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller' | 'avatar' | 'mesh' | 'environment';
// =============================================================================
// Component Query Helpers (read from self-describing ComponentDef)
diff --git a/sdk/src/timeline/timelineMotion.ts b/sdk/src/timeline/timelineMotion.ts
index d8c7fa1e6..f566a248a 100644
--- a/sdk/src/timeline/timelineMotion.ts
+++ b/sdk/src/timeline/timelineMotion.ts
@@ -84,6 +84,10 @@ export function createTimelineMotionDriver(timeline: TimelineAPI): MotionDriver<
if (!asset) return false;
const local = applyWrapMode(time * speedOf(motion), asset.duration, wrapOf(motion, asset));
deps.world = ctx.world;
+ // Through the animator's resolver: a rig with an avatar spells its
+ // joints its own way, and a driver reaching for childPath directly
+ // would drive the joints of whoever exported the clip.
+ deps.resolveChild = ctx.resolveJoint;
sampleTimelineIntoPose(
asset, local.time, ctx.entity, deps, pose,
ctx.extractRootMotion ? WITHOUT_ROOT : undefined,
diff --git a/sdk/tests/animatorAvatar.test.ts b/sdk/tests/animatorAvatar.test.ts
new file mode 100644
index 000000000..5aff4fe64
--- /dev/null
+++ b/sdk/tests/animatorAvatar.test.ts
@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * The claim: ONE clip drives two rigs whose bones are named differently, at the
+ * same time, without a copy of the clip per rig.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ Animator, AnimatorControllerAPI, parseAvatar, emptyAvatar, avatarResolver,
+ type AnimatorData, type AnimatorControllerDef, type AnimatorAvatar,
+} from '../src/animation';
+import { Parent, Children, Name, Transform } from '../src/ecs/component';
+import { createTimelineMotionDriver, TIMELINE_MOTION } from '../src/timeline';
+import { TimelineAPI } from '../src/timeline/TimelineControl';
+import { WrapMode, TrackType, InterpType, type TimelineAsset } from '../src/timeline/TimelineTypes';
+
+function makeWorld() {
+ const store = new Map<unknown, Map<number, unknown>>();
+ const mapOf = (c: unknown) => {
+ let m = store.get(c);
+ if (!m) { m = new Map(); store.set(c, m); }
+ return m;
+ };
+ return {
+ insert(e: number, c: unknown, d: unknown) { mapOf(c).set(e, d); },
+ get(e: number, c: unknown) { return mapOf(c).get(e); },
+ has(e: number, c: unknown) { return mapOf(c).has(e); },
+ set(e: number, c: unknown, d: unknown) { mapOf(c).set(e, d); },
+ tryGet(e: number, c: unknown) { return mapOf(c).get(e) ?? null; },
+ update(e: number, c: unknown, edit: (d: any) => void) {
+ const d = mapOf(c).get(e); edit(d); mapOf(c).set(e, d);
+ },
+ getEntitiesWithComponents(comps: unknown[]) {
+ const [first, ...rest] = comps;
+ return [...mapOf(first).keys()].filter(e => rest.every(c => mapOf(c).has(e)));
+ },
+ } as any;
+}
+
+/** A rig whose one joint is called `boneName`, rooted at `root`. */
+function rig(world: any, root: number, joint: number, boneName: string) {
+ const place = (id: number, name: string) => {
+ world.insert(id, Name, { value: name });
+ world.insert(id, Transform, {
+ position: { x: 0, y: 0, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 },
+ scale: { x: 1, y: 1, z: 1 },
+ });
+ };
+ place(root, `Rig${root}`);
+ place(joint, boneName);
+ world.insert(joint, Parent, { entity: root });
+ world.insert(root, Children, { entities: [joint] });
+}
+
+/** A clip turning whatever joint `childPath` names a quarter turn about Z. */
+function turn(childPath: string): TimelineAsset {
+ const key = (value: number) => ([
+ { time: 0, value, inTangent: 0, outTangent: 0, interpolation: InterpType.Linear },
+ ]);
+ return {
+ version: '1.2', type: 'timeline', duration: 10, wrapMode: WrapMode.Loop,
+ tracks: [{
+ type: TrackType.Property, component: 'Transform', childPath, name: 't',
+ channels: [
+ { property: 'rotation.x', keyframes: key(0) },
+ { property: 'rotation.y', keyframes: key(0) },
+ { property: 'rotation.z', keyframes: key(Math.SQRT1_2) },
+ { property: 'rotation.w', keyframes: key(Math.SQRT1_2) },
+ ],
+ }],
+ } as TimelineAsset;
+}
+
+const turnedZ = (world: any, entity: number) =>
+ Number((world.get(entity, Transform) as { rotation: { z: number } }).rotation.z);
+
+/** One controller playing one clip, with avatars resolved from a table. */
+function controllerWith(avatars: Record<string, AnimatorAvatar>): AnimatorControllerAPI {
+ 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',
+ states: [{
+ name: 'Wave', transitions: [],
+ motion: { kind: TIMELINE_MOTION, clip: 'wave.estimeline', loop: true },
+ }],
+ } as AnimatorControllerDef);
+ return ctrl;
+}
+
+const attach = (world: any, entity: number, avatar: string) =>
+ world.insert(entity, Animator, {
+ controller: 'rig', avatar, currentState: '', layerStates: [], enabled: true,
+ } as AnimatorData);
+
+describe('reading an avatar', () => {
+ it('keeps only the joints that differ', () => {
+ // A name mapped to itself is what having no entry already means; keeping
+ // both spellings of that would be two records of one fact.
+ const avatar = parseAvatar({ joints: { Arm: 'mixamorig:LeftArm', Head: 'Head' } });
+ expect(avatar.joints).toEqual({ Arm: 'mixamorig:LeftArm' });
+ });
+
+ it('refuses a file from a later build, and a shape that is not one', () => {
+ expect(() => parseAvatar({ joints: {}, version: 99 })).toThrow(/version/);
+ expect(() => parseAvatar({ joints: [] })).toThrow(/joints/);
+ expect(() => parseAvatar({ joints: { Arm: 7 } })).toThrow(/childPath/);
+ expect(() => parseAvatar(null)).toThrow(/object/);
+ });
+
+ it('starts blank, translating nothing', () => {
+ expect(emptyAvatar().joints).toEqual({});
+ });
+
+ it('resolves a path with no entry as itself', () => {
+ const world = makeWorld();
+ rig(world, 1, 2, 'Arm');
+ const resolve = avatarResolver(world, parseAvatar({ joints: { Leg: 'Thigh' } }));
+ expect(resolve(1, 'Arm')).toBe(2);
+ expect(resolve(1, 'Missing')).toBeNull();
+ });
+});
+
+describe('one clip over two rigs', () => {
+ it('drives both, each by its own bone names, in the same frame', () => {
+ // The point of the whole thing. The clip names `Arm`; one rig calls that
+ // joint `Arm` and the other `mixamorig:LeftArm`, and neither needs a copy
+ // of the clip nor a controller of its own.
+ const world = makeWorld();
+ rig(world, 1, 2, 'Arm');
+ rig(world, 10, 11, 'mixamorig:LeftArm');
+
+ const imported = parseAvatar({ joints: { Arm: 'mixamorig:LeftArm' } });
+ const ctrl = controllerWith({ 'assets/imported.esavatar': imported });
+ attach(world, 1, '');
+ attach(world, 10, 'assets/imported.esavatar');
+
+ ctrl.update(world, 0.016);
+
+ expect(turnedZ(world, 2)).toBeCloseTo(Math.SQRT1_2, 4);
+ expect(turnedZ(world, 11)).toBeCloseTo(Math.SQRT1_2, 4);
+ });
+
+ it('leaves the rig alone when the avatar names a joint it has not got', () => {
+ const world = makeWorld();
+ rig(world, 1, 2, 'Arm');
+ const wrong = parseAvatar({ joints: { Arm: 'NoSuchBone' } });
+ const ctrl = controllerWith({ 'assets/wrong.esavatar': wrong });
+ attach(world, 1, 'assets/wrong.esavatar');
+
+ ctrl.update(world, 0.016);
+ expect(turnedZ(world, 2)).toBe(0);
+ });
+
+ it('translates the joints a MASK names as well', () => {
+ // A mask is the controller talking about a rig it has never seen, same as
+ // a clip and a constraint. Resolved without the avatar it admits nothing,
+ // and a layer that writes nothing looks exactly like one that is off.
+ const world = makeWorld();
+ rig(world, 1, 2, 'mixamorig:LeftArm');
+ const avatar = parseAvatar({ joints: { Arm: 'mixamorig:LeftArm' } });
+
+ const timeline = new TimelineAPI();
+ timeline.registerAsset('wave.estimeline', turn('Arm'));
+ const ctrl = new AnimatorControllerAPI();
+ ctrl.registerMotionDriver(TIMELINE_MOTION, createTimelineMotionDriver(timeline));
+ ctrl.useAssetAvatars(() => avatar);
+ ctrl.registerController('rig', {
+ version: 2, parameters: [], initialState: 'Rest',
+ states: [{ name: 'Rest', transitions: [] }],
+ layers: [{
+ name: 'Upper', mask: { paths: ['Arm'] }, initialState: 'Wave',
+ states: [{
+ name: 'Wave', transitions: [],
+ motion: { kind: TIMELINE_MOTION, clip: 'wave.estimeline', loop: true },
+ }],
+ }],
+ } as AnimatorControllerDef);
+ attach(world, 1, 'assets/a.esavatar');
+
+ ctrl.update(world, 0.016);
+ expect(turnedZ(world, 2)).toBeCloseTo(Math.SQRT1_2, 4);
+ });
+
+ it('translates the joints a CONSTRAINT names as well', () => {
+ // A constraint addresses joints the same way a clip does, so a rig whose
+ // avatar renames one has to have it renamed here too — or IK reaches for
+ // a joint the clip is no longer driving.
+ const world = makeWorld();
+ rig(world, 1, 2, 'mixamorig:LeftArm');
+ // A second joint on the same rig, to aim at.
+ world.insert(3, Name, { value: 'Goal' });
+ world.insert(3, Transform, {
+ position: { x: 0, y: 100, z: 0 }, rotation: { w: 1, x: 0, y: 0, z: 0 },
+ scale: { x: 1, y: 1, z: 1 },
+ });
+ world.insert(3, Parent, { entity: 1 });
+ world.insert(1, Children, { entities: [2, 3] });
+ world.update(2, Transform, (t: any) => { t.position = { x: 50, y: 0, z: 0 }; });
+
+ const avatar = parseAvatar({ joints: { Arm: 'mixamorig:LeftArm' } });
+ const timeline = new TimelineAPI();
+ timeline.registerAsset('wave.estimeline', turn('Arm'));
+ const ctrl = new AnimatorControllerAPI();
+ ctrl.registerMotionDriver(TIMELINE_MOTION, createTimelineMotionDriver(timeline));
+ ctrl.useAssetAvatars(() => avatar);
+ ctrl.registerController('rig', {
+ version: 2, parameters: [], initialState: 'Wave',
+ states: [{
+ name: 'Wave', transitions: [],
+ motion: { kind: TIMELINE_MOTION, clip: 'wave.estimeline', loop: true },
+ }],
+ // Names the joint the CLIP's way; the avatar has to reach it.
+ ik: [{ kind: 'look-at', tip: 'Arm', target: 'Goal', axis: 'x' }],
+ } as AnimatorControllerDef);
+ attach(world, 1, 'assets/a.esavatar');
+
+ ctrl.update(world, 0.016);
+
+ // The constraint aims the arm's +X along (-50,100) normalized. Measured
+ // on X as well as Y: the clip's own quarter turn puts +X at (0,1), which
+ // passes a test that only looks up.
+ const r = (world.get(2, Transform) as { rotation: { w: number; x: number; y: number; z: number } }).rotation;
+ const facingX = 1 - 2 * (r.y * r.y + r.z * r.z);
+ const facingY = 2 * (r.x * r.y + r.w * r.z);
+ expect(facingX).toBeCloseTo(-50 / Math.hypot(50, 100), 3);
+ expect(facingY).toBeCloseTo(100 / Math.hypot(50, 100), 3);
+ });
+});
diff --git a/sdk/tests/animatorIK.test.ts b/sdk/tests/animatorIK.test.ts
index 8da2796ba..85eecf0be 100644
--- a/sdk/tests/animatorIK.test.ts
+++ b/sdk/tests/animatorIK.test.ts
@@ -283,7 +283,7 @@ describe('a constraint through the animator', () => {
ik: [{ kind: 'two-bone', tip: 'Spine/Upper/Fore/Hand', target: 'Target' }],
} as AnimatorControllerDef);
world.insert(RIG, Animator, {
- controller: 'rig', currentState: '', layerStates: [], enabled: true,
+ controller: 'rig', avatar: '', currentState: '', layerStates: [], enabled: true,
} as AnimatorData);
ctrl.update(world, 0.016);
diff --git a/sdk/tests/animatorLayers.test.ts b/sdk/tests/animatorLayers.test.ts
index 02d6fbd9a..6829efb31 100644
--- a/sdk/tests/animatorLayers.test.ts
+++ b/sdk/tests/animatorLayers.test.ts
@@ -112,7 +112,7 @@ function build(
function attach(world: any): void {
world.insert(E, Animator, {
- controller: 'rig', currentState: '', layerStates: [], enabled: true,
+ controller: 'rig', avatar: '', currentState: '', layerStates: [], enabled: true,
} as AnimatorData);
}
diff --git a/tools/assetMetaTable.js b/tools/assetMetaTable.js
index e3348d352..09fd6331a 100644
--- a/tools/assetMetaTable.js
+++ b/tools/assetMetaTable.js
@@ -87,6 +87,7 @@ export const EXT_TO_TYPE = Object.freeze({
'.esfsm': 'statemachine',
'.esbt': 'behaviortree',
'.esanimator': 'animatorcontroller',
+ '.esavatar': 'avatar',
'.eslocale': 'locale',
'.inputmap': 'inputmap',
// Fonts