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: deepen the Audio guide (handles, buses, spatial)

yhhdac526a83f2c
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdx
index 4b5948315..f32e0f335 100644
--- a/docs/astro/src/content/docs/guides/audio.mdx
+++ b/docs/astro/src/content/docs/guides/audio.mdx
@@ -1,57 +1,77 @@
---
title: Audio
-description: Play sound effects and music, mix buses, and position spatial audio.
+description: Sound effects, music, playback handles, mixer buses, and spatial audio.
---
import { Aside } from '@astrojs/starlight/components';
-Audio is registered by default. Play one-shot effects and music through the
-`Audio` resource, or drive playback declaratively with an `AudioSource`
-component.
+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.
-## Play from a system
+## Sound effects and music
```typescript
import { defineSystem, Res, Audio } from 'esengine';
-defineSystem([Res(Audio)], (audio) => {
- audio.playSFX('assets/audio/kick.wav', { volume: 1.0, pitch: 1.0 });
- audio.playBGM('assets/audio/theme.ogg', { fadeIn: 0.5 });
+const play = defineSystem([Res(Audio)], (audio) => {
+ const sfx = audio.playSFX('assets/hit.wav', { volume: 1, pitch: 1, pan: 0 });
+ audio.playBGM('assets/theme.ogg', { fadeIn: 0.5, crossFade: 1.0 });
});
```
-`AudioAPI` also has `stopBGM(fadeOut?)`, `stopAll()`, `preload(url)` /
-`preloadAll(urls)`, and mixer volumes: `setMasterVolume`, `setMusicVolume`,
-`setSFXVolume`, `setUIVolume` (all `0–1`).
+- `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` returns an `AudioHandle` you can `stop()`, `pause()`, `resume()`,
-`setVolume()`, `setPan()`, `setLoop()`.
+## Control a playing sound
+
+`playSFX` returns an `AudioHandle` you keep and drive:
+
+```typescript
+const 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.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 a clip without code: `clip`, `bus`
-(`"sfx"` by default), `volume`, `pitch`, `loop`, `playOnAwake`, and spatial
-fields (`spatial`, `minDistance`, `maxDistance`, `attenuationModel`). With
+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.
## Mixer buses
-The mixer is hierarchical: `master → { music, sfx, ui, voice }`. Setting a bus
+The mixer is hierarchical — `master → { music, sfx, ui, voice }`. Setting a bus
volume scales everything under it:
```typescript
-audio.setSFXVolume(0.5); // quieter effects
audio.setMasterVolume(0.8);
+audio.setMusicVolume(0.6);
+audio.setSFXVolume(1.0);
+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.
+
## Spatial audio
-Set `AudioSource.spatial = true` and put an enabled `AudioListener` on your
-camera/player entity; distance attenuation follows the source's
-`attenuationModel`.
+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).
<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 for guaranteed timing.
- Browsers also require a user gesture before audio can start.
+ 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>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx b/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
index 625d87382..b1a494002 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
@@ -1,54 +1,73 @@
---
title: 音频
-description: 播放音效与音乐、混音总线,以及空间音频。
+description: 音效、音乐、播放句柄、混音总线与空间音频。
---
import { Aside } from '@astrojs/starlight/components';
-音频默认已注册。通过 `Audio` 资源播放一次性音效与音乐,或用 `AudioSource` 组件以声明
-方式驱动播放。
+音频默认已注册。通过 `Audio` 资源播放一次性音效和循环音乐,用句柄控制单个声音,用总线
+平衡整体混音,并用空间音频把声音定位到世界里。
-## 在系统里播放
+## 音效与音乐
```typescript
import { defineSystem, Res, Audio } from 'esengine';
-defineSystem([Res(Audio)], (audio) => {
- audio.playSFX('assets/audio/kick.wav', { volume: 1.0, pitch: 1.0 });
- audio.playBGM('assets/audio/theme.ogg', { fadeIn: 0.5 });
+const play = defineSystem([Res(Audio)], (audio) => {
+ const sfx = audio.playSFX('assets/hit.wav', { volume: 1, pitch: 1, pan: 0 });
+ audio.playBGM('assets/theme.ogg', { fadeIn: 0.5, crossFade: 1.0 });
});
```
-`AudioAPI` 还有 `stopBGM(fadeOut?)`、`stopAll()`、`preload(url)` /
-`preloadAll(urls)`,以及混音音量:`setMasterVolume`、`setMusicVolume`、
-`setSFXVolume`、`setUIVolume`(均为 `0–1`)。
+- `playSFX(url, { volume?, pitch?, pan?, priority? })` 返回一个 `AudioHandle`。
+- `playBGM(url, { volume?, fadeIn?, crossFade? })` 循环播放并替换当前曲目。
+- `stopBGM(fadeOut?)`、`stopAll()`。
+- `preload(url)` / `preloadAll(urls)` —— 提前加载缓冲,这样第一次播放不会是静音。
-`playSFX` 返回一个 `AudioHandle`,可 `stop()`、`pause()`、`resume()`、
-`setVolume()`、`setPan()`、`setLoop()`。
+## 控制正在播放的声音
-## 声明式播放:`AudioSource`
+`playSFX` 返回一个你可以保留并驱动的 `AudioHandle`:
-给实体挂上 `AudioSource`,无需写代码即可播放某个片段:`clip`、`bus`(默认 `"sfx"`)、
-`volume`、`pitch`、`loop`、`playOnAwake`,以及空间字段(`spatial`、`minDistance`、
-`maxDistance`、`attenuationModel`)。当 `playOnAwake` 且 `enabled` 时,音频系统会自动
-播放它。
+```typescript
+const shot = audio.playSFX('assets/laser.wav');
+shot.setVolume(0.6);
+shot.setPan(-0.5); // -1 左 … +1 右
+shot.setPlaybackRate(1.2); // 音高/速度
+shot.pause(); shot.resume(); shot.stop();
+shot.onEnd = () => { /* 声音播放完毕 */ };
+// 只读:shot.isPlaying、shot.currentTime、shot.duration
+```
+
+## 声明式播放:`AudioSource`
+
+给实体挂一个 `AudioSource`,无需写代码即可播放——设置 `clip`、`bus`(默认 `"sfx"`)、
+`volume`、`pitch`、`loop`、`playOnAwake`。当 `playOnAwake` 且 `enabled` 时,音频系统
+会自动播放它。
## 混音总线
-混音器是分层的:`master → { music, sfx, ui, voice }`。设置某个总线的音量会缩放它下面的
-一切:
+混音器是分层的——`master → { music, sfx, ui, voice }`。设置某总线的音量会缩放它下面的
+一切:
```typescript
-audio.setSFXVolume(0.5); // 降低音效
audio.setMasterVolume(0.8);
+audio.setMusicVolume(0.6);
+audio.setSFXVolume(1.0);
+audio.setUIVolume(0.9);
+audio.muteBus('music', true);
```
+用 `bus` 选项把声音路由到某个总线(`playSFX(url, { … })` 默认 `sfx`),或用
+`AudioSource.bus` 字段。
+
## 空间音频
-把 `AudioSource.spatial` 设为 `true`,并在相机/玩家实体上放一个启用的 `AudioListener`;
-距离衰减遵循音源的 `attenuationModel`。
+把 `AudioSource.spatial` 设为 `true`,并给相机/玩家一个启用的 `AudioListener`;音源会
+按距离衰减。用 `minDistance`、`maxDistance` 和 `attenuationModel`(一个
+`AttenuationModel`:inverse / linear / exponential)来调它。
<Aside type="caution">
- `playSFX` 会自动预加载未缓存的片段并在就绪后播放,因此第一次触发可能是静音的——请
- 提前调用 `preload(url)` 以保证时机。浏览器还要求先有一次用户手势才能开始播放音频。
+ `playSFX` 会自动预加载未缓存的片段并在就绪后播放,所以第一次触发可能是静音的——请
+ 提前调用 `preload(url)`。浏览器还要求先有一次用户手势才能开始播放音频,所以在第一次
+ 点击/按键时启动播放。
</Aside>