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: add Animation guide (sprite / tween / animator state machine)
yhh53ab2d590f90
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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 动画。