音频

要添加、编辑或删除背景音乐（BGM）和音效（SFX）资源，请打开 Naninovel -> Configuration -> Audio 编辑器菜单，然后单击“Manage BGM Resources”或“Manage SFX Resources”按钮以访问相应的资源管理器。您可以使用 Unity 支持 ↗ 的任何音频格式。

提示

选择最适合您的开发工作流程的文件格式。构建项目时，Unity 会自动将所有源资源（纹理、音频、视频等）转换为最适合目标平台的格式，因此您最初在项目中存储资源的格式不会产生影响。有关 Unity 如何管理项目资产的更多信息，请参阅 官方文档 ↗。

如果您有很多音频文件，并且通过编辑器菜单分配它们不方便，只需将它们放入 Resources/Naninovel/BGM（音乐）和 Resources/Naninovel/SFX（音效）文件夹，它们就会自动在脚本中可用。如果您愿意，还可以使用子文件夹组织它们；在这种情况下，在剧本脚本中引用它们时请使用正斜杠（/）。例如，存储为 Resources/Naninovel/BGM/Ambient/Noise002.wav 的音频剪辑可以在脚本中引用为 Ambient/Noise002。

也可以使用 Addressable 资产系统 手动公开资源。要公开资产，请将上述方法所用的路径去掉“Resources/”部分，作为资产的地址。例如，要公开“MainTheme.wav”BGM，请为剪辑资产分配以下地址：Naninovel/BGM/MainTheme。请注意，在编辑器中始终优先使用特殊的“Editor”资源提供者；只有未通过编辑器菜单分配的资源才会尝试通过 Addressable 提供者加载。

警告

未通过资源管理器分配的音频资产不会出现在各种编辑器下拉菜单中，例如用于为角色 Actor 选择 Message Sound 的下拉菜单。

可以使用 Naninovel -> Configuration -> Audio 编辑器菜单配置音频播放行为；有关可用选项，请参阅 配置指南。

背景音乐

使用 @bgm 命令后跟剪辑名称来控制剧本脚本中的音乐播放：

; 开始循环播放名为“Sanctuary”的音乐音轨。
@bgm Sanctuary

; 与上面相同，但在 10 秒内淡入音量并且只播放一次。
@bgm Sanctuary fade:10 !loop

; 在 2.5 秒内将所有正在播放的音乐音轨的音量更改为 50%
; 并让它们循环播放。
@bgm volume:0.5 loop! fade:2.5

音乐音轨默认循环播放。当 @bgm 命令中未指定音乐音轨名称时，将影响所有当前正在播放的音轨。对已在播放的音轨调用该命令时，音轨不会从头重播，但会应用指定的参数（音量和音轨是否循环）。

可以使用 intro 参数先播放前奏，再播放循环部分，例如：

; 播放“BattleThemeIntro”一次，然后循环播放“BattleThemeMain”。
@bgm BattleThemeMain intro:BattleThemeIntro

要停止正在播放的音乐音轨，请使用 @stopBgm 命令，后跟剪辑名称。当未指定剪辑名称时，该命令将停止所有当前正在播放的音轨。

; 在 10 秒内淡出“Promenade”音乐音轨并停止播放。
@stopBgm Promenade fade:10

; 停止所有当前正在播放的音乐音轨。
@stopBgm

音效

使用 @sfx 和 @stopSfx 命令后跟剪辑名称来控制剧本脚本中音效的播放：

; 播放一次名为“Explosion”的 SFX。
@sfx Explosion

; 循环播放名为“Rain”的 SFX。
@sfx Rain loop!

; 在 2.5 秒内将所有正在播放的 SFX 音轨的音量更改为 75%
; 并禁用它们的循环。
@sfx volume:0.75 !loop fade:2.5

音效音轨默认不循环播放。当 @sfx 命令中未指定 SFX 音轨名称时，将影响所有当前正在播放的音轨。对已在播放的音轨调用该命令时，音轨不会从头重播，但会应用指定的参数（音量和音轨是否循环）。

要停止正在播放的音效（无论是否循环），请使用 @stopSfx 命令，后跟剪辑名称。当未指定剪辑名称时，该命令将停止所有当前正在播放的 SFX 音轨。

; 停止播放名为“Rain”的 SFX，淡出 15 秒。
@stopSfx Rain fade:15

; 停止所有当前正在播放的音效音轨。
@stopSfx

空间音频

所有音频命令都支持 pos 和 wpos 参数；指定其中任一参数时会启用空间模式，又名“3D 音频”。关联的音频源将被配置为根据其相对于音频监听器的位置作出响应。使用 pos 可按相对于场景边界的百分比放置音频源（0,0 为左下角，100,100 为右上角），使用 wpos 则可在世界空间中放置音频源。

; 在世界空间中，于监听器稍上方偏后的位置播放“Explosion”。
@sfx Explosion wpos:0,1,-3

可以像其他参数一样为位置设置动画：

; 在场景空间中将“Rain”的位置右-左-右平移，直到停止。
@async Rainpan loop!
    @sfx Rain pos:100,50 fade:10
    @wait 10
    @sfx Rain pos:0,50 fade:10
    @wait 10

...

@stop Rainpan

音频监听器的默认位置是 x0 y0 z-1，位于场景原点稍后方。这样无需总是沿 Z 轴偏移音频位置，也能让声音的位置更自然。

音频混音器

Naninovel 在播放音频时使用 音频混音器 ↗ 资产来分离 BGM、SFX 和语音通道。

可以在音频配置菜单中分配自定义混音器资产、更改每个音频通道使用的组，以及更改音量控制句柄（公开的参数名称）。当未分配自定义混音器资产时，将使用默认资产。

要通过自定义混音器组播放音频，请使用 @bgm、@sfx 和 @voice 命令中可用的 group 参数指定组路径。

; 通过“Master/Ambient”混音器组循环播放“Noise”音频资源。
@sfx Noise loop! group:Master/Ambient

; 通过“Master/Reverb”混音器组播放“ScaryVoice”语音资源。
@voice ScaryVoice group:Master/Reverb

使用当前分配的音频混音器资产的 FindMatchingGroups(groupPath) 方法检索组；有关预期路径格式的更多信息，请参阅 Unity 文档 ↗。如果多个组与提供的路径关联，则将使用第一个组来播放音频。

自定义音频后端

Unity 允许使用自定义解决方案（例如 FMOD ↗ 和 Wwise ↗）替换其内置音频后端。为此，Naninovel 的 IAudioManager 接口不依赖于默认音频后端（例如，它不引用 AudioClip、AudioSource 等）。这样，您就可以 覆盖服务 并使用自定义音频后端，而无需修改引擎的源代码。

下面是针对 FMOD 进行此类覆盖的最小示例。

[InitializeAtRuntime(@override: typeof(AudioManager))]
public class FMODAudioManager : IAudioManager
{
    // 假设 FMOD 资源加载是在外部管理的。
    public IResourceLoader SfxLoader { get; } = new NullResourceLoader();

    // 假设 FMOD 的生命周期是在外部管理的。
    public Awaitable InitializeService () => Async.Completed;
    public void DestroyService () { }

    public Awaitable PlaySfx (string path, ...)
    {
        // 从路径解析 FMOD 的事件引用并播放它。
    }

    public AudioMixerGroup GetGroup (string groupPath)
    {
        // 返回 null 或以其他方式忽略不支持的功能是可以的。
        return null;
    }

    // 其他 API...
}