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: fix audio guide accuracy and add missing API coverage
esenginefe25d0e24b62
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdxindex 99086d302..32ce19f05 100644--- a/docs/astro/src/content/docs/guides/audio.mdx+++ b/docs/astro/src/content/docs/guides/audio.mdx@@ -24,7 +24,7 @@ Attach to any entity to play audio. Requires a `Transform` component for spatial| `spatial` | boolean | `false` | Enable spatial audio || `minDistance` | number | `100` | Spatial reference distance || `maxDistance` | number | `1000` | Spatial max distance |-| `attenuationModel` | number | `0` | 0 = Linear, 1 = Inverse, 2 = Exponential |+| `attenuationModel` | number | `1` | 0 = Linear, 1 = Inverse, 2 = Exponential || `rolloff` | number | `1.0` | Spatial rolloff factor (0–5) || `priority` | number | `0` | Playback priority || `enabled` | boolean | `true` | Component active |@@ -48,23 +48,57 @@ import { Audio } from 'esengine';const handle = Audio.playSFX('assets/explosion.mp3', {volume: 0.8,pitch: 1.2,+ pan: -0.5, // stereo panning (-1 left, 0 center, 1 right)});// Control playbackhandle.pause();handle.resume();handle.stop();+handle.setVolume(0.6);+handle.setLoop(true);+handle.setPlaybackRate(1.5);-// Play background music with fade-in+// Query state+console.log(handle.isPlaying, handle.currentTime, handle.duration);+```++### Background Music++```typescript+// Play BGM with fade-inAudio.playBGM('assets/theme.mp3', { volume: 0.5, fadeIn: 2.0 });+// Switch BGM with cross-fade (old track fades out while new one fades in)+Audio.playBGM('assets/boss.mp3', { volume: 0.7, crossFade: 1.5 });+// Stop BGM with fade-outAudio.stopBGM(1.0);++// Stop all audio immediately (BGM + cancel fades)+Audio.stopAll();```+### AudioHandle++Both `playSFX` and entity-based playback return an `AudioHandle`:++| Method / Property | Description |+|-------------------|-------------|+| `stop()` | Stop playback and release resources |+| `pause()` | Pause playback |+| `resume()` | Resume paused playback |+| `setVolume(v)` | Set volume (0–1) |+| `setPan(p)` | Set stereo panning (-1 left, 0 center, 1 right) |+| `setLoop(l)` | Enable/disable looping |+| `setPlaybackRate(r)` | Set playback speed |+| `isPlaying` | Whether audio is currently playing |+| `currentTime` | Current playback position in seconds |+| `duration` | Total duration in seconds |+## Volume Control-Control volume per bus:+Control volume per bus via the mixer:```typescriptimport { Audio } from 'esengine';@@ -78,6 +112,10 @@ Audio.setUIVolume(0.7);Audio.muteBus('music', true);```+<Aside type="caution">+The mixer is only available on Web (Web Audio API). On WeChat MiniGame, the mixer is `null` and these volume methods are no-ops. Use `AudioHandle.setVolume()` for per-sound volume control on WeChat.+</Aside>+## PreloadingPreload audio files to avoid latency on first play:@@ -93,6 +131,10 @@ await Audio.preloadAll([]);```+<Aside type="tip">+Audio clips referenced by `AudioSource` components are automatically preloaded when a scene loads. Manual preloading is only needed for clips played via `Audio.playSFX()` or `Audio.playBGM()` from script code.+</Aside>+## Entity-Based PlaybackAdd `AudioSource` to an entity in the editor or via code:@@ -124,9 +166,17 @@ The system automatically calculates distance-based attenuation and stereo pannin**Attenuation models:**- **Linear** (0) — volume decreases linearly between `minDistance` and `maxDistance`-- **Inverse** (1) — realistic falloff based on inverse distance+- **Inverse** (1, default) — realistic falloff based on inverse distance- **Exponential** (2) — steep falloff using exponential curve+## WeChat MiniGame++On WeChat, audio uses `wx.createInnerAudioContext()` instead of Web Audio API. Key differences:++- **No mixer** — bus-based volume control (`setMasterVolume`, `setSFXVolume`, etc.) is unavailable. Use `AudioHandle.setVolume()` for per-sound control.+- **No stereo panning** — `setPan()` is a no-op. Spatial audio attenuation still works (volume-based).+- **Local file paths** — audio files in the build package are accessed by relative path (e.g. `assets/sounds/bgm.mp3`).+## Editor Integration- **Inspector** — audio files show an inline preview player with play/pause controlsdiff --git a/docs/astro/src/content/docs/zh/guides/audio.mdx b/docs/astro/src/content/docs/zh/guides/audio.mdxindex eef65db37..736e67ba6 100644--- a/docs/astro/src/content/docs/zh/guides/audio.mdx+++ b/docs/astro/src/content/docs/zh/guides/audio.mdx@@ -24,7 +24,7 @@ ESEngine 提供完整的音频系统,包含 ECS 组件、总线混音和空间| `spatial` | boolean | `false` | 启用空间音频 || `minDistance` | number | `100` | 空间音频参考距离 || `maxDistance` | number | `1000` | 空间音频最大距离 |-| `attenuationModel` | number | `0` | 0 = 线性, 1 = 反比, 2 = 指数 |+| `attenuationModel` | number | `1` | 0 = 线性, 1 = 反比, 2 = 指数 || `rolloff` | number | `1.0` | 空间衰减因子(0–5) || `priority` | number | `0` | 播放优先级 || `enabled` | boolean | `true` | 组件激活 |@@ -48,23 +48,57 @@ import { Audio } from 'esengine';const handle = Audio.playSFX('assets/explosion.mp3', {volume: 0.8,pitch: 1.2,+ pan: -0.5, // 立体声声像(-1 左, 0 中, 1 右)});// 控制播放handle.pause();handle.resume();handle.stop();+handle.setVolume(0.6);+handle.setLoop(true);+handle.setPlaybackRate(1.5);+// 查询状态+console.log(handle.isPlaying, handle.currentTime, handle.duration);+```++### 背景音乐++```typescript// 播放背景音乐,带淡入Audio.playBGM('assets/theme.mp3', { volume: 0.5, fadeIn: 2.0 });+// 切换背景音乐,带交叉淡入淡出(旧曲目淡出,新曲目同时淡入)+Audio.playBGM('assets/boss.mp3', { volume: 0.7, crossFade: 1.5 });+// 停止背景音乐,带淡出Audio.stopBGM(1.0);++// 立即停止所有音频(背景音乐 + 取消淡入淡出)+Audio.stopAll();```+### AudioHandle++`playSFX` 和基于实体的播放都返回 `AudioHandle`:++| 方法 / 属性 | 说明 |+|-------------|------|+| `stop()` | 停止播放并释放资源 |+| `pause()` | 暂停播放 |+| `resume()` | 恢复暂停的播放 |+| `setVolume(v)` | 设置音量(0–1) |+| `setPan(p)` | 设置立体声声像(-1 左, 0 中, 1 右) |+| `setLoop(l)` | 启用/禁用循环 |+| `setPlaybackRate(r)` | 设置播放速度 |+| `isPlaying` | 是否正在播放 |+| `currentTime` | 当前播放位置(秒) |+| `duration` | 总时长(秒) |+## 音量控制-按总线控制音量:+通过混音器按总线控制音量:```typescriptimport { Audio } from 'esengine';@@ -78,6 +112,10 @@ Audio.setUIVolume(0.7);Audio.muteBus('music', true);```+<Aside type="caution">+混音器仅在 Web 平台(Web Audio API)可用。在微信小游戏上,混音器为 `null`,这些音量方法不会生效。请在微信上使用 `AudioHandle.setVolume()` 进行逐个音效的音量控制。+</Aside>+## 预加载预加载音频文件以避免首次播放延迟:@@ -93,6 +131,10 @@ await Audio.preloadAll([]);```+<Aside type="tip">+`AudioSource` 组件引用的音频剪辑会在场景加载时自动预加载。只有通过脚本代码调用 `Audio.playSFX()` 或 `Audio.playBGM()` 播放的剪辑才需要手动预加载。+</Aside>+## 基于实体的播放在编辑器中或通过代码为实体添加 `AudioSource`:@@ -124,9 +166,17 @@ import { AudioSource, AudioListener, AttenuationModel } from 'esengine';**衰减模型:**- **线性** (0) — 音量在 `minDistance` 和 `maxDistance` 之间线性降低-- **反比** (1) — 基于反比距离的真实衰减+- **反比** (1, 默认) — 基于反比距离的真实衰减- **指数** (2) — 使用指数曲线的陡峭衰减+## 微信小游戏++在微信平台上,音频使用 `wx.createInnerAudioContext()` 而非 Web Audio API。主要差异:++- **无混音器** — 总线音量控制(`setMasterVolume`、`setSFXVolume` 等)不可用。请使用 `AudioHandle.setVolume()` 进行逐个音效的音量控制。+- **无立体声声像** — `setPan()` 无效。空间音频衰减仍然有效(基于音量)。+- **本地文件路径** — 构建包内的音频文件通过相对路径访问(如 `assets/sounds/bgm.mp3`)。+## 编辑器集成- **检查器** — 音频文件显示内联预览播放器,支持播放/暂停控制