AlicizaX/Client/Assets/Books/Framework/Runtime/Audio.md

Audio

模块概述

Audio 模块负责统一音频分类、音量控制、音频池与播放行为。它把音频拆分为音乐、音效、UI 音效、语音等类别，并支持使用 AudioMixer 做混音控制。

快速开始

1. 场景挂载 AudioComponent
2. 配置 AudioMixer、实例根节点与 AudioGroupConfig
3. 通过 GameApp.Audio 播放音频

using AlicizaX;
using AlicizaX.Audio.Runtime;

public sealed class AudioQuickStart
{
    public void PlayClick()
    {
        GameApp.Audio.Play(AudioType.UISound, "Audio/UI/Click");
    }
}

架构说明

AudioComponent
  └─ AudioService
      ├─ AudioCategory
      ├─ AudioAgent
      ├─ AudioGroupConfig
      └─ AudioClipPool

核心类与接口

IAudioService

主要属性：

• Volume
• Enable
• MusicVolume / SoundVolume / UISoundVolume / VoiceVolume
• MusicEnable / SoundEnable / UISoundEnable / VoiceEnable
• AudioMixer
• InstanceRoot

主要方法：

• Initialize(...)
• Play(...)
• Stop(...)
• StopAll(...)
• PutInAudioPool(...)
• CleanSoundPool()

API 参考

Initialize(AudioGroupConfig[] audioGroupConfigs, Transform instanceRoot = null, AudioMixer audioMixer = null)

• 必填参数：audioGroupConfigs
• 可选参数：instanceRoot
• 可选参数：audioMixer
• 返回值：无

Play(AudioType type, string path, bool bLoop = false, float volume = 1.0f, bool bAsync = false, bool bInPool = false)

• 必填参数：type
• 必填参数：path
• 其余均为可选参数
• 返回值：AudioAgent

完整使用示例

using AlicizaX;
using AlicizaX.Audio.Runtime;

public sealed class AudioExample
{
    public void PlayBgm()
    {
        GameApp.Audio.MusicVolume = 0.8f;
        GameApp.Audio.Play(AudioType.Music, "Audio/Bgm/MainTheme", true, 1f, true, true);
    }
}

最佳实践

• 常用短音效建议预热
• 背景音乐和 UI 音效分混音组管理