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.

docs(animation): what a clip can say, and what it may ask to move

esenginea157b68a9fab
diff --git a/desktop b/desktop
index 11f1b6d1b..c6c177bf1 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 11f1b6d1b4f39b70836721d47df66b70720dfb95
+Subproject commit c6c177bf1d23bc9fc8f877def7503e7de13df799
diff --git a/docs/astro/src/content/docs/animation/overview.mdx b/docs/astro/src/content/docs/animation/overview.mdx
index 7e0e94e3a..e3ca124c8 100644
--- a/docs/astro/src/content/docs/animation/overview.mdx
+++ b/docs/astro/src/content/docs/animation/overview.mdx
@@ -534,6 +534,100 @@ evaluateAnimatorPath(player, 'locomotion/idle', { speed: 3 }, new Set());
| `evaluateAnimatorPath(def, path, params, triggers, clipFinished?)` | One pure evaluation step over a path → `{ nextPath, consumedTriggers }`. |
| `STATE_PATH_SEP` | The path separator, `'/'`. |
+### Animation events
+
+A clip can name the moments inside it. A `customEvent` track in an
+`.estimeline` carries `{ time, name, payload }`, and the animator reports each
+one on the frame whose step **crossed** it — never the frame that landed on it,
+which a fixed timestep does not do. They arrive on the `AnimatorEvent` bus:
+
+```typescript
+import {
+ defineSystem, EventReader, GetWorld, Res,
+ AnimatorEvent, Particle, resolveChildEntity,
+} from 'esengine';
+
+const footsteps = defineSystem(
+ [EventReader(AnimatorEvent), GetWorld(), Res(Particle)],
+ (events, world, particles) => {
+ for (const event of events) {
+ if (event.name !== 'footstep') continue;
+ const dust = resolveChildEntity(world, event.entity, 'FootDust');
+ if (dust !== null) particles.play(dust);
+ }
+ },
+ { name: 'FootstepSystem' },
+);
+```
+
+| Field | Description |
+|---|---|
+| `entity` | The animated entity — who this happened to. |
+| `name` | The event's name as the clip declared it. |
+| `value` | Its numeric payload (`payload.value`); `0` when the clip states none. |
+| `text` | Its string payload (`payload.text`); empty when the clip states none. |
+
+What the animator promises:
+
+- An event fires on the interval `(previous, current]` a step covered, so a long
+ frame never steps over one and never reports one twice.
+- A loop wrap is *two* intervals — the tail of the lap, then the head of the next
+ — so an event near either end fires exactly once per lap.
+- Several events in one step fire in the order the clip declares them.
+- During a crossfade only the state being **entered** reports events. The one
+ fading out keeps its clock and says nothing, so an attack cancelled into a
+ dodge does not go on landing its hit.
+
+The animator calls into no particle system, no audio and no gameplay: it states
+the event, and whoever owns those things answers it.
+
+### Root motion
+
+A clip that animates the entity it is played **on** is not posing a skeleton —
+it is saying where the character travels. A state declares that:
+
+```json
+{
+ "name": "Dodge",
+ "motion": { "kind": "timeline", "clip": "dodge.estimeline", "loop": false },
+ "rootMotion": true,
+ "transitions": [{ "to": "Idle", "conditions": [], "hasExitTime": true }]
+}
+```
+
+The animator then keeps that root track's `position` and `rotation` out of the
+pose — the clip never moves the entity — and publishes what it asked for on the
+entity's `AnimatorRootMotion` component:
+
+| Field | Description |
+|---|---|
+| `enabled` | Authoring: whether the request is published at all. |
+| `active` | A state declaring root motion is driving this frame. |
+| `deltaPosition` | The displacement asked for, in world space. |
+| `deltaRotation` | The turn asked for, in the character's own frame. |
+| `deltaTime` | The seconds the two deltas cover. |
+
+<Aside type="caution">
+ The deltas are a **request**, not a result. Hand them to whatever moves the
+ character and let the world answer — `ThirdPersonController` does exactly
+ that: while `active` it ignores the stick and asks `CharacterController3D` for
+ `deltaPosition / deltaTime`, so a dodge into a wall asks for the whole
+ distance and travels none of it. Writing `deltaPosition` onto a `Transform`
+ puts the animator in charge of movement, and an animator in charge of movement
+ walks through walls.
+</Aside>
+
+`deltaTime` comes with the deltas because the animator runs on the frame clock
+while a character controller usually steps on a fixed one: form a rate from the
+pair. A consumer that simply added the displacement would move twice on a frame
+with two fixed steps and not at all on a frame with none.
+
+Read `active` rather than "is the delta non-zero" — a dodge has a still moment in
+the middle, and the stick must not take it back there. Without an
+`AnimatorRootMotion` component the state still refuses to pose the character's
+own transform; the clip simply plays on the spot.
+
+
## Choosing the right tool
<Aside type="tip">
diff --git a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx
index 18af005ad..bf853c059 100644
--- a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx
@@ -495,6 +495,92 @@ evaluateAnimatorPath(player, 'locomotion/idle', { speed: 3 }, new Set());
| `evaluateAnimatorPath(def, path, params, triggers, clipFinished?)` | 对路径做一步纯求值 → `{ nextPath, consumedTriggers }`。 |
| `STATE_PATH_SEP` | 路径分隔符,`'/'`。 |
+### 动画事件
+
+剪辑可以给自己内部的时刻命名。`.estimeline` 里的 `customEvent` 轨道携带
+`{ time, name, payload }`,动画器在**跨过**该时刻的那一帧报告它——而不是正好落在
+它上面的那一帧,固定步长根本不会正好落上去。事件走 `AnimatorEvent` 总线:
+
+```typescript
+import {
+ defineSystem, EventReader, GetWorld, Res,
+ AnimatorEvent, Particle, resolveChildEntity,
+} from 'esengine';
+
+const footsteps = defineSystem(
+ [EventReader(AnimatorEvent), GetWorld(), Res(Particle)],
+ (events, world, particles) => {
+ for (const event of events) {
+ if (event.name !== 'footstep') continue;
+ const dust = resolveChildEntity(world, event.entity, 'FootDust');
+ if (dust !== null) particles.play(dust);
+ }
+ },
+ { name: 'FootstepSystem' },
+);
+```
+
+| 字段 | 说明 |
+|---|---|
+| `entity` | 被播放动画的实体——事情发生在谁身上。 |
+| `name` | 剪辑声明的事件名。 |
+| `value` | 数值负载(`payload.value`);剪辑没写时为 `0`。 |
+| `text` | 字符串负载(`payload.text`);剪辑没写时为空串。 |
+
+动画器给出的承诺:
+
+- 事件按一步覆盖的区间 `(上一时刻, 当前时刻]` 触发,所以再长的一帧也不会跨过去
+ 漏掉,也不会为同一次跨越报两次。
+- 循环回绕算**两个**区间——本圈的尾巴,再加下一圈的开头——所以贴着两端的事件每圈
+ 正好触发一次。
+- 一步内跨过多个事件,按剪辑声明的顺序触发。
+- 交叉淡化期间只有**正在进入**的状态报告事件。正在淡出的那个仍在走时钟,但什么都
+ 不说——所以被闪避打断的攻击不会继续把伤害判定打出来。
+
+动画器不调用任何粒子、音频或玩法代码:它只陈述事件,由拥有这些东西的系统来回应。
+
+### 根运动
+
+一段动画如果动的是它被播放在其上的那个实体,它就不是在摆骨架的姿势——它是在说角色
+往哪走。这件事由状态声明:
+
+```json
+{
+ "name": "Dodge",
+ "motion": { "kind": "timeline", "clip": "dodge.estimeline", "loop": false },
+ "rootMotion": true,
+ "transitions": [{ "to": "Idle", "conditions": [], "hasExitTime": true }]
+}
+```
+
+动画器于是把该根轨道的 `position` 与 `rotation` 排除在姿势之外——剪辑永远不会自己
+移动实体——并把它请求的位移发布到实体的 `AnimatorRootMotion` 组件上:
+
+| 字段 | 说明 |
+|---|---|
+| `enabled` | 创作项:是否发布这个请求。 |
+| `active` | 本帧是否有声明了根运动的状态在驱动角色。 |
+| `deltaPosition` | 请求的位移,世界空间。 |
+| `deltaRotation` | 请求的转向,角色自身坐标系。 |
+| `deltaTime` | 这两个增量覆盖的秒数。 |
+
+<Aside type="caution">
+ 这些增量是**请求**,不是结果。把它交给真正移动角色的东西,让世界来回答——
+ `ThirdPersonController` 正是这么做的:`active` 期间它忽略摇杆,向
+ `CharacterController3D` 请求 `deltaPosition / deltaTime`,所以撞墙的闪避会请求
+ 整段距离而一步也走不了。把 `deltaPosition` 直接写进 `Transform`,等于让动画器
+ 接管移动,而接管了移动的动画器会穿墙。
+</Aside>
+
+`deltaTime` 与增量一起给出,是因为动画器跑在帧时钟上,而角色控制器通常跑在固定步长
+上:请用这一对算出速率。直接把位移加上去的消费者,会在有两个固定步的帧里走两倍,在
+没有固定步的帧里一步不走。
+
+判断依据请读 `active`,而不是「增量是否非零」——闪避中间有静止的一瞬,摇杆不能在那
+一刻把控制权抢回去。实体上没有 `AnimatorRootMotion` 组件时,该状态依然拒绝去摆角色
+自身的 transform,剪辑只是原地播放。
+
+
## 如何选择
<Aside type="tip">
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index 60ec26fb5..2e02d9cd4 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -133,6 +133,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
// ── Animation ──────────────────────────────────────────────────────────────
Animator: { category: 'animation', summary: 'Runs an animator controller — states, transitions and blend trees — over the entity.', doc: 'animation/overview', anchor: 'animator-state-machine', anchorZh: '动画状态机' },
+ AnimatorRootMotion: { category: 'animation', summary: 'Publishes how far the active animation asks the character to move, for gameplay to hand to a character controller — a request, never a result.', doc: 'animation/overview', anchor: 'root-motion', anchorZh: '根运动' },
SpriteAnimator: { category: 'animation', summary: 'Plays a flipbook clip by swapping the sprite frame, with speed, looping and frame events.', doc: 'animation/overview', anchor: 'sprite-animation', anchorZh: '精灵动画' },
TimelinePlayer: { category: 'animation', summary: 'Plays a timeline asset — keyframed tracks across many entities — with wrap modes and playback control.', doc: 'animation/timeline', anchor: 'attach-a-timeline', anchorZh: '附加时间轴' },
SpineAnimation: { category: 'animation', summary: 'A Spine skeleton: its skeleton and atlas assets, current animation, skin and mix settings.', doc: 'animation/spine', anchor: 'the-spineanimation-component', anchorZh: 'spineanimation-组件' },
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 1e8a72283..d6683b3da 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -23,6 +23,55 @@
}
]
},
+ {
+ "name": "AnimatorRootMotion",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true"
+ },
+ {
+ "key": "active",
+ "type": "boolean",
+ "default": "false",
+ "readonly": true,
+ "advanced": true
+ },
+ {
+ "key": "deltaPosition",
+ "type": "Vec3",
+ "default": "(0, 0, 0)",
+ "readonly": true,
+ "advanced": true
+ },
+ {
+ "key": "deltaRotation",
+ "type": "Quat",
+ "default": "(0, 0, 0, 1)",
+ "readonly": true,
+ "advanced": true
+ },
+ {
+ "key": "deltaTime",
+ "type": "number",
+ "default": "0",
+ "readonly": true,
+ "advanced": true
+ }
+ ],
+ "animatable": [
+ "deltaPosition.x",
+ "deltaPosition.y",
+ "deltaPosition.z",
+ "deltaRotation.w",
+ "deltaRotation.x",
+ "deltaRotation.y",
+ "deltaRotation.z",
+ "deltaTime"
+ ]
+ },
{
"name": "AudioListener",
"source": "ts",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 652094030..07fb4b239 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -12548,7 +12548,7 @@ ServicesPlugin
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
```
## setBtNodeField — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 2a32d11a7..c18cad771 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -12791,7 +12791,7 @@ ServicesPlugin
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
```
## setBtNodeField — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 2f5338b9e..de586be8b 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -12553,7 +12553,7 @@ ServicesPlugin
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
```
## setBtNodeField — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 249859e28..3e97bb7b0 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -12810,7 +12810,7 @@ ServicesPlugin
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
```
## setBtNodeField — function @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 5657c03bf..6c90b78dc 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -12576,7 +12576,7 @@ ServicesPlugin
## setAnimatorStateProps — function @experimental
```
-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; }): AnimatorControllerDef
+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }): AnimatorControllerDef
```
## setBtNodeField — function @experimental
diff --git a/sdk/src/animation/animatorGraph.ts b/sdk/src/animation/animatorGraph.ts
index 15d2f9269..9296bed43 100644
--- a/sdk/src/animation/animatorGraph.ts
+++ b/sdk/src/animation/animatorGraph.ts
@@ -117,7 +117,10 @@ export function setStateMotion(
};
}
-export function setStateProps(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean }): AnimatorControllerDef {
+export function setStateProps(
+ def: AnimatorControllerDef, name: string,
+ patch: { speed?: number; loop?: boolean; rootMotion?: boolean },
+): AnimatorControllerDef {
return { ...def, states: def.states.map((s) => (s.name === name ? { ...s, ...patch } : s)) };
}