docs: today's creation surfaces reach the guides, EN + zh

Animation: the Flipbook editor workflow (Create Sprite Animation,
grid slicing, frame strip, Create Animated Sprite, edit-mode viewport
preview), the SpriteAnimator finished flag, and code-free state
switching via the spriteAnim.* built-ins. AI: the new optional action
argument and the four spriteAnim built-ins. Audio: bus effect chains,
sidechain ducking, the Audio Mixer panel + project config, and audio
import settings. Build & export: the Compress Audio package option.

Author: esengine

docs/astro/src/content/docs/guides/ai.mdx

@@ -107,6 +107,16 @@ the agent entity (the same channel your code and the editor use):
 | `timeline.play` | action | Raise the agent's [`TimelinePlayer`](/docs/guides/timeline/) play flag. On a finished clip this replays it from the top. |
 | `timeline.pause` | action | Lower the play flag (resume with `timeline.play`). |
 | `timeline.finished` | condition | True once the clip has completed (a `once` clip that ran to its end) and is not playing. |
+| `spriteAnim.play` | action | Play the agent's sprite flipbook; the **argument** switches to that clip. |
+| `spriteAnim.restart` | action | Rewind the flipbook to frame 0 and play (argument switches clip). |
+| `spriteAnim.stop` | action | Pause the flipbook. |
+| `spriteAnim.finished` | condition | True once a one-shot sprite clip has finished. |
+
+Actions can carry an optional **string argument** — set it next to the action
+name in the FSM state inspector (or on a BT action node). Built-ins use it for
+data the component can't carry per-state, like which clip `spriteAnim.play`
+should switch to; your own registered actions receive it as their third
+parameter: `(ctx, blackboard, arg) => …`.
 
 Together they make a **code-free cutscene state**: entering the state starts the
 clip, and its completion drives the transition out.

docs/astro/src/content/docs/guides/animation.mdx

@@ -38,6 +38,7 @@ const setClip = defineSystem([Query(Mut(SpriteAnimator))], (q) => {
 | `playing` | boolean | `true` | Whether playback is advancing. |
 | `loop` | boolean | `true` | Loop the clip vs. hold the last frame. |
 | `enabled` | boolean | `true` | Disable to freeze the animator. |
+| `finished` | boolean | `false` | Read-only: latched when a one-shot clip completes. Raising `playing` on a finished animator replays from frame 0. |
 | `currentFrame` | number | `0` | Read-only: the frame index being shown. |
 | `frameTimer` | number | `0` | Read-only: time accumulated on the current frame. |
 
@@ -65,6 +66,43 @@ const jump = defineSystem([Query(Mut(SpriteAnimator)), Res(SpriteAnimation)], (q
 Clips can carry **frame events** (`SpriteAnimEvent`) that fire when playback
 reaches a frame — use them for footstep sounds or hit frames.
 
+### Authoring clips in the editor
+
+Clips are `.esanim` assets you author visually — no JSON by hand:
+
+1. **Right-click a texture** in the Content Browser and choose **Create Sprite
+   Animation**. The Flipbook editor opens with the sheet under a slicing grid
+   (the cell size is guessed from the image; adjust cell width/height, margin,
+   and spacing in the toolbar).
+2. **Click or drag across cells** to append frames. The frame strip below shows
+   each frame's thumbnail with an editable duration (ms; empty = `1000 / FPS`),
+   drag to reorder, and a live looping preview.
+3. **Save**, then **right-click the `.esanim` → Create Animated Sprite** (or
+   drag it into the viewport). You get a `Sprite` + `SpriteAnimator` entity
+   posed at frame 0 — it plays in Play mode with zero code.
+
+Selecting an animated sprite loops its flipbook **in the viewport while
+editing** (toggle with the Preview FX show flag). If the clip is open in the
+Flipbook editor at the same time, frame edits animate live as you make them.
+
+Re-slicing the grid moves every frame consistently — frames reference grid
+cells, not pixel rectangles. Frames that fall outside the current grid are
+flagged red in the strip.
+
+### Driving clips from a state machine — no code
+
+The [FSM/BT built-ins](/docs/guides/ai/) drive flipbooks as data. An action's
+optional **argument** carries the clip, so idle/run/attack switching is pure
+`.esfsm` on the existing state-machine canvas:
+
+| Name | Kind | Description |
+|---|---|---|
+| `spriteAnim.play` | action | Play. With a clip argument, switch to that clip (rewinds to frame 0). Safe on `onUpdate` — same-clip play while playing is a no-op. |
+| `spriteAnim.restart` | action | Unconditional rewind + play (re-trigger a one-shot mid-flight). |
+| `spriteAnim.stop` | action | Pause playback. |
+| `spriteAnim.finished` | condition | True once a one-shot clip completed — `onEnter: spriteAnim.play` + a `spriteAnim.finished` transition is a self-contained attack state. |
+
+
 ## Tweens
 
 The `Tween` resource interpolates a property from one value to another over a

docs/astro/src/content/docs/guides/audio.mdx

@@ -131,6 +131,46 @@ defaulting to `sfx`. Volume setters exist for `setMasterVolume` (a global slider
 and `setMusicVolume` / `setSFXVolume` / `setUIVolume`. The `voice` bus routes sounds
 but has no volume setter — toggle it with `muteBus('voice', …)`.
 
+### Bus effects & ducking
+
+Each bus carries a DSP insert chain, declared as data:
+
+```typescript
+audio.setBusEffects('music', [
+  { type: 'filter', filter: 'lowpass', frequency: 800, q: 1 },   // muffle (pause menu)
+  { type: 'reverb', seconds: 1.5, wet: 0.3 },                     // procedural room tail
+  { type: 'compressor', thresholdDb: -24, ratio: 4 },
+]);
+audio.setBusEffects('music', []);   // clear
+```
+
+Sidechain ducking is a rule, not code — duck music while voice lines play:
+
+```typescript
+audio.setBusDucking('music', { trigger: 'voice', amount: 0.3, attack: 0.05, release: 0.4 });
+audio.setBusDucking('music', null);  // remove
+```
+
+While the `trigger` bus carries signal, the target's duck stage ramps to
+`amount`; on silence it releases back to 1. Ducking is a separate gain stage,
+so it never fights the user's volume setting. On backends without a WebAudio
+graph (WeChat) both APIs degrade to no-ops, like the volume calls.
+
+### The Audio Mixer panel & project config
+
+The **Audio Mixer** bottom-dock panel edits all of this visually — one strip
+per bus with a volume fader, mute, the effect chain, a duck-by rule, and
+custom buses. Edits persist to `project.esproject` (`features.audio`) and
+apply live in the editor; Play and every export boot the identical mix.
+
+### Import settings & cooked audio
+
+Selecting an audio asset shows a decoded waveform with play/seek plus **Import
+Settings**: `Compress` and `Bitrate` control the cook's WAV → MP3 transcode
+(enable **Compress audio** in the Package dialog). Already-compressed formats
+pass through untouched. MP3 has a small encoder delay — turn `Compress` off on
+clips that must loop seamlessly.
+
 ## Spatial audio
 
 Set `AudioSource.spatial = true` and give your listener entity (usually the camera

docs/astro/src/content/docs/guides/build-export.mdx

@@ -99,6 +99,9 @@ module for each engine feature the game uses (`physics-wechat`, `spine-wechat`,
 
 The Package dialog also drives what the **cook** does to your assets:
 
+- **Compress audio** — re-encode WAV sources to MP3 at cook (per-asset Import
+  Settings can opt a clip out or pick a bitrate; other audio formats pass
+  through unchanged).
 - **Compress textures** — encode PNGs to GPU-ready **KTX2** (Basis Universal), which
   the runtime transcodes to the best format each device supports (ASTC → ETC2 → S3TC,
   falling back to RGBA8). Smaller downloads and less VRAM; leave off to ship raw PNGs.

docs/astro/src/content/docs/zh-cn/guides/ai.mdx

@@ -95,6 +95,14 @@ export enum Status { Success = 'success', Failure = 'failure', Running = 'runnin
 | `timeline.play` | 动作 | 拉起该实体 [`TimelinePlayer`](/docs/zh-cn/guides/timeline/) 的播放旗标。对已播完的片段,从头重播。 |
 | `timeline.pause` | 动作 | 放下播放旗标(用 `timeline.play` 恢复)。 |
 | `timeline.finished` | 条件 | 片段已完成(`once` 片段播到末尾)且未在播放时为真。 |
+| `spriteAnim.play` | 动作 | 播放代理实体的精灵翻页动画;**参数**可切换到指定剪辑。 |
+| `spriteAnim.restart` | 动作 | 回卷到第 0 帧并播放(参数可切换剪辑)。 |
+| `spriteAnim.stop` | 动作 | 暂停翻页动画。 |
+| `spriteAnim.finished` | 条件 | 一次性精灵剪辑播完后为真。 |
+
+动作可携带一个可选**字符串参数**——在 FSM 状态检查器的动作名旁(或 BT 动作节点上)填写。
+内置动作用它承载组件无法按状态携带的数据,比如 `spriteAnim.play` 要切换到哪个剪辑;
+你自己注册的动作在第三个参数收到它:`(ctx, blackboard, arg) => …`。
 
 三者组合出一个**零代码的过场状态**:进入状态即播放片段,片段播完即驱动转移:
 

docs/astro/src/content/docs/zh-cn/guides/animation.mdx

@@ -37,6 +37,7 @@ const setClip = defineSystem([Query(Mut(SpriteAnimator))], (q) => {
 | `playing` | boolean | `true` | 播放是否在推进。 |
 | `loop` | boolean | `true` | 循环片段 vs 停在最后一帧。 |
 | `enabled` | boolean | `true` | 关掉即冻结动画器。 |
+| `finished` | boolean | `false` | 只读:一次性片段播完时锁存。在 finished 状态抬起 `playing` 会从第 0 帧重播。 |
 | `currentFrame` | number | `0` | 只读:正在显示的帧索引。 |
 | `frameTimer` | number | `0` | 只读:当前帧已累积的时间。 |
 
@@ -62,6 +63,36 @@ const jump = defineSystem([Query(Mut(SpriteAnimator)), Res(SpriteAnimation)], (q
 
 片段可以携带**帧事件**(`SpriteAnimEvent`),播放到某帧时触发——用于脚步声或命中帧。
 
+### 在编辑器中创作剪辑
+
+剪辑是 `.esanim` 资产,全程可视化创作——不用手写 JSON:
+
+1. 在内容浏览器中**右键纹理**,选择**创建精灵动画**。Flipbook 编辑器打开,
+   精灵表上覆盖切片网格(格子尺寸按图片猜测;在工具栏调整格宽/格高/边距/间距)。
+2. **点击或拖选格子**追加帧。下方帧条显示每帧缩略图与可编辑时长
+   (毫秒;留空 = `1000 / 帧率`),可拖拽重排,并带实时循环预览。
+3. **保存**,然后**右键 `.esanim` → 创建动画精灵**(或直接拖进视口)。
+   得到一个定格在第 0 帧的 `Sprite` + `SpriteAnimator` 实体——进 Play 零代码播放。
+
+选中动画精灵时,翻页动画**在编辑态视口中循环播放**(用 Preview FX 显示开关控制)。
+若该剪辑同时在 Flipbook 编辑器中打开,改帧即时反映在视口里。
+
+重新切片时所有帧一致跟随——帧引用的是网格格子,不是像素矩形。
+超出当前网格的帧会在帧条中标红。
+
+### 用状态机驱动剪辑——零代码
+
+[FSM/BT 内置](/docs/zh-cn/guides/ai/)以数据驱动翻页动画。动作的可选**参数**
+携带剪辑,所以 idle/run/attack 切换是纯 `.esfsm` 数据,画在现有状态机画布上:
+
+| 名称 | 类型 | 说明 |
+|---|---|---|
+| `spriteAnim.play` | 动作 | 播放。带剪辑参数时切换到该剪辑(回卷到第 0 帧)。可安全放在 `onUpdate`——同剪辑播放中为空操作。 |
+| `spriteAnim.restart` | 动作 | 无条件回卷 + 播放(中途重触发一次性动画)。 |
+| `spriteAnim.stop` | 动作 | 暂停播放。 |
+| `spriteAnim.finished` | 条件 | 一次性剪辑播完后为真——`onEnter: spriteAnim.play` + `spriteAnim.finished` 过渡即是自包含的攻击状态。 |
+
+
 ## 补间(Tween)
 
 `Tween` 资源在一段时长内把属性从一个值插值到另一个值。`to(entity, target, from, to,

docs/astro/src/content/docs/zh-cn/guides/audio.mdx

@@ -124,6 +124,42 @@ audio.muteBus('music', true);
 `setMasterVolume`(全局滑条)和 `setMusicVolume` / `setSFXVolume` / `setUIVolume`。`voice`
 总线能路由声音但没有音量设置器——用 `muteBus('voice', …)` 开关它。
 
+### 总线效果与自动闪避(ducking)
+
+每条总线携带一条 DSP 插入链,以数据声明:
+
+```typescript
+audio.setBusEffects('music', [
+  { type: 'filter', filter: 'lowpass', frequency: 800, q: 1 },   // 闷化(暂停菜单)
+  { type: 'reverb', seconds: 1.5, wet: 0.3 },                     // 程序化房间混响
+  { type: 'compressor', thresholdDb: -24, ratio: 4 },
+]);
+audio.setBusEffects('music', []);   // 清空
+```
+
+旁链闪避是一条规则,不是代码——语音播放时自动压低音乐:
+
+```typescript
+audio.setBusDucking('music', { trigger: 'voice', amount: 0.3, attack: 0.05, release: 0.4 });
+audio.setBusDucking('music', null);  // 移除
+```
+
+`trigger` 总线有信号时,目标总线的闪避级压到 `amount`;静默后按 `release` 恢复到 1。
+闪避是独立的增益级,不会与用户音量设置打架。无 WebAudio 图的后端(微信)上,
+两个 API 与音量调用一样优雅降级为空操作。
+
+### 音频混音器面板与项目配置
+
+底部停靠的**音频混音器**面板可视化编辑以上一切——每总线一条 strip:音量推子、
+静音、效果链、闪避规则、自定义总线。编辑持久化到 `project.esproject`
+(`features.audio`)并在编辑器中即时生效;Play 与所有导出以同一套混音启动。
+
+### 导入设置与打包音频
+
+选中音频资产会显示解码波形(可播放/点击跳转)和**导入设置**:`Compress` 与
+`Bitrate` 控制打包时的 WAV → MP3 转码(在打包对话框勾选**压缩音频**)。
+已压缩格式原样通过。MP3 有少量编码器延迟——需要无缝循环的素材请关闭 `Compress`。
+
 ## 空间音频
 
 设 `AudioSource.spatial = true`,并给监听实体(通常是相机或玩家)加一个启用的 `AudioListener`。

docs/astro/src/content/docs/zh-cn/guides/build-export.mdx

@@ -85,6 +85,8 @@ node build-tools/cli.js build -t playable
 
 打包对话框还控制**烘焙**如何处理你的资产:
 
+- **压缩音频** —— 打包时把 WAV 源重编码为 MP3(可在资产的导入设置中单独关闭或选码率;
+  其他音频格式原样通过)。
 - **压缩纹理** —— 把 PNG 编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
   设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。下载更小、显存更省;关掉则
   发布原始 PNG。