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: deepen the Animation guide (sprite / tweens+sequencing / state machine)
yhhbaeb91004a55
diff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/guides/animation.mdxindex f1981bd48..597aaa028 100644--- a/docs/astro/src/content/docs/guides/animation.mdx+++ b/docs/astro/src/content/docs/guides/animation.mdx@@ -1,66 +1,118 @@---title: Animation-description: Sprite sheets, tweens, and animator state machines.+description: Sprite sheets, tweens (with sequencing), and animator state machines.----Estella has three ways to animate, each suited to a different job.+import { Aside } from '@astrojs/starlight/components';++Estella has three animation systems, each for a different job: **sprite+animation** for frame-by-frame art, **tweens** for interpolating properties, and+the **animator state machine** for character animation driven by parameters.## Sprite animation-The `SpriteAnimator` component plays sprite-sheet clips. Switch the clip by-writing the component (query it with `Mut`):+The `SpriteAnimator` component plays sprite-sheet clips. Its fields are `clip`+(the current clip name), `speed`, `playing`, `loop`, plus the read-only+`currentFrame` and `frameTimer`. Switch clips by writing the component:```typescriptimport { defineSystem, Query, Mut, SpriteAnimator } from 'esengine';const setClip = defineSystem([Query(Mut(SpriteAnimator))], (q) => {for (const [entity, animator] of q) {- animator.clip = 'walk'; // switch to another clip- animator.currentFrame = 0; // restart from the first frame- animator.frameTimer = 0;+ animator.clip = 'walk';+ animator.speed = 1.5;+ animator.playing = true;}});```+For finer control, the `SpriteAnimation` resource can jump to a specific frame or+a named label, and register clips at runtime:++```typescript+import { defineSystem, Query, Mut, Res, SpriteAnimator, SpriteAnimation } from 'esengine';++const jump = defineSystem([Query(Mut(SpriteAnimator)), Res(SpriteAnimation)], (q, sprites) => {+ for (const [entity, animator] of q) {+ sprites.gotoFrame(animator, 0, true); // frame index, and play+ sprites.gotoLabel(animator, 'attack', true);+ }+});+```++Clips can carry **frame events** (`SpriteAnimEvent`) that fire when playback+reaches a frame — use them for footstep sounds or hit frames.+## Tweens-The `Tween` resource interpolates one property from a start value to an end value-over a duration:+The `Tween` resource interpolates a property from one value to another over a+duration:```typescript-import { defineSystem, Query, Res, Transform, Tween, TweenTarget, EasingType, LoopMode } from 'esengine';+import { defineSystem, Res, Tween, TweenTarget, EasingType, LoopMode } from 'esengine';-const animate = defineSystem([Query(Transform), Res(Tween)], (q, tween) => {- for (const [entity] of q) {- tween.to(entity, TweenTarget.PositionX, 0, 200, 1.0, {- easing: EasingType.EaseInOutQuad,- loop: LoopMode.PingPong,- });- }+const animate = defineSystem([Res(Tween)], (tween) => {+ tween.to(entity, TweenTarget.PositionX, 0, 200, 1.0, {+ easing: EasingType.EaseInOutQuad,+ delay: 0.2,+ loop: LoopMode.PingPong,+ loopCount: 3, // -1 = forever+ });});```-`TweenTarget` covers position, scale, rotation, and color channels — e.g.-`PositionX`, `ScaleX`, `RotationZ`, `ColorR`. `EasingType` has the usual curves-(`Linear`, `EaseInOutQuad`, …), and `LoopMode` includes `PingPong`.+**Targets** (`TweenTarget`): `PositionX` / `PositionY` / `PositionZ`, `ScaleX` /+`ScaleY`, `RotationZ`, `ColorR` / `ColorG` / `ColorB` / `ColorA`, `SizeX` /+`SizeY`, and `CameraOrthoSize`. `EasingType` has the usual curves, and a handle+can use a custom cubic-bezier via `.bezier(p1x, p1y, p2x, p2y)`.++### Sequencing and control++Compose tweens, and cancel or pause them:++```typescript+// Chain: run one after another.+tween.to(e, TweenTarget.ScaleX, 1, 1.4, 0.15).then(+ tween.to(e, TweenTarget.ScaleX, 1.4, 1, 0.15)+);++tween.parallel([...]); // run several at once (a group)+tween.sequence([...]); // run in order (factories)+tween.delay(0.5); // a timed gap++tween.cancel(handle); // stop one+tween.cancelAll(entity); // stop everything on an entity+```++`tween.value(...)` tweens a plain number (not a component target) — for driving+custom logic through a callback.## Animator state machineFor character animation, an animator controller (authored in the editor) holds-states, transitions, and 1D blend trees driven by parameters. At runtime you set-those parameters through `Res(AnimatorController)`:+states, transitions, and 1D blend trees driven by **parameters**. At runtime you+set the parameters through `Res(AnimatorController)`; the controller resolves the+current state, clip, and blend:```typescriptimport { defineSystem, Query, Res, SpriteAnimator, AnimatorController } from 'esengine';const drive = defineSystem([Query(SpriteAnimator), Res(AnimatorController)], (q, animator) => {for (const [entity] of q) {- animator.setFloat(entity, 'speed', 4.2);+ animator.setFloat(entity, 'speed', 4.2); // drives a 1D blend / transitionanimator.setBool(entity, 'grounded', true);- animator.setTrigger(entity, 'jump');+ animator.setTrigger(entity, 'jump'); // one-shot; resetTrigger to clear+ const speed = animator.getFloat(entity, 'speed');}});```-The controller resolves the current state/clip (or blends between clips) from the-parameters, and can drive both sprite and Spine animations.+The controller can drive both sprite and Spine animations, so one state machine+handles a whole character.++<Aside type="tip">+ Reach for **tweens** for one-off UI/juice (a button pop, a fade), **sprite+ animation** for looping art, and the **state machine** when transitions between+ many clips depend on gameplay parameters.+</Aside>diff --git a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx b/docs/astro/src/content/docs/zh-cn/guides/animation.mdxindex 2a05d480c..30028f23a 100644--- a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx@@ -1,64 +1,108 @@---title: 动画-description: 精灵表、补间与动画状态机。+description: 精灵表、补间(含序列)与动画状态机。----Estella 有三种动画方式,各自适合不同场景。+import { Aside } from '@astrojs/starlight/components';++Estella 有三套动画系统,各司其职:**精灵动画**做逐帧美术,**补间**做属性插值,+**动画状态机**做由参数驱动的角色动画。## 精灵动画-`SpriteAnimator` 组件播放精灵表(sprite-sheet)片段。写这个组件即可切换片段(用 `Mut`-查询它):+`SpriteAnimator` 组件播放精灵表片段。它的字段有 `clip`(当前片段名)、`speed`、+`playing`、`loop`,以及只读的 `currentFrame` 和 `frameTimer`。写这个组件即可切换片段:```typescriptimport { defineSystem, Query, Mut, SpriteAnimator } from 'esengine';const setClip = defineSystem([Query(Mut(SpriteAnimator))], (q) => {for (const [entity, animator] of q) {- animator.clip = 'walk'; // 切换到另一个片段- animator.currentFrame = 0; // 从第一帧重新开始- animator.frameTimer = 0;+ animator.clip = 'walk';+ animator.speed = 1.5;+ animator.playing = true;}});```+想更精细,`SpriteAnimation` 资源可以跳到指定帧或命名 label,并在运行时注册片段:++```typescript+import { defineSystem, Query, Mut, Res, SpriteAnimator, SpriteAnimation } from 'esengine';++const jump = defineSystem([Query(Mut(SpriteAnimator)), Res(SpriteAnimation)], (q, sprites) => {+ for (const [entity, animator] of q) {+ sprites.gotoFrame(animator, 0, true); // 帧索引,并播放+ sprites.gotoLabel(animator, 'attack', true);+ }+});+```++片段可以携带**帧事件**(`SpriteAnimEvent`),播放到某帧时触发——用于脚步声或命中帧。+## 补间(Tween)`Tween` 资源在一段时长内把某个属性从起始值插值到结束值:```typescript-import { defineSystem, Query, Res, Transform, Tween, TweenTarget, EasingType, LoopMode } from 'esengine';+import { defineSystem, Res, Tween, TweenTarget, EasingType, LoopMode } from 'esengine';-const animate = defineSystem([Query(Transform), Res(Tween)], (q, tween) => {- for (const [entity] of q) {- tween.to(entity, TweenTarget.PositionX, 0, 200, 1.0, {- easing: EasingType.EaseInOutQuad,- loop: LoopMode.PingPong,- });- }+const animate = defineSystem([Res(Tween)], (tween) => {+ tween.to(entity, TweenTarget.PositionX, 0, 200, 1.0, {+ easing: EasingType.EaseInOutQuad,+ delay: 0.2,+ loop: LoopMode.PingPong,+ loopCount: 3, // -1 = 永远+ });});```-`TweenTarget` 覆盖位置、缩放、旋转和颜色通道——例如 `PositionX`、`ScaleX`、-`RotationZ`、`ColorR`。`EasingType` 提供常见缓动曲线(`Linear`、`EaseInOutQuad` 等),-`LoopMode` 包含 `PingPong`。+**目标**(`TweenTarget`):`PositionX` / `PositionY` / `PositionZ`、`ScaleX` /+`ScaleY`、`RotationZ`、`ColorR` / `ColorG` / `ColorB` / `ColorA`、`SizeX` /+`SizeY`,以及 `CameraOrthoSize`。`EasingType` 提供常见曲线,句柄还可以用+`.bezier(p1x, p1y, p2x, p2y)` 自定义三次贝塞尔。++### 序列与控制++组合补间,并取消或暂停:++```typescript+// 链式:一个接一个。+tween.to(e, TweenTarget.ScaleX, 1, 1.4, 0.15).then(+ tween.to(e, TweenTarget.ScaleX, 1.4, 1, 0.15)+);++tween.parallel([...]); // 同时运行多个(一个组)+tween.sequence([...]); // 按顺序运行(工厂函数)+tween.delay(0.5); // 一段定时间隔++tween.cancel(handle); // 停止一个+tween.cancelAll(entity); // 停止某实体上的全部+```++`tween.value(...)` 补间一个普通数字(而非组件目标)——用于通过回调驱动自定义逻辑。## 动画状态机-对于角色动画,动画控制器(在编辑器里编排)持有状态、过渡,以及由参数驱动的 1D 混合-树(blend tree)。运行时你通过 `Res(AnimatorController)` 设置这些参数:+对于角色动画,动画控制器(在编辑器里编排)持有状态、过渡和由**参数**驱动的 1D 混合树。+运行时你通过 `Res(AnimatorController)` 设置参数;控制器解析出当前状态、片段与混合:```typescriptimport { defineSystem, Query, Res, SpriteAnimator, AnimatorController } from 'esengine';const drive = defineSystem([Query(SpriteAnimator), Res(AnimatorController)], (q, animator) => {for (const [entity] of q) {- animator.setFloat(entity, 'speed', 4.2);+ animator.setFloat(entity, 'speed', 4.2); // 驱动 1D 混合 / 过渡animator.setBool(entity, 'grounded', true);- animator.setTrigger(entity, 'jump');+ animator.setTrigger(entity, 'jump'); // 一次性;用 resetTrigger 清除+ const speed = animator.getFloat(entity, 'speed');}});```-控制器根据这些参数解析出当前状态/片段(或在片段间混合),并且可以同时驱动精灵动画和-Spine 动画。+控制器可以同时驱动精灵动画和 Spine 动画,因此一个状态机就能管一整个角色。++<Aside type="tip">+ 一次性的 UI/手感(按钮弹跳、淡入淡出)用**补间**;循环的美术用**精灵动画**;当多个+ 片段之间的过渡取决于游戏参数时,用**状态机**。+</Aside>