com.alicizax.unity.framework/Runtime/Audio/Audio.md

Audio 模块使用文档

1. 模块目标

Audio 模块为框架提供统一的音频播放、缓存、回收、3D 空间音频与配置管理能力。

当前实现目标：

• 高频播放路径尽量稳定，避免热路径 GC
• AudioClip / AudioSource 生命周期可控，避免泄漏
• 支持 Music、Sound、UISound、Voice、Ambient
• 支持 2D 音频、3D 定点音频、跟随目标音频
• 支持距离衰减、空间混合、遮挡低通
• 配置从组件 Inspector 中抽离为可复用 ScriptableObject

模块核心代码位于：

• Runtime/Audio/AudioComponent.cs
• Runtime/Audio/IAudioService.cs
• Runtime/Audio/AudioService.cs
• Runtime/Audio/AudioCategory.cs
• Runtime/Audio/AudioAgent.cs
• Runtime/Audio/AudioGroupConfig.cs
• Runtime/Audio/AudioGroupConfigCollection.cs

2. 架构概览

模块运行时由以下几层组成：

2.1 AudioComponent

AudioComponent 是场景中的挂载入口，负责：

• 注册 AudioService
• 绑定 AudioMixer
• 绑定 AudioListener
• 绑定 AudioGroupConfigCollection
• 初始化运行时音频系统

2.2 AudioService

AudioService 是模块核心调度层，负责：

• 播放请求入口
• AudioType 维度的音量与开关管理
• AudioClip 缓存、引用计数、TTL、LRU
• AudioSource 对象池管理
• 播放句柄分配与控制
• 监听器注册

2.3 AudioCategory

每个 AudioType 对应一个 AudioCategory，负责：

• 维护该分类下的固定数量 AudioAgent
• 用空闲栈管理可用槽位
• 用最老播放堆管理满载抢占
• 更新该分类下活跃音频

2.4 AudioAgent

每个 AudioAgent 对应一个运行时播放槽位，负责：

• 绑定一个 AudioSource
• 管理单条播放状态
• 管理当前 AudioClip 引用
• 处理跟随、淡出、遮挡检测

2.5 AudioSourceObject

AudioSourceObject 是 AudioSource 的池化包装对象，接入框架 ObjectPoolService。

2.6 AudioClipCacheEntry

AudioClipCacheEntry 是单个地址的缓存条目，负责：

• AssetHandle
• AudioClip
• 引用计数
• LRU 链表节点
• pending 加载请求链

3. 生命周期

3.1 初始化

初始化链路：

1. 场景中挂载 AudioComponent
2. Awake 时注册 AudioService
3. Start 时读取 AudioGroupConfigCollection
4. 显式注册 AudioListener
5. 创建每个分类的 AudioCategory
6. 为每个分类预创建固定数量 AudioAgent
7. 每个 AudioAgent 从 ObjectPoolService 获取一个 AudioSourceObject

3.2 播放

播放链路：

1. 业务通过 IAudioService 发起播放
2. AudioService 生成池化播放请求
3. 对应 AudioCategory 从空闲栈取槽位，或从最老播放堆抢占
4. AudioAgent 绑定配置
5. 直接播放 AudioClip 或进入 AudioClip 加载/缓存逻辑
6. 播放完成、停止、淡出结束后释放引用

3.3 回收

回收链路：

• AudioAgent 停止后释放 AudioClip 引用
• AudioClip 引用计数归零后进入 LRU
• 到达 TTL 或容量超限时淘汰
• 服务销毁时统一停止播放、释放缓存、释放未使用 AudioSource

4. 场景配置

4.1 AudioComponent

在场景中创建一个 GameObject 挂载 AudioComponent。

推荐字段配置：

• Audio Mixer
  • 指向音频混音器资源
• Instance Root
  • 音频实例根节点
• Audio Listener
  • 显式绑定实际生效的监听器
• Audio Group Configs
  • 指向 AudioGroupConfigCollection 资源

4.2 为什么要显式绑定 AudioListener

当前实现不再扫描全场景查找监听器。

这样做的原因：

• 避免运行时全场景线性查找
• 避免多监听器场景中的不确定性
• 保证 3D 音频和遮挡始终基于明确目标

如果不手动绑定，AudioComponent 会在自身层级下尝试一次 GetComponentInChildren<AudioListener>(true)。

推荐规则：

• 主场景主相机上的监听器手动拖给 AudioComponent
• 运行时如果切换监听器，应显式重新注册

5. 配置资产

5.1 AudioGroupConfigCollection

AudioGroupConfigCollection 是一个 ScriptableObject，保存全部分类配置。

默认通过 CreateAssetMenu 创建：

• AlicizaX/Audio/Audio Group Configs

5.2 默认配置

新建资源后默认包含以下五组：

• Music
• Sound
• UISound
• Voice
• Ambient

5.3 AudioGroupConfig 字段说明

每个 AudioGroupConfig 包含：

• 音频类型
  • 对应 AudioType
• 名称
  • 配置展示名
• 静音
  • 初始化时该分类是否关闭
• 音量
  • 初始线性音量
• 通道数
  • 该分类最大并发 AudioAgent 数量
• Mixer音量参数
  • 对应 AudioMixer 暴露参数名
• 空间混合
  • 2D/3D 混合比例
• 多普勒
  • 多普勒系数
• 扩散
  • 声场扩散
• AudioSource优先级
  • Unity AudioSource Priority
• 混响区混合
  • Reverb Zone Mix
• 衰减模式
  • AudioRolloffMode
• 最小距离
  • 3D 音频近距离阈值
• 最大距离
  • 3D 音频远距离阈值
• 开启遮挡
  • 是否进行遮挡检测
• 遮挡检测层
  • 遮挡 Raycast LayerMask
• 遮挡检测间隔
  • 检测频率
• 遮挡低通截止频率
  • 遮挡时低通频率
• 遮挡音量系数
  • 遮挡时音量乘数

6. Inspector 使用

6.1 AudioComponent Inspector

AudioComponentInspector 提供：

• 音频监听器 字段
• 音频分组配置 字段
• 一键创建默认配置资源按钮

6.2 AudioGroupConfigCollection Inspector

AudioGroupConfigCollectionInspector 提供：

• 中文字段名
• 分类分块显示
• Occlusion 未开启时隐藏遮挡相关字段

7. 运行时 API

核心接口为 IAudioService。

7.1 全局开关

IAudioService audio = GameApp.Audio;

audio.Volume = 1f;
audio.Enable = true;

7.2 通用分类音量接口

推荐统一使用以下接口：

audio.SetCategoryVolume(AudioType.Music, 0.8f);
audio.SetCategoryVolume(AudioType.Sound, 1f);

float musicVolume = audio.GetCategoryVolume(AudioType.Music);

7.3 通用分类开关接口

audio.SetCategoryEnable(AudioType.Music, true);
audio.SetCategoryEnable(AudioType.Ambient, false);

bool ambientEnabled = audio.GetCategoryEnable(AudioType.Ambient);

7.4 2D 地址播放

ulong handle = audio.Play(
    AudioType.Sound,
    "Audio/SFX/Click",
    loop: false,
    volume: 1f,
    async: false,
    cacheClip: true);

参数说明：

• type
  • 分类
• path
  • 资源地址
• loop
  • 是否循环
• volume
  • 播放音量
• async
  • 是否异步加载
• cacheClip
  • 是否在播放后保留到缓存

7.5 直接播放 AudioClip

ulong handle = audio.Play(AudioType.Music, clip, loop: true, volume: 1f);

7.6 3D 定点播放

Vector3 position = hitPoint;
ulong handle = audio.Play3D(
    AudioType.Sound,
    "Audio/SFX/Explosion",
    position,
    loop: false,
    volume: 1f,
    async: true,
    cacheClip: true);

7.7 跟随目标播放

ulong handle = audio.PlayFollow(
    AudioType.Voice,
    "Audio/Voice/Npc001",
    npcTransform,
    Vector3.zero,
    loop: false,
    volume: 1f,
    async: true,
    cacheClip: true);

注意：

• 跟随播放不会把池化 AudioSource 挂到业务节点下
• 实际上是保持在音频根节点下，并同步世界位置/旋转

7.8 停止、暂停、恢复

audio.Stop(handle, fadeout: true);
audio.Pause(handle);
audio.Resume(handle);

7.9 按分类停止

audio.Stop(AudioType.Music, fadeout: true);
audio.StopAll(fadeout: false);

7.10 预加载与卸载

audio.Preload(preloadList, pin: true);
audio.Unload(unloadList);
audio.ClearCache();

说明：

• Preload(..., pin: true)
  • 预加载并常驻
• Unload(...)
  • 取消 pin，并在无引用时释放
• ClearCache()
  • 只清 unused 条目，不会强拆播放中和加载中的 clip

8. 句柄语义

播放返回值为 ulong handle。

句柄特点：

• 不是 AudioAgent 对象引用
• 对外只暴露控制句柄，不暴露内部实现
• 使用代际句柄避免旧句柄误命中新播放实例

推荐规则：

• 业务层如需后续停止某条音频，保存 handle
• 不需要控制的瞬时音效可忽略返回值

9. 缓存策略

9.1 基本机制

每个 AudioClip 地址对应一个 AudioClipCacheEntry。

条目包含：

• AssetHandle
• AudioClip
• RefCount
• Pinned
• CacheAfterUse
• Loading
• PendingHead / PendingTail
• LRU 节点

9.2 引用计数

播放开始时：

• RetainClip

播放结束时：

• ReleaseClip

9.3 LRU 与 TTL

当 RefCount == 0 时：

• 若 CacheAfterUse == true，进入 LRU
• 若 CacheAfterUse == false，立即清理

缓存会在以下情况被淘汰：

• 超过容量
• 超过 TTL

9.4 Pinned 资源

通过 Preload(..., pin: true) 的资源为 pinned。

特点：

• 不会被普通缓存淘汰
• 必须显式 Unload(...) 解除 pin

10. AudioSource 池化

10.1 池化来源

AudioSourceObject 使用框架内置 ObjectPoolService。

每个分类初始化时会创建固定数量 AudioAgent。 每个 AudioAgent 都会对应一个可复用 AudioSourceObject。

10.2 回收时机

模块销毁时：

• 停止所有播放
• 分类销毁
• AudioSourceObject 归还池
• 未使用池对象统一释放

11. 3D 空间音频

11.1 空间混合

由以下字段决定：

• AudioGroupConfig.SpatialBlend
• 播放请求是否是 3D / Follow / WorldPosition

11.2 距离衰减

由以下字段决定：

• RolloffMode
• MinDistance
• MaxDistance

11.3 遮挡

如果开启 Occlusion：

• 按配置时间间隔执行 Physics.Raycast
• 命中遮挡层后：
  • 启用 AudioLowPassFilter
  • 设置低通频率
  • 按 OcclusionVolumeMultiplier 压低音量

11.4 监听器来源

监听器只来自显式注册：

• AudioComponent 绑定的 AudioListener
• 或未来业务显式切换注册

12. 抢占策略

当某个 AudioCategory 已满：

• 先尝试空闲栈取空槽
• 若没有空槽，则从“最老播放堆”中取最早开始播放的槽位进行复用

特点：

• 无线性扫描
• 高并发下行为确定
• CPU 成本稳定

13. 与资源模块的关系

音频模块不直接把 AudioClip 交给资源模块对象池管理，而是：

• 使用 IResourceService.LoadAssetSyncHandle<T>()
• 使用 IResourceService.LoadAssetAsyncHandle<T>()
• 自己持有 AssetHandle
• 在缓存淘汰或销毁时 Dispose()

这样做的原因：

• 音频需要精细控制引用计数
• 音频有自己的 pin/LRU/TTL/pending 语义

14. 常见使用模式

14.1 BGM

var audio = GameApp.Audio;
audio.SetCategoryVolume(AudioType.Music, 0.8f);

ulong bgmHandle = audio.Play(
    AudioType.Music,
    "Audio/BGM/MainTheme",
    loop: true,
    volume: 1f,
    async: true,
    cacheClip: true);

14.2 UI 点击音效

GameApp.Audio.Play(
    AudioType.UISound,
    "Audio/UI/Click",
    loop: false,
    volume: 1f,
    async: false,
    cacheClip: true);

14.3 角色语音

GameApp.Audio.PlayFollow(
    AudioType.Voice,
    "Audio/Voice/Hero/Greeting",
    heroTransform,
    Vector3.up * 1.5f,
    loop: false,
    volume: 1f,
    async: true,
    cacheClip: false);

14.4 环境循环声

GameApp.Audio.Play3D(
    AudioType.Ambient,
    "Audio/Ambient/WaterfallLoop",
    waterfallPosition,
    loop: true,
    volume: 1f,
    async: true,
    cacheClip: true);

15. 运行时切换监听器

如果项目存在相机切换或监听器切换逻辑，应显式调用：

IAudioService audio = GameApp.Audio;
audio.UnregisterListener(oldListener);
audio.RegisterListener(newListener);

建议规则：

• 保证同一时刻只有一个主监听器负责注册
• 切换时先注销旧监听器，再注册新监听器

16. 扩展组件

16.1 AudioListenerBinder

AudioListenerBinder 用于把场景内的 AudioListener 显式注册到 IAudioService。

适用场景：

• 主相机不在 AudioComponent 同一节点下
• 运行时相机或监听器会切换
• 不希望 AudioComponent 扫描子节点查找监听器

使用方式：

1. 在带有 AudioListener 的对象上添加 AudioListenerBinder。
2. 确保场景中已经有 AudioComponent 初始化音频服务。
3. 对象启用时自动注册，禁用时自动注销。

16.2 AudioEmitter

AudioEmitter 是场景 3D 声源组件，面向篝火、电台、瀑布、机器噪音等固定或跟随物体的循环环境声。

核心字段：

• Audio Type：播放分类，环境声通常使用 Ambient。
• Address：音频资源地址。
• Play On Enable：对象启用时播放。
• Loop：是否循环。
• Follow Self：是否跟随当前物体。
• Min Distance：近距离清晰范围。
• Max Distance：超过该距离后听不到或接近听不到。
• Use Trigger Range：是否进入半径才播放。
• Trigger Range：自定义进入播放区域。
• Trigger Hysteresis：离开判定缓冲，避免边界频繁启停。
• Draw Gizmos：绘制触发范围和衰减范围。

篝火使用方式：

1. 在篝火对象上添加 AudioEmitter。
2. Audio Type 设为 Ambient。
3. Address 填篝火循环音效地址。
4. 开启 Play On Enable、Loop、Follow Self。
5. 关闭 Use Trigger Range。
6. 设置 Min Distance 为清晰听到的距离，例如 2。
7. 设置 Max Distance 为听不到的距离，例如 18。

这样玩家靠近篝火时声音更清晰，远离到最大距离后由 Unity 3D 衰减处理到不可闻。

电台使用方式：

1. 在电台对象上添加 AudioEmitter。
2. Audio Type 设为 Ambient 或 Voice。
3. Address 填电台循环音效地址。
4. 开启 Loop、Follow Self、Use Trigger Range。
5. 设置 Trigger Range 为进入区域，例如 8。
6. 设置 Min Distance 和 Max Distance 控制区域内的清晰范围与衰减。
7. 开启 Draw Gizmos，在 Scene 视图查看触发范围和衰减范围。

注意事项：

• AudioEmitter 不做场景扫描，不读取私有配置，不创建临时对象。
• 进入区域只触发一次；非循环音效播放完后不会在范围内每帧重播，离开再进入才会重新触发。
• Play3D 静态声源和 PlayFollow 跟随声源都支持单次播放覆盖 MinDistance、MaxDistance、RolloffMode、SpatialBlend。

17. 性能建议

17.1 推荐

• 高频短音效使用同步加载 + cacheClip: true
• 大型语音或低频资源可异步加载
• 常驻 BGM / 高频 UI 音效建议提前 Preload
• 明确设置分类通道数，避免过小导致过度抢占
• 3D 语音/环境音再开启遮挡，不要给所有分类都开

17.2 不推荐

• 每次播放都 cacheClip: false 且地址重复
• 不显式绑定 AudioListener
• 给 Music 设置过高空间混合
• 给大量瞬时音效开启高频遮挡检测

18. 常见问题

18.1 为什么播放返回 0

可能原因：

• AudioService 尚未初始化
• AudioType 越界
• AudioComponent 未正确配置
• AudioListener 未注册时 3D 音频相关行为不完整

18.2 为什么 ClearCache() 后仍有部分资源未释放

因为：

• 播放中的 clip 仍有引用
• 正在加载的 clip 仍有 pending request
• pinned 资源未调用 Unload

18.3 为什么跟随音频不会挂到目标节点下

这是刻意设计：

• 防止业务节点销毁时把池对象一起销毁
• 防止池生命周期被业务层意外接管

19. 扩展建议

如果后续继续扩展模块，优先遵守以下方向：

• 核心接口只保留 AudioType 通用访问
• 不再继续膨胀 IAudioService
• 新分类优先通过：
  • AudioType
  • AudioGroupConfigCollection
  • AudioMixer 暴露参数
  • 通用 Get/SetCategory API

不推荐继续在核心接口里新增：

• NpcVoiceVolume
• BattleMusicEnable
• CutsceneAmbientVolume

这类业务语义应放在业务 facade 或上层系统里。

20. 自测清单

修改音频模块后建议至少回归以下场景：

• 2D 同步播放
• 2D 异步播放
• 3D 定点播放
• Follow 播放
• 目标销毁时的 Follow 回收
• 分类满载时抢占
• Preload(pin: true) 与 Unload
• ClearCache() 对 unused 资源的清理
• 遮挡开启/关闭切换
• 监听器切换

21. 总结

当前 Audio 模块的核心使用原则可以归纳为：

• 入口统一从 IAudioService 走
• 分类控制统一用 AudioType
• 监听器显式注册，不做全场景扫描
• 高频资源使用缓存与预加载
• 3D 音频通过配置资产控制，不在业务层硬编码
• 池对象生命周期永远由音频系统自己掌握

如果严格遵守以上规则，模块可以稳定支撑常规项目中的 BGM、SFX、UI、Voice、Ambient 五类音频需求。