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: 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.mdxindex 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```typescriptimport { 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 busvolume scales everything under it:```typescript-audio.setSFXVolume(0.5); // quieter effectsaudio.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.mdxindex 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` 资源播放一次性音效和循环音乐,用句柄控制单个声音,用总线+平衡整体混音,并用空间音频把声音定位到世界里。-## 在系统里播放+## 音效与音乐```typescriptimport { 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>