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): the graph ops address a layer, without a second vocabulary

esengine2133e70ddff7
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index a7027c068..90dc9c531 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": 1854,
+ "experimental": 1858,
"deprecated": 3
},
- "total": 2069,
+ "total": 2073,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 44f77fd05..ad19e1836 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 · 1693 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1697 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -10611,6 +10611,11 @@ TransformData
(config: AssetGroupsConfig | null | undefined): string | undefined
```
+## addAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+```
+
## addAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef
@@ -10618,12 +10623,12 @@ TransformData
## addAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x?: number, y?: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x?: number, y?: number, layer?: number): AnimatorControllerDef
```
## addAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, to: string, layer?: number): AnimatorControllerDef
```
## addBtChild — function @experimental
@@ -10748,7 +10753,7 @@ AnimationPlugin
## animatorEdges — function @experimental
```
-(def: AnimatorControllerDef): AnimatorEdge[]
+(def: AnimatorControllerDef, layer?: number): AnimatorEdge[]
```
## animatorLayer — function @experimental
@@ -12476,9 +12481,14 @@ MeshRendererPlugin
(st: AnimatorState): AnimatorMotion | null
```
+## moveAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, to: number): AnimatorControllerDef
+```
+
## moveAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x: number, y: number, layer?: number): AnimatorControllerDef
```
## moveBtNode — function @experimental
@@ -13036,6 +13046,11 @@ PrefabsPlugin
(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
+## removeAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number): AnimatorControllerDef
+```
+
## removeAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string): AnimatorControllerDef
@@ -13043,12 +13058,12 @@ PrefabsPlugin
## removeAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## removeAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, layer?: number): AnimatorControllerDef
```
## removeBtNode — function @experimental
@@ -13073,7 +13088,7 @@ PrefabsPlugin
## renameAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef
+(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
## renameState — function @experimental
@@ -13353,27 +13368,27 @@ ServicesPlugin
## setAnimatorConditions — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[], layer?: number): AnimatorControllerDef
```
## setAnimatorInitial — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateClip — function @experimental
```
-(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, clip: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateMotion — function @experimental
```
-(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null, layer?: number): AnimatorControllerDef
```
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef
```
## setBtNodeField — function @experimental
@@ -13856,6 +13871,11 @@ UIVisibilityPlugin
(id: string): void
```
+## updateAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, patch: Pick<Partial<AnimatorLayer>, "name" | "weight" | "blend" | "mask">): AnimatorControllerDef
+```
+
## updateAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef
@@ -13863,7 +13883,7 @@ UIVisibilityPlugin
## updateAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>, layer?: number): AnimatorControllerDef
```
## updateCameraAspectRatio — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index f48c02178..6f6d3f32c 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 · 1712 experimental · 3 deprecated
+Symbols: 114 public · 99 beta · 1716 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -10804,6 +10804,11 @@ TransformData
(config: AssetGroupsConfig | null | undefined): string | undefined
```
+## addAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+```
+
## addAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef
@@ -10811,12 +10816,12 @@ TransformData
## addAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x?: number, y?: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x?: number, y?: number, layer?: number): AnimatorControllerDef
```
## addAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, to: string, layer?: number): AnimatorControllerDef
```
## addBtChild — function @experimental
@@ -10941,7 +10946,7 @@ AnimationPlugin
## animatorEdges — function @experimental
```
-(def: AnimatorControllerDef): AnimatorEdge[]
+(def: AnimatorControllerDef, layer?: number): AnimatorEdge[]
```
## animatorLayer — function @experimental
@@ -12719,9 +12724,14 @@ MeshRendererPlugin
(st: AnimatorState): AnimatorMotion | null
```
+## moveAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, to: number): AnimatorControllerDef
+```
+
## moveAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x: number, y: number, layer?: number): AnimatorControllerDef
```
## moveBtNode — function @experimental
@@ -13279,6 +13289,11 @@ PrefabsPlugin
(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
+## removeAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number): AnimatorControllerDef
+```
+
## removeAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string): AnimatorControllerDef
@@ -13286,12 +13301,12 @@ PrefabsPlugin
## removeAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## removeAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, layer?: number): AnimatorControllerDef
```
## removeBtNode — function @experimental
@@ -13316,7 +13331,7 @@ PrefabsPlugin
## renameAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef
+(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
## renameState — function @experimental
@@ -13596,27 +13611,27 @@ ServicesPlugin
## setAnimatorConditions — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[], layer?: number): AnimatorControllerDef
```
## setAnimatorInitial — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateClip — function @experimental
```
-(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, clip: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateMotion — function @experimental
```
-(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null, layer?: number): AnimatorControllerDef
```
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef
```
## setBtNodeField — function @experimental
@@ -14099,6 +14114,11 @@ UIVisibilityPlugin
(id: string): void
```
+## updateAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, patch: Pick<Partial<AnimatorLayer>, "name" | "weight" | "blend" | "mask">): AnimatorControllerDef
+```
+
## updateAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef
@@ -14106,7 +14126,7 @@ UIVisibilityPlugin
## updateAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>, layer?: number): AnimatorControllerDef
```
## updateCameraAspectRatio — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index b93758922..7523875f4 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 · 1692 experimental · 3 deprecated
+Symbols: 114 public · 96 beta · 1696 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10606,6 +10606,11 @@ TransformData
(config: AssetGroupsConfig | null | undefined): string | undefined
```
+## addAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+```
+
## addAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef
@@ -10613,12 +10618,12 @@ TransformData
## addAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x?: number, y?: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x?: number, y?: number, layer?: number): AnimatorControllerDef
```
## addAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, to: string, layer?: number): AnimatorControllerDef
```
## addBtChild — function @experimental
@@ -10743,7 +10748,7 @@ AnimationPlugin
## animatorEdges — function @experimental
```
-(def: AnimatorControllerDef): AnimatorEdge[]
+(def: AnimatorControllerDef, layer?: number): AnimatorEdge[]
```
## animatorLayer — function @experimental
@@ -12476,9 +12481,14 @@ MeshRendererPlugin
(st: AnimatorState): AnimatorMotion | null
```
+## moveAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, to: number): AnimatorControllerDef
+```
+
## moveAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x: number, y: number, layer?: number): AnimatorControllerDef
```
## moveBtNode — function @experimental
@@ -13041,6 +13051,11 @@ PrefabsPlugin
(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
+## removeAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number): AnimatorControllerDef
+```
+
## removeAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string): AnimatorControllerDef
@@ -13048,12 +13063,12 @@ PrefabsPlugin
## removeAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## removeAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, layer?: number): AnimatorControllerDef
```
## removeBtNode — function @experimental
@@ -13078,7 +13093,7 @@ PrefabsPlugin
## renameAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef
+(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
## renameState — function @experimental
@@ -13358,27 +13373,27 @@ ServicesPlugin
## setAnimatorConditions — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[], layer?: number): AnimatorControllerDef
```
## setAnimatorInitial — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateClip — function @experimental
```
-(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, clip: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateMotion — function @experimental
```
-(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null, layer?: number): AnimatorControllerDef
```
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef
```
## setBtNodeField — function @experimental
@@ -13861,6 +13876,11 @@ UIVisibilityPlugin
(id: string): void
```
+## updateAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, patch: Pick<Partial<AnimatorLayer>, "name" | "weight" | "blend" | "mask">): AnimatorControllerDef
+```
+
## updateAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef
@@ -13868,7 +13888,7 @@ UIVisibilityPlugin
## updateAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>, layer?: number): AnimatorControllerDef
```
## updateCameraAspectRatio — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 3e170e615..6c37d26e9 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 · 1714 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1718 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10860,6 +10860,11 @@ TransformData
(config: AssetGroupsConfig | null | undefined): string | undefined
```
+## addAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+```
+
## addAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef
@@ -10867,12 +10872,12 @@ TransformData
## addAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x?: number, y?: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x?: number, y?: number, layer?: number): AnimatorControllerDef
```
## addAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, to: string, layer?: number): AnimatorControllerDef
```
## addBtChild — function @experimental
@@ -10997,7 +11002,7 @@ AnimationPlugin
## animatorEdges — function @experimental
```
-(def: AnimatorControllerDef): AnimatorEdge[]
+(def: AnimatorControllerDef, layer?: number): AnimatorEdge[]
```
## animatorLayer — function @experimental
@@ -12740,9 +12745,14 @@ MeshRendererPlugin
(st: AnimatorState): AnimatorMotion | null
```
+## moveAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, to: number): AnimatorControllerDef
+```
+
## moveAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x: number, y: number, layer?: number): AnimatorControllerDef
```
## moveBtNode — function @experimental
@@ -13300,6 +13310,11 @@ PrefabsPlugin
(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
+## removeAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number): AnimatorControllerDef
+```
+
## removeAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string): AnimatorControllerDef
@@ -13307,12 +13322,12 @@ PrefabsPlugin
## removeAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## removeAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, layer?: number): AnimatorControllerDef
```
## removeBtNode — function @experimental
@@ -13337,7 +13352,7 @@ PrefabsPlugin
## renameAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef
+(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
## renameState — function @experimental
@@ -13617,27 +13632,27 @@ ServicesPlugin
## setAnimatorConditions — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[], layer?: number): AnimatorControllerDef
```
## setAnimatorInitial — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateClip — function @experimental
```
-(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, clip: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateMotion — function @experimental
```
-(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null, layer?: number): AnimatorControllerDef
```
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef
```
## setBtNodeField — function @experimental
@@ -14120,6 +14135,11 @@ UIVisibilityPlugin
(id: string): void
```
+## updateAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, patch: Pick<Partial<AnimatorLayer>, "name" | "weight" | "blend" | "mask">): AnimatorControllerDef
+```
+
## updateAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef
@@ -14127,7 +14147,7 @@ UIVisibilityPlugin
## updateAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>, layer?: number): AnimatorControllerDef
```
## updateCameraAspectRatio — function @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 092a6c6bd..c7cbd829e 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 · 1704 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1708 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -10634,6 +10634,11 @@ TransformData
(config: AssetGroupsConfig | null | undefined): string | undefined
```
+## addAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+```
+
## addAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, type: AnimatorParamType): AnimatorControllerDef
@@ -10641,12 +10646,12 @@ TransformData
## addAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x?: number, y?: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x?: number, y?: number, layer?: number): AnimatorControllerDef
```
## addAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, to: string, layer?: number): AnimatorControllerDef
```
## addBtChild — function @experimental
@@ -10771,7 +10776,7 @@ AnimationPlugin
## animatorEdges — function @experimental
```
-(def: AnimatorControllerDef): AnimatorEdge[]
+(def: AnimatorControllerDef, layer?: number): AnimatorEdge[]
```
## animatorLayer — function @experimental
@@ -12504,9 +12509,14 @@ MeshRendererPlugin
(st: AnimatorState): AnimatorMotion | null
```
+## moveAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, to: number): AnimatorControllerDef
+```
+
## moveAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, x: number, y: number, layer?: number): AnimatorControllerDef
```
## moveBtNode — function @experimental
@@ -13064,6 +13074,11 @@ PrefabsPlugin
(compData: SceneComponentData, entityMap: Map<number, Entity>, external?: ReadonlyMap<number, Entity>): void
```
+## removeAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number): AnimatorControllerDef
+```
+
## removeAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string): AnimatorControllerDef
@@ -13071,12 +13086,12 @@ PrefabsPlugin
## removeAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## removeAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, layer?: number): AnimatorControllerDef
```
## removeBtNode — function @experimental
@@ -13101,7 +13116,7 @@ PrefabsPlugin
## renameAnimatorState — function @experimental
```
-(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef
+(def: AnimatorControllerDef, oldName: string, newName: string, layer?: number): AnimatorControllerDef
```
## renameState — function @experimental
@@ -13381,27 +13396,27 @@ ServicesPlugin
## setAnimatorConditions — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[], layer?: number): AnimatorControllerDef
```
## setAnimatorInitial — function @experimental
```
-(def: AnimatorControllerDef, name: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateClip — function @experimental
```
-(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, clip: string, layer?: number): AnimatorControllerDef
```
## setAnimatorStateMotion — function @experimental
```
-(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null, layer?: number): AnimatorControllerDef
```
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef
```
## setBtNodeField — function @experimental
@@ -13884,6 +13899,11 @@ UIVisibilityPlugin
(id: string): void
```
+## updateAnimatorLayer — function @experimental
+```
+(def: AnimatorControllerDef, index: number, patch: Pick<Partial<AnimatorLayer>, "name" | "weight" | "blend" | "mask">): AnimatorControllerDef
+```
+
## updateAnimatorParam — function @experimental
```
(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef
@@ -13891,7 +13911,7 @@ UIVisibilityPlugin
## updateAnimatorTransition — function @experimental
```
-(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>): AnimatorControllerDef
+(def: AnimatorControllerDef, from: string, index: number, patch: Partial<AnimatorTransition>, layer?: number): AnimatorControllerDef
```
## updateCameraAspectRatio — function @experimental
diff --git a/sdk/src/animation/animatorGraph.ts b/sdk/src/animation/animatorGraph.ts
index 2d43be987..5d2637a0e 100644
--- a/sdk/src/animation/animatorGraph.ts
+++ b/sdk/src/animation/animatorGraph.ts
@@ -14,8 +14,11 @@
*/
import { ANIMATOR_FORMAT_VERSION } from './Animator';
+import { animatorLayer } from './Animator';
import type {
AnimatorControllerDef,
+ AnimatorLayer,
+ AnimatorScope,
AnimatorState,
AnimatorTransition,
AnimatorCondition,
@@ -32,20 +35,52 @@ import {
/** A flattened transition edge, for the graph canvas. */
export type AnimatorEdge = GraphEdge<AnimatorTransition>;
-const spec: GraphSpec<AnimatorControllerDef, AnimatorState, AnimatorTransition> = {
- states: def => def.states,
- withStates: (def, states) => ({ ...def, states }),
- initial: def => def.initialState,
- withInitial: (def, initialState) => ({ ...def, initialState }),
- transitions: state => state.transitions,
- withTransitions: (state, transitions) => ({ ...state, transitions }),
- makeState: (name, x, y) => ({ name, x, y, transitions: [] }),
- makeTransition: to => ({ to, conditions: [] }),
-};
+type AnimatorSpec = GraphSpec<AnimatorControllerDef, AnimatorState, AnimatorTransition>;
+
+/** A controller with layer `index` patched; the base layer is the def itself. */
+function withLayer(
+ def: AnimatorControllerDef, index: number, patch: Partial<AnimatorLayer>,
+): AnimatorControllerDef {
+ if (index === 0) return { ...def, ...patch };
+ const layers = (def.layers ?? []).map((l, i) => (i === index - 1 ? { ...l, ...patch } : l));
+ return { ...def, layers };
+}
+
+/** Layer `index` as a scope, or an empty one for an index that is not there. */
+function scopeAt(def: AnimatorControllerDef, index: number): AnimatorScope {
+ return animatorLayer(def, index) ?? EMPTY_SCOPE;
+}
+
+const EMPTY_SCOPE: AnimatorScope = { states: [], initialState: '' };
+
+/**
+ * Every graph op is the same op on a different layer, so the layer is the only
+ * thing that varies here — which is what keeps adding layers from multiplying
+ * the editor's vocabulary. Memoized because a spec is identity-free and the ops
+ * are called per keystroke.
+ */
+const specs = new Map<number, AnimatorSpec>();
+
+function specFor(index: number): AnimatorSpec {
+ let found = specs.get(index);
+ if (found) return found;
+ found = {
+ states: def => scopeAt(def, index).states,
+ withStates: (def, states) => withLayer(def, index, { states }),
+ initial: def => scopeAt(def, index).initialState,
+ withInitial: (def, initialState) => withLayer(def, index, { initialState }),
+ transitions: state => state.transitions,
+ withTransitions: (state, transitions) => ({ ...state, transitions }),
+ makeState: (name, x, y) => ({ name, x, y, transitions: [] }),
+ makeTransition: to => ({ to, conditions: [] }),
+ };
+ specs.set(index, found);
+ return found;
+}
/** Flatten every state's outgoing transitions into addressable edges. */
-export function animatorEdges(def: AnimatorControllerDef): AnimatorEdge[] {
- return graphEdges(spec, def);
+export function animatorEdges(def: AnimatorControllerDef, layer = 0): AnimatorEdge[] {
+ return graphEdges(specFor(layer), def);
}
/** A blank controller with one initial state and no parameters. */
@@ -58,33 +93,35 @@ export function emptyAnimatorController(): AnimatorControllerDef {
};
}
-export function addState(def: AnimatorControllerDef, name: string, x = 0, y = 0): AnimatorControllerDef {
- return addGraphState(spec, def, name, x, y);
+export function addState(def: AnimatorControllerDef, name: string, x = 0, y = 0, layer = 0): AnimatorControllerDef {
+ return addGraphState(specFor(layer), def, name, x, y);
}
-export function removeState(def: AnimatorControllerDef, name: string): AnimatorControllerDef {
- return removeGraphState(spec, def, name);
+export function removeState(def: AnimatorControllerDef, name: string, layer = 0): AnimatorControllerDef {
+ return removeGraphState(specFor(layer), def, name);
}
-export function moveState(def: AnimatorControllerDef, name: string, x: number, y: number): AnimatorControllerDef {
- return moveGraphState(spec, def, name, x, y);
+export function moveState(def: AnimatorControllerDef, name: string, x: number, y: number, layer = 0): AnimatorControllerDef {
+ return moveGraphState(specFor(layer), def, name, x, y);
}
/**
* Rename a state. On top of the shared rewiring (initial + per-state transition
* targets) an animator also has any-state transitions to repoint.
*/
-export function renameState(def: AnimatorControllerDef, oldName: string, newName: string): AnimatorControllerDef {
- const next = renameGraphState(spec, def, oldName, newName);
- if (next === def || !def.anyStateTransitions) return next;
- return {
- ...next,
- anyStateTransitions: def.anyStateTransitions.map(t => (t.to === oldName ? { ...t, to: newName } : t)),
- };
+export function renameState(
+ def: AnimatorControllerDef, oldName: string, newName: string, layer = 0,
+): AnimatorControllerDef {
+ const next = renameGraphState(specFor(layer), def, oldName, newName);
+ const anyState = scopeAt(def, layer).anyStateTransitions;
+ if (next === def || !anyState) return next;
+ return withLayer(next, layer, {
+ anyStateTransitions: anyState.map(t => (t.to === oldName ? { ...t, to: newName } : t)),
+ });
}
-export function setInitial(def: AnimatorControllerDef, name: string): AnimatorControllerDef {
- return setGraphInitial(spec, def, name);
+export function setInitial(def: AnimatorControllerDef, name: string, layer = 0): AnimatorControllerDef {
+ return setGraphInitial(specFor(layer), def, name);
}
/**
@@ -101,12 +138,13 @@ function withMotion(s: AnimatorState, motion: Partial<AnimatorState>): AnimatorS
}
/** Set the state's motion to a single sprite clip (clears any other motion). */
-export function setStateClip(def: AnimatorControllerDef, name: string, clip: string): AnimatorControllerDef {
- return {
- ...def,
- states: def.states.map((s) =>
+export function setStateClip(
+ def: AnimatorControllerDef, name: string, clip: string, layer = 0,
+): AnimatorControllerDef {
+ return withLayer(def, layer, {
+ states: scopeAt(def, layer).states.map((s) =>
s.name === name ? withMotion(s, clip ? { clip } : {}) : s),
- };
+ });
}
/**
@@ -114,28 +152,29 @@ export function setStateClip(def: AnimatorControllerDef, name: string, clip: str
* either. Null clears it, leaving a state that plays nothing.
*/
export function setStateMotion(
- def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null,
+ def: AnimatorControllerDef, name: string, motion: AnimatorMotion | null, layer = 0,
): AnimatorControllerDef {
- return {
- ...def,
- states: def.states.map((s) =>
+ return withLayer(def, layer, {
+ states: scopeAt(def, layer).states.map((s) =>
s.name === name ? withMotion(s, motion ? { motion } : {}) : s),
- };
+ });
}
export function setStateProps(
def: AnimatorControllerDef, name: string,
- patch: { speed?: number; loop?: boolean; rootMotion?: boolean },
+ patch: { speed?: number; loop?: boolean; rootMotion?: boolean }, layer = 0,
): AnimatorControllerDef {
- return { ...def, states: def.states.map((s) => (s.name === name ? { ...s, ...patch } : s)) };
+ return withLayer(def, layer, {
+ states: scopeAt(def, layer).states.map((s) => (s.name === name ? { ...s, ...patch } : s)),
+ });
}
-export function addTransition(def: AnimatorControllerDef, from: string, to: string): AnimatorControllerDef {
- return addGraphTransition(spec, def, from, to);
+export function addTransition(def: AnimatorControllerDef, from: string, to: string, layer = 0): AnimatorControllerDef {
+ return addGraphTransition(specFor(layer), def, from, to);
}
-export function removeTransition(def: AnimatorControllerDef, from: string, index: number): AnimatorControllerDef {
- return removeGraphTransition(spec, def, from, index);
+export function removeTransition(def: AnimatorControllerDef, from: string, index: number, layer = 0): AnimatorControllerDef {
+ return removeGraphTransition(specFor(layer), def, from, index);
}
export function updateTransition(
@@ -143,13 +182,17 @@ export function updateTransition(
from: string,
index: number,
patch: Partial<AnimatorTransition>,
+ layer = 0,
): AnimatorControllerDef {
- return updateGraphTransition(spec, def, from, index, patch);
+ return updateGraphTransition(specFor(layer), def, from, index, patch);
}
/** Replace the whole condition list on a transition. */
-export function setConditions(def: AnimatorControllerDef, from: string, index: number, conditions: AnimatorCondition[]): AnimatorControllerDef {
- return updateTransition(def, from, index, { conditions });
+export function setConditions(
+ def: AnimatorControllerDef, from: string, index: number,
+ conditions: AnimatorCondition[], layer = 0,
+): AnimatorControllerDef {
+ return updateTransition(def, from, index, { conditions }, layer);
}
// — Parameters —
@@ -166,3 +209,55 @@ export function removeParam(def: AnimatorControllerDef, name: string): AnimatorC
export function updateParam(def: AnimatorControllerDef, name: string, patch: Partial<AnimatorParam>): AnimatorControllerDef {
return { ...def, parameters: def.parameters.map((p) => (p.name === name ? { ...p, ...patch } : p)) };
}
+
+// — Layers —
+
+/**
+ * A new layer over the ones already there, with one state of its own. Added at
+ * the top because that is what "over" means and it is where an author who just
+ * asked for a layer expects to find it.
+ */
+export function addLayer(def: AnimatorControllerDef, name: string): AnimatorControllerDef {
+ if (!name || (def.layers ?? []).some(l => l.name === name)) return def;
+ const layer: AnimatorLayer = {
+ name,
+ states: [{ name: 'Idle', x: 80, y: 80, transitions: [] }],
+ initialState: 'Idle',
+ };
+ return { ...def, layers: [...(def.layers ?? []), layer] };
+}
+
+/** Drop layer `index`. The base layer is not one of these and cannot be removed:
+ * a controller with no base is a controller that poses nothing. */
+export function removeLayer(def: AnimatorControllerDef, index: number): AnimatorControllerDef {
+ if (index <= 0 || !def.layers?.[index - 1]) return def;
+ return { ...def, layers: def.layers.filter((_, i) => i !== index - 1) };
+}
+
+/** Patch what layer `index` is, as opposed to what its machine does. Refuses the
+ * base layer, which has no weight, blend or mask to set. */
+export function updateLayer(
+ def: AnimatorControllerDef, index: number,
+ patch: Pick<Partial<AnimatorLayer>, 'name' | 'weight' | 'blend' | 'mask'>,
+): AnimatorControllerDef {
+ if (index <= 0 || !def.layers?.[index - 1]) return def;
+ return withLayer(def, index, patch);
+}
+
+/**
+ * Move layer `index` to `to`, both counted with the base layer at 0. Order is
+ * what a stack means, so this is an edit like any other rather than a view
+ * setting — and the base layer neither moves nor is displaced.
+ */
+export function moveLayer(
+ def: AnimatorControllerDef, index: number, to: number,
+): AnimatorControllerDef {
+ const layers = def.layers;
+ if (!layers || index <= 0 || to <= 0) return def;
+ const from = index - 1;
+ const dest = Math.min(to - 1, layers.length - 1);
+ if (from === dest || !layers[from]) return def;
+ const next = layers.slice();
+ next.splice(dest, 0, next.splice(from, 1)[0]!);
+ return { ...def, layers: next };
+}
diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.ts
index 969c82cbf..3da08b979 100644
--- a/sdk/src/animation/index.ts
+++ b/sdk/src/animation/index.ts
@@ -96,6 +96,10 @@ export {
removeTransition as removeAnimatorTransition,
updateTransition as updateAnimatorTransition,
setConditions as setAnimatorConditions,
+ addLayer as addAnimatorLayer,
+ removeLayer as removeAnimatorLayer,
+ updateLayer as updateAnimatorLayer,
+ moveLayer as moveAnimatorLayer,
addParam as addAnimatorParam,
removeParam as removeAnimatorParam,
updateParam as updateAnimatorParam,
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index ba88a98ec..be56d08ba 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -488,6 +488,10 @@ export {
removeAnimatorTransition,
updateAnimatorTransition,
setAnimatorConditions,
+ addAnimatorLayer,
+ removeAnimatorLayer,
+ updateAnimatorLayer,
+ moveAnimatorLayer,
addAnimatorParam,
removeAnimatorParam,
updateAnimatorParam,
diff --git a/sdk/tests/animator-graph.test.ts b/sdk/tests/animator-graph.test.ts
index fc8883ad2..0cf6bc184 100644
--- a/sdk/tests/animator-graph.test.ts
+++ b/sdk/tests/animator-graph.test.ts
@@ -11,7 +11,10 @@ import {
addState, removeState, moveState, renameState, setInitial,
addTransition, removeTransition, updateTransition, setConditions,
addParam, removeParam, updateParam,
+ addLayer as addAnimatorLayer, removeLayer as removeAnimatorLayer,
+ updateLayer as updateAnimatorLayer, moveLayer as moveAnimatorLayer,
} from '../src/animation/animatorGraph';
+import { animatorLayerCount, ANIMATOR_FORMAT_VERSION } from '../src/animation/Animator';
import type { AnimatorControllerDef } from '../src/animation/Animator';
describe('animatorGraph', () => {
@@ -94,3 +97,79 @@ describe('animatorGraph', () => {
expect(edges[0]).toMatchObject({ id: 'Idle->Run#0', from: 'Idle', to: 'Run', index: 0 });
});
});
+
+// ---------------------------------------------------------------------------
+// Layers
+// ---------------------------------------------------------------------------
+
+describe('editing a controller with layers', () => {
+ const base = (): AnimatorControllerDef => ({
+ version: ANIMATOR_FORMAT_VERSION,
+ parameters: [],
+ states: [{ name: 'Idle', transitions: [] }],
+ initialState: 'Idle',
+ });
+
+ it('adds a layer with a machine of its own', () => {
+ const def = addAnimatorLayer(base(), 'arms');
+ expect(animatorLayerCount(def)).toBe(2);
+ expect(def.layers![0]!.states).toHaveLength(1);
+ expect(def.layers![0]!.initialState).toBe('Idle');
+ });
+
+ it('refuses a second layer by the same name', () => {
+ const once = addAnimatorLayer(base(), 'arms');
+ expect(addAnimatorLayer(once, 'arms')).toBe(once);
+ });
+
+ it('edits the layer the op was given and no other', () => {
+ // The base and the layer both hold a state called Idle. An op that
+ // reached the wrong one would still "work", which is why this asserts on
+ // both sides rather than on the one it edited.
+ let def = addAnimatorLayer(base(), 'arms');
+ def = addState(def, 'Wave', 0, 0, 1);
+ expect(def.layers![0]!.states.map(s => s.name)).toEqual(['Idle', 'Wave']);
+ expect(def.states.map(s => s.name)).toEqual(['Idle']);
+
+ def = addState(def, 'Run', 0, 0);
+ expect(def.states.map(s => s.name)).toEqual(['Idle', 'Run']);
+ expect(def.layers![0]!.states.map(s => s.name)).toEqual(['Idle', 'Wave']);
+ });
+
+ it('renames within one layer, rewiring that layer’s any-state edges', () => {
+ let def = addAnimatorLayer(base(), 'arms');
+ def = updateAnimatorLayer(def, 1, {});
+ def = { ...def, layers: [{ ...def.layers![0]!, anyStateTransitions: [{ to: 'Idle', conditions: [] }] }] };
+ def = renameState(def, 'Idle', 'Calm', 1);
+
+ expect(def.layers![0]!.initialState).toBe('Calm');
+ expect(def.layers![0]!.anyStateTransitions![0]!.to).toBe('Calm');
+ expect(def.initialState).toBe('Idle');
+ });
+
+ it('sets what a layer IS, and refuses to on the base', () => {
+ let def = addAnimatorLayer(base(), 'arms');
+ def = updateAnimatorLayer(def, 1, { weight: 0.4, blend: 'additive', mask: { paths: ['chest'] } });
+ expect(def.layers![0]!.weight).toBe(0.4);
+ expect(def.layers![0]!.blend).toBe('additive');
+ expect(def.layers![0]!.mask!.paths).toEqual(['chest']);
+
+ // The base layer has no weight to set — it is what the others modify.
+ expect(updateAnimatorLayer(def, 0, { weight: 0.5 })).toBe(def);
+ expect(removeAnimatorLayer(def, 0)).toBe(def);
+ });
+
+ it('reorders layers, order being what a stack means', () => {
+ let def = addAnimatorLayer(addAnimatorLayer(base(), 'arms'), 'aim');
+ expect(def.layers!.map(l => l.name)).toEqual(['arms', 'aim']);
+ def = moveAnimatorLayer(def, 2, 1);
+ expect(def.layers!.map(l => l.name)).toEqual(['aim', 'arms']);
+ });
+
+ it('removes a layer without disturbing the base', () => {
+ let def = addAnimatorLayer(base(), 'arms');
+ def = removeAnimatorLayer(def, 1);
+ expect(animatorLayerCount(def)).toBe(1);
+ expect(def.states.map(s => s.name)).toEqual(['Idle']);
+ });
+});