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: rewrite the Audio guide to the complete-reference template
yhh383f1e16df25
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdxindex f32e0f335..61138cffd 100644--- a/docs/astro/src/content/docs/guides/audio.mdx+++ b/docs/astro/src/content/docs/guides/audio.mdx@@ -1,15 +1,29 @@---title: Audio-description: Sound effects, music, playback handles, mixer buses, and spatial audio.+description: The complete guide to audio — sound effects, music, playback handles, the AudioSource/AudioListener components, mixer buses, and spatial audio.---import { Aside } from '@astrojs/starlight/components';-Audio is registered by default. Play one-shot effects and looping music through-the `Audio` resource, control individual sounds with a handle, balance the mix-with buses, and position sounds in the world with spatial audio.+Estella's audio plays one-shot effects and looping music through the `Audio`+resource, controls individual sounds with a handle, balances the mix with a bus+hierarchy, and positions sounds in the world with spatial audio. It runs on the+Web Audio backend in browsers and the native backend on WeChat.-## Sound effects and music+## How it works++`Audio` is a per-App resource, registered by default. Sound files are decoded into+**buffers** that are cached on first use, then played on a **bus** (a named volume+group). Each play returns an `AudioHandle` you can keep to adjust or stop that one+sound. For sounds tied to a place or an object, an `AudioSource` component plays+declaratively and (when `spatial`) attenuates by distance from the `AudioListener`.++<Aside type="note">+ Audio is registered automatically — no plugin to add. Browsers require a user+ gesture before sound can start, so trigger the first playback from a tap or key.+</Aside>++## Sound effects & music```typescriptimport { defineSystem, Res, Audio } from 'esengine';@@ -20,37 +34,79 @@ const play = defineSystem([Res(Audio)], (audio) => {});```-- `playSFX(url, { volume?, pitch?, pan?, priority? })` returns an `AudioHandle`.-- `playBGM(url, { volume?, fadeIn?, crossFade? })` loops and replaces the current- track.-- `stopBGM(fadeOut?)`, `stopAll()`.-- `preload(url)` / `preloadAll(urls)` — load buffers ahead of time so the first- play isn't silent.+`playSFX` fires a one-shot and returns a handle; `playBGM` loops and replaces the+current track, optionally cross-fading. Both auto-preload an uncached clip and play+it once ready.++## `Audio` API reference-## Control a playing sound+| Method | Description |+|---|---|+| `playSFX(url, config?)` | Play a one-shot; returns an `AudioHandle`. Config: `volume`, `pitch`, `pan`, `priority`. |+| `playBGM(url, config?)` | Loop music, replacing the current track. Config: `volume`, `fadeIn`, `crossFade`. |+| `stopBGM(fadeOut?)` | Stop the music, optionally fading out over `fadeOut` seconds. |+| `stopAll()` | Stop every playing sound. |+| `setMasterVolume(v)` | Set the master bus volume (0..1). |+| `setMusicVolume(v)` | Set the `music` bus volume. |+| `setSFXVolume(v)` | Set the `sfx` bus volume. |+| `setUIVolume(v)` | Set the `ui` bus volume. |+| `muteBus(name, muted)` | Mute/unmute a bus by name. |+| `preload(url)` | Decode and cache a clip ahead of time (async). |+| `preloadAll(urls)` | Preload an array of clips (async). |+| `getBufferHandle(url)` | The cached buffer for `url`, or `undefined`. |-`playSFX` returns an `AudioHandle` you keep and drive:+## Controlling a playing sound++`playSFX` returns an `AudioHandle` — keep it to drive that specific sound:```typescriptconst shot = audio.playSFX('assets/laser.wav');shot.setVolume(0.6);shot.setPan(-0.5); // -1 left … +1 right-shot.setPlaybackRate(1.2); // pitch/speed+shot.setPlaybackRate(1.2); // pitch / speed+shot.setLoop(true);shot.pause(); shot.resume(); shot.stop();shot.onEnd = () => { /* the sound finished */ };-// readonly: shot.isPlaying, shot.currentTime, shot.duration```-## Declarative playback: `AudioSource`--Attach an `AudioSource` to an entity to play without code — set `clip`, `bus`-(`"sfx"` by default), `volume`, `pitch`, `loop`, and `playOnAwake`. With-`playOnAwake` + `enabled`, the audio system plays it automatically.+| Member | Type | Description |+|---|---|---|+| `setVolume(v)` | method | Volume, 0..1. |+| `setPan(p)` | method | Stereo pan, `-1` (left) … `+1` (right). |+| `setPlaybackRate(r)` | method | Playback speed / pitch (`1` = normal). |+| `setLoop(l)` | method | Loop the sound. |+| `pause()` / `resume()` / `stop()` | method | Transport control. |+| `onEnd` | callback | Called once when the sound finishes. |+| `isPlaying` | readonly | Whether it's currently playing. |+| `currentTime` | readonly | Playback position in seconds. |+| `duration` | readonly | Total length in seconds. |++## Declarative playback — `AudioSource`++Attach an `AudioSource` to an entity to play without code — ideal for ambience,+looping machines, or a sound anchored to an object. With `playOnAwake` + `enabled`+the audio system starts it automatically.++| Property | Type | Default | Description |+|---|---|---|---|+| `clip` | asset | `''` | Audio asset to play. |+| `bus` | string | `'sfx'` | Mixer bus to route through. |+| `volume` | number | `1` | Volume, 0..1. |+| `pitch` | number | `1` | Playback speed / pitch. |+| `loop` | boolean | `false` | Loop the clip. |+| `playOnAwake` | boolean | `false` | Start automatically when the entity is enabled. |+| `spatial` | boolean | `false` | Attenuate by distance from the listener. |+| `minDistance` | number | `100` | Distance within which volume is full. |+| `maxDistance` | number | `1000` | Distance beyond which the sound is silent. |+| `attenuationModel` | `AttenuationModel` | `Inverse` | Falloff curve — `Linear` / `Inverse` / `Exponential`. |+| `rolloff` | number | `1` | Falloff steepness multiplier. |+| `priority` | number | `0` | Voice priority when the pool is full (higher wins). |+| `enabled` | boolean | `true` | Disable to stop and silence without removing the component. |## Mixer busesThe mixer is hierarchical — `master → { music, sfx, ui, voice }`. Setting a bus-volume scales everything under it:+volume scales everything routed under it:```typescriptaudio.setMasterVolume(0.8);@@ -60,18 +116,56 @@ audio.setUIVolume(0.9);audio.muteBus('music', true);```-Route a sound to a bus with the `bus` option (`playSFX(url, { … })` defaults to-`sfx`) or the `AudioSource.bus` field.+Route a sound to a bus with the `AudioSource.bus` field, or leave `playSFX`+defaulting to `sfx`. Use `master` for a global volume slider, and separate `music`+/ `sfx` / `ui` / `voice` sliders in your options menu.## Spatial audio-Set `AudioSource.spatial = true` and give your camera/player an enabled-`AudioListener`; the source attenuates by distance. Tune it with `minDistance`,-`maxDistance`, and `attenuationModel` (an `AttenuationModel`: inverse / linear /-exponential).+Set `AudioSource.spatial = true` and give your listener entity (usually the camera+or player) an enabled `AudioListener`. The source then attenuates by distance:-<Aside type="caution">- `playSFX` auto-preloads an uncached clip and plays it once ready, so the very- first hit can be silent — call `preload(url)` up front. Browsers also require a- user gesture before audio can start, so kick playback off the first tap/key.-</Aside>+```typescript+import { defineSystem, Commands, Transform, AudioSource, AudioListener,+ AttenuationModel } from 'esengine';++const setupSpatial = defineSystem([Commands()], (cmds) => {+ // A positioned, looping ambience that fades with distance.+ cmds.spawn()+ .insert(Transform, { position: { x: 600, y: 0, z: 0 } })+ .insert(AudioSource, {+ clip: 'assets/campfire.ogg', loop: true, playOnAwake: true,+ spatial: true, minDistance: 80, maxDistance: 900,+ attenuationModel: AttenuationModel.Inverse,+ });++ // The listener (attach to the camera/player).+ cmds.entity(cameraEntity).insert(AudioListener, { enabled: true });+});+```++| `AttenuationModel` | Falloff |+|---|---|+| `Linear` | Straight line from `minDistance` to `maxDistance`. |+| `Inverse` (default) | Natural inverse-distance rolloff. |+| `Exponential` | Steeper exponential rolloff. |++`AudioListener` has a single field, `enabled` (default `true`) — keep exactly one+enabled listener in the scene.++## Best practices++- **Preload** clips you'll play in performance-critical moments (`preload` /+ `preloadAll`) so the first play isn't silent while it decodes.+- **Start on a gesture** — browsers block audio until the first user input.+- **Separate buses** (`music` / `sfx` / `ui` / `voice`) so players can mix them,+ and drive everything from `master`.+- **Cap simultaneous sounds** with `priority` on `AudioSource` so important sounds+ win when the voice pool is full.+- **Use `AudioSource` (declarative)** for world/object sounds and `playSFX` for+ fire-and-forget UI/gameplay one-shots.++## See also++- [Assets](/docs/guides/assets/) — loading and bundling audio clips.+- [Scenes](/docs/guides/scene/) — `AudioSource` state persists with the scene.diff --git a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx b/docs/astro/src/content/docs/zh-cn/guides/audio.mdxindex b1a494002..1aabeeda8 100644--- a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/audio.mdx@@ -1,12 +1,24 @@---title: 音频-description: 音效、音乐、播放句柄、混音总线与空间音频。+description: 音频完整指南——音效、音乐、播放句柄、AudioSource/AudioListener 组件、混音总线与空间音频。---import { Aside } from '@astrojs/starlight/components';-音频默认已注册。通过 `Audio` 资源播放一次性音效和循环音乐,用句柄控制单个声音,用总线-平衡整体混音,并用空间音频把声音定位到世界里。+Estella 的音频通过 `Audio` 资源播放一次性音效和循环音乐,用句柄控制单个声音,用总线层级+平衡混音,并用空间音频把声音定位到世界里。它在浏览器上跑 Web Audio 后端,在微信上跑原生后端。++## 工作原理++`Audio` 是逐 App 的资源,默认已注册。音频文件会被解码成**缓冲区**并在首次使用时缓存,然后+在某个**总线**(命名的音量分组)上播放。每次播放返回一个 `AudioHandle`,你可以留着它来调节+或停止这一个声音。对于绑定到某个位置或物体的声音,`AudioSource` 组件声明式地播放,并在+(`spatial`)开启时按与 `AudioListener` 的距离衰减。++<Aside type="note">+ 音频自动注册——无需加插件。浏览器要求先有用户手势才能开始播放,所以第一次播放要从点击或+ 按键触发。+</Aside>## 音效与音乐@@ -19,35 +31,77 @@ const play = defineSystem([Res(Audio)], (audio) => {});```-- `playSFX(url, { volume?, pitch?, pan?, priority? })` 返回一个 `AudioHandle`。-- `playBGM(url, { volume?, fadeIn?, crossFade? })` 循环播放并替换当前曲目。-- `stopBGM(fadeOut?)`、`stopAll()`。-- `preload(url)` / `preloadAll(urls)` —— 提前加载缓冲,这样第一次播放不会是静音。+`playSFX` 触发一次性播放并返回一个句柄;`playBGM` 循环并替换当前曲目,可选交叉淡入。两者都会+自动预加载未缓存的片段并在就绪后播放。++## `Audio` API 参考++| 方法 | 说明 |+|---|---|+| `playSFX(url, config?)` | 播放一次性;返回 `AudioHandle`。config:`volume`、`pitch`、`pan`、`priority`。 |+| `playBGM(url, config?)` | 循环音乐,替换当前曲目。config:`volume`、`fadeIn`、`crossFade`。 |+| `stopBGM(fadeOut?)` | 停止音乐,可在 `fadeOut` 秒内淡出。 |+| `stopAll()` | 停止所有正在播放的声音。 |+| `setMasterVolume(v)` | 设置 master 总线音量(0..1)。 |+| `setMusicVolume(v)` | 设置 `music` 总线音量。 |+| `setSFXVolume(v)` | 设置 `sfx` 总线音量。 |+| `setUIVolume(v)` | 设置 `ui` 总线音量。 |+| `muteBus(name, muted)` | 按名字静音/取消静音一个总线。 |+| `preload(url)` | 提前解码并缓存一个片段(异步)。 |+| `preloadAll(urls)` | 预加载一组片段(异步)。 |+| `getBufferHandle(url)` | `url` 的已缓存缓冲区,或 `undefined`。 |## 控制正在播放的声音-`playSFX` 返回一个你可以保留并驱动的 `AudioHandle`:+`playSFX` 返回一个 `AudioHandle`——留着它驱动这个特定的声音:```typescriptconst shot = audio.playSFX('assets/laser.wav');shot.setVolume(0.6);-shot.setPan(-0.5); // -1 左 … +1 右-shot.setPlaybackRate(1.2); // 音高/速度+shot.setPan(-0.5); // -1 left … +1 right+shot.setPlaybackRate(1.2); // pitch / speed+shot.setLoop(true);shot.pause(); shot.resume(); shot.stop();-shot.onEnd = () => { /* 声音播放完毕 */ };-// 只读:shot.isPlaying、shot.currentTime、shot.duration+shot.onEnd = () => { /* the sound finished */ };```-## 声明式播放:`AudioSource`--给实体挂一个 `AudioSource`,无需写代码即可播放——设置 `clip`、`bus`(默认 `"sfx"`)、-`volume`、`pitch`、`loop`、`playOnAwake`。当 `playOnAwake` 且 `enabled` 时,音频系统-会自动播放它。+| 成员 | 类型 | 说明 |+|---|---|---|+| `setVolume(v)` | 方法 | 音量,0..1。 |+| `setPan(p)` | 方法 | 立体声声像,`-1`(左)…`+1`(右)。 |+| `setPlaybackRate(r)` | 方法 | 播放速度 / 音调(`1` = 正常)。 |+| `setLoop(l)` | 方法 | 循环该声音。 |+| `pause()` / `resume()` / `stop()` | 方法 | 传输控制。 |+| `onEnd` | 回调 | 声音结束时调用一次。 |+| `isPlaying` | 只读 | 是否正在播放。 |+| `currentTime` | 只读 | 播放位置(秒)。 |+| `duration` | 只读 | 总时长(秒)。 |++## 声明式播放 —— `AudioSource`++给实体加一个 `AudioSource` 即可不写代码播放——非常适合环境音、循环的机器声,或锚定到物体的+声音。配 `playOnAwake` + `enabled`,音频系统会自动开始播放。++| 属性 | 类型 | 默认 | 说明 |+|---|---|---|---|+| `clip` | asset | `''` | 要播放的音频资源。 |+| `bus` | string | `'sfx'` | 路由经过的混音总线。 |+| `volume` | number | `1` | 音量,0..1。 |+| `pitch` | number | `1` | 播放速度 / 音调。 |+| `loop` | boolean | `false` | 循环片段。 |+| `playOnAwake` | boolean | `false` | 实体启用时自动开始。 |+| `spatial` | boolean | `false` | 按与监听器的距离衰减。 |+| `minDistance` | number | `100` | 在此距离内音量为满。 |+| `maxDistance` | number | `1000` | 超过此距离即静音。 |+| `attenuationModel` | `AttenuationModel` | `Inverse` | 衰减曲线——`Linear` / `Inverse` / `Exponential`。 |+| `rolloff` | number | `1` | 衰减陡峭度的倍率。 |+| `priority` | number | `0` | 池满时的声部优先级(高者胜)。 |+| `enabled` | boolean | `true` | 关掉即停止并静音,而不移除组件。 |## 混音总线-混音器是分层的——`master → { music, sfx, ui, voice }`。设置某总线的音量会缩放它下面的-一切:+混音器是层级的——`master → { music, sfx, ui, voice }`。设置某个总线的音量会缩放路由到它下面+的一切:```typescriptaudio.setMasterVolume(0.8);@@ -57,17 +111,50 @@ audio.setUIVolume(0.9);audio.muteBus('music', true);```-用 `bus` 选项把声音路由到某个总线(`playSFX(url, { … })` 默认 `sfx`),或用-`AudioSource.bus` 字段。+用 `AudioSource.bus` 字段把声音路由到某个总线,或让 `playSFX` 默认走 `sfx`。用 `master` 做+全局音量滑条,在选项菜单里分开做 `music` / `sfx` / `ui` / `voice` 的滑条。## 空间音频-把 `AudioSource.spatial` 设为 `true`,并给相机/玩家一个启用的 `AudioListener`;音源会-按距离衰减。用 `minDistance`、`maxDistance` 和 `attenuationModel`(一个-`AttenuationModel`:inverse / linear / exponential)来调它。+设 `AudioSource.spatial = true`,并给监听实体(通常是相机或玩家)加一个启用的 `AudioListener`。+声源便按距离衰减:-<Aside type="caution">- `playSFX` 会自动预加载未缓存的片段并在就绪后播放,所以第一次触发可能是静音的——请- 提前调用 `preload(url)`。浏览器还要求先有一次用户手势才能开始播放音频,所以在第一次- 点击/按键时启动播放。-</Aside>+```typescript+import { defineSystem, Commands, Transform, AudioSource, AudioListener,+ AttenuationModel } from 'esengine';++const setupSpatial = defineSystem([Commands()], (cmds) => {+ // A positioned, looping ambience that fades with distance.+ cmds.spawn()+ .insert(Transform, { position: { x: 600, y: 0, z: 0 } })+ .insert(AudioSource, {+ clip: 'assets/campfire.ogg', loop: true, playOnAwake: true,+ spatial: true, minDistance: 80, maxDistance: 900,+ attenuationModel: AttenuationModel.Inverse,+ });++ // The listener (attach to the camera/player).+ cmds.entity(cameraEntity).insert(AudioListener, { enabled: true });+});+```++| `AttenuationModel` | 衰减 |+|---|---|+| `Linear` | 从 `minDistance` 到 `maxDistance` 的直线。 |+| `Inverse`(默认) | 自然的反距离衰减。 |+| `Exponential` | 更陡的指数衰减。 |++`AudioListener` 只有一个字段 `enabled`(默认 `true`)——场景里保持恰好一个启用的监听器。++## 最佳实践++- 对在关键时刻要播放的片段**预加载**(`preload` / `preloadAll`),第一次播放就不会因解码而静音。+- **在手势上开始**——浏览器在第一次用户输入前会屏蔽音频。+- **分开总线**(`music` / `sfx` / `ui` / `voice`)让玩家能各自调节,并统一由 `master` 驱动。+- 用 `AudioSource` 上的 `priority` **限制同时播放的声音数**,声部池满时重要的声音才胜出。+- 世界/物体声音**用 `AudioSource`(声明式)**,一次性的 UI/玩法音效用 `playSFX`。++## 参见++- [资源](/docs/zh-cn/guides/assets/) —— 加载与打包音频片段。+- [场景](/docs/zh-cn/guides/scene/) —— `AudioSource` 状态随场景持久化。