Cave：入门指南

在Cave中，音频设计非常简单：导入音频文件，在编辑器中预览，然后在游戏中播放。

在本课中，你将学习：

• 音频资源在资源浏览器中的工作原理。
• 如何预览音频文件。
• 如何导出或替换音频为.ogg文件。
• 如何通过Python播放音频。
• 音量和音调的含义。
• 返回的音频句柄可以用于什么。
• 音频监视器标签如何帮助调试音频。

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

导入音频

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

一旦音频被导入，它将在资源浏览器中与其他项目内容一样显示。在那里，你可以在脚本、UI回调、逻辑砖、时间线事件或任何需要播放声音的系统中使用它。

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

• 按钮点击
• 门打开
• 拾取硬币
• 脚步声
• 森林氛围

可读的名称在这里非常有用，因为音频通常在Python中通过名称引用。

预览音频资源

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

有两种简单的方法可以做到这一点：

• 双击资源浏览器中的音频资产以快速播放预览。
• 单击一次以选择它并显示其属性，在那里你可以使用预览控制播放它。

属性视图非常有用，因为它在预览时提供了更多控制。例如，你可以在将声音用于游戏之前测试不同音调值的音频效果。

这对于脚步声、冲击声、UI点击声和生物声音等效果特别有帮助。一点点音调变化可以使重复的声音感觉不那么相同。

导出或替换音频

音频资源也可以导出为.ogg文件。这在你想在外部工具中编辑音频时很有用。

你还可以用另一个.ogg文件替换音频资产。当逻辑已经引用了资源名称，但你想更改实际声音时，这很实用。

例如，你的游戏可能已经使用名为门打开的资源。如果你替换了该资产中的音频，播放门打开的脚本可以继续工作，而无需重命名。

使用音频组件播放音频

有时你想播放简单的循环声音，例如环境音、主菜单的音乐等。在这种情况下，音频组件就足够：

它将无休止地播放你指定的音频，并允许你控制音量、音调、声音是否是3D以及最大距离。注意，它没有暴露更多选项，例如我们希望循环音频的次数等。如果你需要更多自定义，你需要通过代码播放音频。

从Python播放音频

通过Python播放音频资产的最简单方法是使用cave.playSound()。

cave.playSound("按钮点击")

这会播放名为按钮点击的音频资产。

你还可以传递音量值：

cave.playSound("门打开", volume=0.8)

音量的默认值为1.0，这意味着正常音量。较低的值使声音更安静。

例如：

大多数情况下，你将从1.0开始并从那里调整。

音量和音调

• 音量控制声音的响度。
• 音调控制声音的高低感觉。它还改变播放速度，因此较高音调的声音更快更尖锐，而较低音调的声音更慢更深沉。

音量和音调的默认值均为1.0。

例如：

使用cave.playSound()时，音量在声音开始时直接传递。音调通常通过返回的音频句柄来改变。

音频句柄

当你调用cave.playSound()时，Cave返回一个音频句柄。

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

sound = cave.playSound("脚步声石头", volume=0.8)
sound.pitch = 1.0

你可以使用该句柄在声音开始后控制声音。

例如：

sound = cave.playSound("洞穴氛围", volume=0.6, loop=True)

# 或者，你可以使用getter和setter：
sound.setPitch(0.9)
sound.setVolume(0.4)

该句柄可用于以下操作：

• 更改音量。
• 更改音调。
• 暂停声音。
• 恢复声音。
• 停止声音。
• 检查进度。
• 使声音来自3D实体。

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

sound = cave.playSound("门打开", volume=1.0)
sound.setSource3D(self.entity, maxDistance=20)

你不需要这个句柄播放每个声音。如果你只想播放一次快速的按钮点击，这就足够了：

cave.playSound("按钮点击")

在需要额外控制时使用句柄。

甚至可以随机化脚步声，给它更多的变化而无需更多的声音：

sd = cave.playSound("脚步声石头")

# 将其3D源设置为播放它的实体：
sd.setSource3D(entity, 20)

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

上面的代码与在创建新Cave项目时默认Proto角色的行走和奔跑动画回调中找到的代码非常相似。

音频监视器标签

Cave还包括一个音频监视器标签，用于在游戏运行时调试音频。

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

音频监视器显示有关当前正在播放的音频的信息，包括播放进度。你可以展开条目以检查更多细节，当一个项目开始同时播放多个声音时，这非常有帮助。

例如，音频监视器可以帮助你回答诸如：

• 这个声音实际上正在播放吗？
• 是否同样的声音播放次数过多？
• 循环的环境音是否仍然有效？
• 声音进行到什么程度？

你可能不会在小型原型中不断需要音频监视器，但在调试更复杂的场景时，它变得非常有用。

你应该记住什么

在Cave中，音频非常简单：导入音频文件，在资源浏览器中预览，并通过cave.playSound()从Python播放。

使用音量控制响度，使用音调控制声音的高低感觉，当你需要控制声音时，保留返回的句柄。

当音频变得难以跟踪时，从标签菜单打开音频监视器标签，检查正在播放的内容。