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: today's creation surfaces reach the guides, EN + zh
esengineb30c8bacffa1
diff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/guides/ai.mdxindex 8b7caafe5..13ba167ec 100644--- a/docs/astro/src/content/docs/guides/ai.mdx+++ b/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 theclip, and its completion drives the transition out.diff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/guides/animation.mdxindex 57db53e44..a2092d308 100644--- a/docs/astro/src/content/docs/guides/animation.mdx+++ b/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)], (qClips can carry **frame events** (`SpriteAnimEvent`) that fire when playbackreaches 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. |++## TweensThe `Tween` resource interpolates a property from one value to another over adiff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdxindex d647731ac..7bfcf8a77 100644--- a/docs/astro/src/content/docs/guides/audio.mdx+++ b/docs/astro/src/content/docs/guides/audio.mdx@@ -131,6 +131,46 @@ defaulting to `sfx`. Volume setters exist for `setMasterVolume` (a global sliderand `setMusicVolume` / `setSFXVolume` / `setUIVolume`. The `voice` bus routes soundsbut 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 audioSet `AudioSource.spatial = true` and give your listener entity (usually the cameradiff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdxindex b6918a08c..75c2aa261 100644--- a/docs/astro/src/content/docs/guides/build-export.mdx+++ b/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), whichthe 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.diff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/guides/ai.mdxindex 676b63bea..786eae496 100644--- a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx+++ b/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) => …`。三者组合出一个**零代码的过场状态**:进入状态即播放片段,片段播完即驱动转移:diff --git a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx b/docs/astro/src/content/docs/zh-cn/guides/animation.mdxindex 1c69974d2..9232f30c4 100644--- a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx+++ b/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,diff --git a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx b/docs/astro/src/content/docs/zh-cn/guides/audio.mdxindex dc0d84139..1dddfa9a0 100644--- a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx+++ b/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`。diff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdxindex 744933134..ce0accf0b 100644--- a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx+++ b/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。