AudioModule 音频

AudioModule 是框架统一音频入口。业务提交资源 Address 和播放参数，使用 AudioHandle 控制单次播放，不直接创建、缓存或销毁 AudioSource。

子功能

• 播放参数
• 句柄与 Bus
• 配置
• 后端扩展

快速使用

AudioModule audio = AudioModule.Get();
if (audio == null)
    return;

AudioHandle music = audio.PlayMusic("Audio_MenuBgm", fadeIn: 0.5f, fadeOut: 0.3f);
AudioHandle click = audio.PlayUI("Audio_UIClick");
AudioHandle hit = audio.PlaySfx("Audio_Hit", volume: 0.8f);
AudioHandle voice = audio.PlayVoice("Audio_Voice001");
AudioHandle wind = audio.PlayAmbient("Audio_Wind", loop: true);
AudioHandle explosion = audio.PlayAt("Audio_Explosion", worldPosition);

高频调用可使用 UtilFunc：

AudioHandle music = UtilFunc.PlayMusic("Audio_MenuBgm");
AudioHandle sfx = UtilFunc.PlaySfx("Audio_Hit");
AudioHandle ui = UtilFunc.PlayUIAudio("Audio_UIClick");

UtilFunc.StopAudio(sfx);
UtilFunc.StopAudioBus(AudioBus.Sfx);

传入的字符串是 ResModule 能加载到 AudioClip 的全局 Address，不是文件系统路径。

设计思路与生命周期

当前调用链：

业务 -> AudioModule -> IAudioBackend -> UnityAudioBackend
                                      -> ResModule.LoadAsync<AudioClip>()

Unity 后端初始化时创建常驻 SuperCoreAudio 根节点、五个 Bus 子节点、AudioSource 对象池和唯一 AudioListener。每次播放：

1. 分配版本化 AudioHandle。
2. 通过 ResModule 异步加载 AudioClip。
3. 从对应 Bus 的池中取得并配置 AudioSource。
4. 播放结束、显式停止或并发淘汰时回收 Source，并释放 AssetHandle。

超出 Bus 并发上限时，后端优先停止该 Bus 中最早创建的非循环实例；没有可停止实例时拒绝新播放并记录警告。Music 不维护队列，新音乐会先停止当前 Music。

AudioModule.OnClear() 会停止全部实例、释放所有音频资源句柄、清理对象池并销毁 SuperCoreAudio。

AudioKey 支持 string 和 int 隐式转换。字符串供当前 Unity 后端使用；整数 Event ID 是为其他音频中间件后端预留的抽象，当前 Unity 后端收到整数会返回无效句柄。

注意事项

• 当前公开实现只有 Unity 后端，整数 AudioKey 不会播放。
• 业务 Scene 和 Prefab 不应再放置 AudioListener；框架后端已经创建唯一监听器。
• 3D 音效跟随对象时使用 parent；只设置 position 表示固定世界位置。
• 不要缓存或修改后端内部 AudioSource，业务只持有 AudioHandle。
• Bus 音量是运行态状态。需要跨启动保存时，由业务设置系统负责持久化并在启动后重新调用 Set API。
• 音频 Address 必须由资源工作台配置并能被当前活动资源 Package 路由。