A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(anim): one clip drives rigs that do not share its bone names
esengine793157a0aee1
diff --git a/desktop b/desktopindex ced6c9cb9..5b6070623 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit ced6c9cb96a3853cd26b6a4065669240d98870fc+Subproject commit 5b6070623a4dd0993b1914f2ebc8ff42d142a586diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.jsonindex 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.tsindex 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.mdindex 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: AnimationPluginComponentDef<AnimatorData>```+## AnimatorAvatar — interface @experimental+```+joints: Record<string, string>+```+## AnimatorBlend1D — interface @experimental```parameter: string@@ -480,6 +490,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => voidupdate: (world: World, dt?: number, events?: AnimatorEventSink) => void+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => voidstatic new (): AnimatorControllerAPIstatic prototype: AnimatorControllerAPI```@@ -497,6 +508,7 @@ version: number | undefined## AnimatorData — interface @beta```+avatar: stringcontroller: stringcurrentState: stringenabled: 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: booleantype: 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) => voidstatic new (): MaskReachstatic prototype: MaskReach```@@ -5222,6 +5239,7 @@ params: Readonly<Record<string, number | boolean>>releaseDelta: (delta: RootMotionDelta) => voidreleaseMix: (mix: WeightedPose[]) => voidreleasePose: (pose: Pose) => void+resolveJoint: JointResolverrootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => booleansample: (motion: AnimatorMotion, time: number, pose: Pose) => booleanworld: 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) => MotionContextdriverFor: (motion: AnimatorMotion) => MotionDriver | undefinedhas: (kind: string) => booleanregister: <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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: AnimationPluginComponentDef<AnimatorData>```+## AnimatorAvatar — interface @experimental+```+joints: Record<string, string>+```+## AnimatorBlend1D — interface @experimental```parameter: string@@ -480,6 +490,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => voidupdate: (world: World, dt?: number, events?: AnimatorEventSink) => void+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => voidstatic new (): AnimatorControllerAPIstatic prototype: AnimatorControllerAPI```@@ -497,6 +508,7 @@ version: number | undefined## AnimatorData — interface @beta```+avatar: stringcontroller: stringcurrentState: stringenabled: 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: booleantype: 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) => voidstatic new (): MaskReachstatic prototype: MaskReach```@@ -5235,6 +5252,7 @@ params: Readonly<Record<string, number | boolean>>releaseDelta: (delta: RootMotionDelta) => voidreleaseMix: (mix: WeightedPose[]) => voidreleasePose: (pose: Pose) => void+resolveJoint: JointResolverrootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => booleansample: (motion: AnimatorMotion, time: number, pose: Pose) => booleanworld: 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) => MotionContextdriverFor: (motion: AnimatorMotion) => MotionDriver | undefinedhas: (kind: string) => booleanregister: <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 @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: AnimationPluginComponentDef<AnimatorData>```+## AnimatorAvatar — interface @experimental+```+joints: Record<string, string>+```+## AnimatorBlend1D — interface @experimental```parameter: string@@ -475,6 +485,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => voidupdate: (world: World, dt?: number, events?: AnimatorEventSink) => void+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => voidstatic new (): AnimatorControllerAPIstatic prototype: AnimatorControllerAPI```@@ -492,6 +503,7 @@ version: number | undefined## AnimatorData — interface @beta```+avatar: stringcontroller: stringcurrentState: stringenabled: 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: booleantype: 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) => voidstatic new (): MaskReachstatic prototype: MaskReach```@@ -5217,6 +5234,7 @@ params: Readonly<Record<string, number | boolean>>releaseDelta: (delta: RootMotionDelta) => voidreleaseMix: (mix: WeightedPose[]) => voidreleasePose: (pose: Pose) => void+resolveJoint: JointResolverrootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => booleansample: (motion: AnimatorMotion, time: number, pose: Pose) => booleanworld: 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) => MotionContextdriverFor: (motion: AnimatorMotion) => MotionDriver | undefinedhas: (kind: string) => booleanregister: <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 @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: AnimationPluginComponentDef<AnimatorData>```+## AnimatorAvatar — interface @experimental+```+joints: Record<string, string>+```+## AnimatorBlend1D — interface @experimental```parameter: string@@ -475,6 +485,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => voidupdate: (world: World, dt?: number, events?: AnimatorEventSink) => void+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => voidstatic new (): AnimatorControllerAPIstatic prototype: AnimatorControllerAPI```@@ -492,6 +503,7 @@ version: number | undefined## AnimatorData — interface @beta```+avatar: stringcontroller: stringcurrentState: stringenabled: 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: booleantype: 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) => voidstatic new (): MaskReachstatic prototype: MaskReach```@@ -5465,6 +5482,7 @@ params: Readonly<Record<string, number | boolean>>releaseDelta: (delta: RootMotionDelta) => voidreleaseMix: (mix: WeightedPose[]) => voidreleasePose: (pose: Pose) => void+resolveJoint: JointResolverrootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => booleansample: (motion: AnimatorMotion, time: number, pose: Pose) => booleanworld: 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) => MotionContextdriverFor: (motion: AnimatorMotion) => MotionDriver | undefinedhas: (kind: string) => booleanregister: <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 @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: AnimationPluginComponentDef<AnimatorData>```+## AnimatorAvatar — interface @experimental+```+joints: Record<string, string>+```+## AnimatorBlend1D — interface @experimental```parameter: string@@ -475,6 +485,7 @@ setSpineDriver: (driver: SpineAnimationDriver | null) => voidsetTrigger: (entity: Entity, name: string) => voidunregisterController: (name: string) => voidupdate: (world: World, dt?: number, events?: AnimatorEventSink) => void+useAssetAvatars: (source: (ref: string) => AnimatorAvatar | undefined) => voidstatic new (): AnimatorControllerAPIstatic prototype: AnimatorControllerAPI```@@ -492,6 +503,7 @@ version: number | undefined## AnimatorData — interface @beta```+avatar: stringcontroller: stringcurrentState: stringenabled: 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: booleantype: 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) => voidstatic new (): MaskReachstatic prototype: MaskReach```@@ -5224,6 +5241,7 @@ params: Readonly<Record<string, number | boolean>>releaseDelta: (delta: RootMotionDelta) => voidreleaseMix: (mix: WeightedPose[]) => voidreleasePose: (pose: Pose) => void+resolveJoint: JointResolverrootDelta: (motion: AnimatorMotion, span: MotionSpan, out: RootMotionDelta) => booleansample: (motion: AnimatorMotion, time: number, pose: Pose) => booleanworld: 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) => MotionContextdriverFor: (motion: AnimatorMotion) => MotionDriver | undefinedhas: (kind: string) => booleanregister: <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 @experimentaldiff --git a/sdk/src/animation/AnimationPlugin.ts b/sdk/src/animation/AnimationPlugin.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.jsindex 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