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: add Animation guide (sprite / tween / animator state machine)

yhh53ab2d590f90
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index fb5c675a2..461087455 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -51,6 +51,7 @@ export default defineConfig({
{ label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'guides/input' },
{ label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
{ label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },
+ { label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'guides/animation' },
{ label: 'Tilemaps', translations: { 'zh-CN': '瓦片地图' }, slug: 'guides/tilemap' },
{ label: 'UI', translations: { 'zh-CN': 'UI' }, slug: 'guides/ui' },
{ label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
diff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/guides/animation.mdx
new file mode 100644
index 000000000..50e6234f9
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/animation.mdx
@@ -0,0 +1,62 @@
+---
+title: Animation
+description: Sprite sheets, tweens, and animator state machines.
+---
+
+Estella has three ways to animate, each suited to a different job.
+
+## Sprite animation
+
+The `SpriteAnimator` component plays sprite-sheet clips. Switch the clip by
+writing the component (query it with `Mut`):
+
+```typescript
+import { 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;
+ }
+});
+```
+
+## Tweens
+
+The `Tween` resource interpolates one property from a start value to an end value
+over a duration:
+
+```typescript
+import { defineSystem, Res, Tween, TweenTarget, EasingType, LoopMode } from 'esengine';
+
+const animate = defineSystem([Res(Tween)], (tween) => {
+ tween.to(entity, TweenTarget.PositionX, 0, 200, 1.0, {
+ easing: EasingType.EaseInOutQuad,
+ loop: LoopMode.PingPong,
+ });
+});
+```
+
+`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`.
+
+## Animator state machine
+
+For 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)`:
+
+```typescript
+import { defineSystem, Res, AnimatorController } from 'esengine';
+
+const drive = defineSystem([Res(AnimatorController)], (animator) => {
+ animator.setFloat(entity, 'speed', 4.2);
+ animator.setBool(entity, 'grounded', true);
+ animator.setTrigger(entity, 'jump');
+});
+```
+
+The controller resolves the current state/clip (or blends between clips) from the
+parameters, and can drive both sprite and Spine animations.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
new file mode 100644
index 000000000..af8f57e1d
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
@@ -0,0 +1,60 @@
+---
+title: 动画
+description: 精灵表、补间与动画状态机。
+---
+
+Estella 有三种动画方式,各自适合不同场景。
+
+## 精灵动画
+
+`SpriteAnimator` 组件播放精灵表(sprite-sheet)片段。写这个组件即可切换片段(用 `Mut`
+查询它):
+
+```typescript
+import { 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;
+ }
+});
+```
+
+## 补间(Tween)
+
+`Tween` 资源在一段时长内把某个属性从起始值插值到结束值:
+
+```typescript
+import { defineSystem, Res, Tween, TweenTarget, EasingType, LoopMode } from 'esengine';
+
+const animate = defineSystem([Res(Tween)], (tween) => {
+ tween.to(entity, TweenTarget.PositionX, 0, 200, 1.0, {
+ easing: EasingType.EaseInOutQuad,
+ loop: LoopMode.PingPong,
+ });
+});
+```
+
+`TweenTarget` 覆盖位置、缩放、旋转和颜色通道——例如 `PositionX`、`ScaleX`、
+`RotationZ`、`ColorR`。`EasingType` 提供常见缓动曲线(`Linear`、`EaseInOutQuad` 等),
+`LoopMode` 包含 `PingPong`。
+
+## 动画状态机
+
+对于角色动画,动画控制器(在编辑器里编排)持有状态、过渡,以及由参数驱动的 1D 混合
+树(blend tree)。运行时你通过 `Res(AnimatorController)` 设置这些参数:
+
+```typescript
+import { defineSystem, Res, AnimatorController } from 'esengine';
+
+const drive = defineSystem([Res(AnimatorController)], (animator) => {
+ animator.setFloat(entity, 'speed', 4.2);
+ animator.setBool(entity, 'grounded', true);
+ animator.setTrigger(entity, 'jump');
+});
+```
+
+控制器根据这些参数解析出当前状态/片段(或在片段间混合),并且可以同时驱动精灵动画和
+Spine 动画。