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
docs(animation): what a clip can say, and what it may ask to move
esenginea157b68a9fab
diff --git a/desktop b/desktopindex 11f1b6d1b..c6c177bf1 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 11f1b6d1b4f39b70836721d47df66b70720dfb95+Subproject commit c6c177bf1d23bc9fc8f877def7503e7de13df799diff --git a/docs/astro/src/content/docs/animation/overview.mdx b/docs/astro/src/content/docs/animation/overview.mdxindex 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.mdxindex 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.tsindex 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.jsonindex 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.mdindex 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 @experimentaldiff --git a/sdk/src/animation/animatorGraph.ts b/sdk/src/animation/animatorGraph.tsindex 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)) };}