Cave 中的音频设计得非常直接：你导入音频文件，在编辑器中预览，并在游戏中某个事件发生时播放。

本课你将学习：

音频资产在 Asset Browser 中的工作方式。
如何预览音频文件。
如何导出或替换为 .ogg 格式的音频。
如何通过 Python 播放音频。
音量和音调的含义。
返回的音频句柄的用途。
Audio Monitor 标签页如何帮助调试音频。

你无需复杂的设置即可开始。如果你能导入声音，并在按钮、门、拾取物或角色动作发生时播放，你就已经理解了核心流程。

导入音频

Cave 可以将音频文件导入项目作为音频资产。正如你在导入资产部分看到的，Cave 支持 .ogg 格式的音频文件。

导入完成后，它会像其他项目内容一样显示在 Asset Browser 中。你可以在脚本、UI 回调、Logic Bricks、时间线事件或任何需要播放声音的系统中使用它。

例如，你的项目可能有这些音频资产：

Button Click
Door Open
Pickup Coin
Footstep
Forest Ambience

可读的名字非常有用，因为在 Python 中经常通过名字来引用音频。

预览音频资产

导入音频文件后，你可以直接在 Cave 中预览它。

有两种简单方式：

在 Asset Browser 中双击音频资产快速播放预览。
单击选中资产，显示属性面板，然后用预览控件播放。

属性面板预览更灵活，比如你可以在使用音频前测试不同音调的声音效果。

这对步伐声、撞击声、UI 点击声和生物声音等效果特别有用。微小的音调变化可以让重复的声音不那么单调。

导出或替换音频

音频资产也可以导出成 .ogg 文件，方便你在外部工具中编辑。

你也可以用另一段 .ogg 文件替换已存在的音频资产。这在逻辑已经引用该资产名，想改变实际声音时非常实用。

比如，游戏已经有名为 Door Open 的资产。如果你替换该资产中的音频，调用 Door Open 的脚本仍然有效，无需重命名。

使用 Audio Component 播放音频

有时你想播放一个简单的循环音效，比如环境音或主菜单音乐，这时只需用 Audio Component 即可：

它会无限循环播放指定音频，你可以控制音量、音调、是否为3D声音及最大距离。注意它没有更多选项，如循环次数等。如果需要更多定制，请用代码播放音频。

从 Python 播放音频

用最简单的方法，从 Python 调用 cave.playSound() 来播放音频资产。

cave.playSound("Button Click")

这段代码播放名为 Button Click 的音频资产。

你还可以传入音量参数：

cave.playSound("Door Open", volume=0.8)

音量默认是 1.0，表示正常音量。较低值使声音更小。

例如：

音量	含义
`2.0`	超大声音
`1.0`	正常声音
`0.5`	一半声音
`0.0`	静音

大部分情况下你会用 1.0 开始，再做调整。

音量和音调

音量控制声音大小。
音调控制声音高低，还会影响播放速度：高音调声音更快更尖锐，低音调声音更慢更低沉。

音量和音调的默认值都是 1.0。

例如：

数值	音量效果	音调效果
`1.0`	正常音量	正常音调
`0.5`	更小声	更低沉缓慢
`1.5`	更大声（当作音量时）	更高更快

使用 cave.playSound() 时，音量在启动声音时传入。音调通常通过函数返回的音频句柄来更改。

音频句柄

调用 cave.playSound() 后，Cave 会返回一个音频句柄。

该句柄代表当前正在播放的声音实例。

sound = cave.playSound("Footstep Stone", volume=0.8)
sound.pitch = 1.0

通过这个句柄，你可以在声音开始后控制它。

例如：

sound = cave.playSound("Cave Ambience", volume=0.6, loop=True)

# 也可以用 getter 和 setter：
sound.setPitch(0.9)
sound.setVolume(0.4)

这个句柄可以用来：

改变音量。
改变音调。
暂停声音。
继续播放。
停止声音。
查询播放进度。
使声音来源于3D实体。

比如，如果门的声音应该来自门的实体：

sound = cave.playSound("Door Open", volume=1.0)
sound.setSource3D(self.entity, maxDistance=20)

并非所有声音都需要这个句柄。如果只是播放一个简单的按钮点击声，直接调用即可：

cave.playSound("Button Click")

需要精细控制时再使用音频句柄。

你甚至可以通过稍微随机化步伐音高和音量，增加变化而无需增加更多声音文件：

sd = cave.playSound("Footstep Stone")

# 设置3D音源为播放该声音的实体：
sd.setSource3D(entity, 20)

# 随机化音调和音量：
sd.pitch  = cave.random.uniform(0.5, 1.5)
sd.volume = cave.random.uniform(0.1, 0.3)

上面代码与默认 Proto Character 走路和奔跑动画回调中的代码非常相似，在创建新 Cave 项目时即可看到。

Audio Monitor 标签页

Cave 还包含一个 Audio Monitor 标签页，用于游戏运行时调试音频。

你可以从编辑器左上角的 Tabs 菜单打开它。

Audio Monitor 显示当前播放的音频信息，包括播放进度。你可以展开条目查看更详细内容，非常适合当项目中同时播放多个声音时调试使用。

例如，Audio Monitor 可以帮你回答：

这音效真的在播放吗？
同样的音效播放了太多次吗？
循环播放的环境音仍在继续吗？
声音播放到了哪个位置？

在小型原型中你可能不常用 Audio Monitor，但在调试复杂场景时非常有用。

你应该记住的

Cave 中的音频很简单：导入音频文件，在 Asset Browser 中预览，并用 cave.playSound() 从 Python 播放。

用音量控制响度，音调控制声音高低，启动后需要控制时保留返回的句柄。

音频变得难以追踪时，从 Tabs 菜单打开 Audio Monitor 标签页，查看播放详情。

Cave：入门指南