# 音频系统设置指南

## 概述

本文档介绍如何在游戏中集成音乐和音效系统，以及如何通过菜单控制音频音量。

## 系统架构

### 核心组件

1. **AudioManager** (`assets/scripts/Core/AudioManager.ts`)
   - 统一管理所有音频播放
   - 提供音乐和音效的播放、停止、音量控制功能
   - 单例模式，全局访问

2. **SoundController** (`assets/scripts/CombatSystem/MenuSystem/SoundController.ts`)
   - 管理菜单中的音频控制UI
   - 处理滑动条和开关按钮的交互
   - 与AudioManager集成，实现音量控制

3. **Audio静态类** (`assets/scripts/Core/AudioManager.ts`)
   - 提供便捷的静态方法访问音频功能
   - 简化代码调用

## 设置步骤

### 1. 创建AudioManager节点

在主场景中创建一个AudioManager节点：

```
Canvas/
├── AudioManager (添加AudioManager组件)
│   ├── MusicAudioSource (自动创建)
│   └── SFXAudioSource (自动创建)
```

### 2. 配置SoundController

在MenuUI节点上添加SoundController组件，并配置以下属性：

- **soundEffectSlider**: 音效滑动条组件
- **soundEffectCheckbox**: 音效开关按钮
- **soundEffectCheck**: 音效勾选标记节点
- **soundEffectProgressBg**: 音效进度条背景
- **musicSlider**: 音乐滑动条组件
- **musicCheckbox**: 音乐开关按钮
- **musicCheck**: 音乐勾选标记节点
- **musicProgressBg**: 音乐进度条背景
- **greenProgressSprite**: 绿色进度条材质

### 3. 准备音频资源

将音频文件放置在resources目录下：

```
assets/resources/
├── audio/
│   ├── music/
│   │   ├── background_music.mp3
│   │   └── menu_music.mp3
│   └── sfx/
│       ├── button_click.mp3
│       ├── weapon_fire.mp3
│       └── explosion.mp3
```

### 4. 在代码中使用音频系统

#### 播放背景音乐

```typescript
import { Audio } from '../Core/AudioManager';

// 播放背景音乐
Audio.playMusic('audio/music/background_music');

// 停止音乐
Audio.stopMusic();

// 暂停/恢复音乐
Audio.pauseMusic();
Audio.resumeMusic();
```

#### 播放音效

```typescript
// 播放音效
Audio.playSFX('audio/sfx/button_click');

// 播放音效并指定音量
Audio.playSFX('audio/sfx/explosion', 0.8);
```

#### 控制音量

```typescript
// 设置音乐音量 (0-1)
Audio.setMusicVolume(0.7);

// 设置音效音量 (0-1)
Audio.setSFXVolume(0.8);
```

## 菜单音频控制功能

### 滑动条功能

- **音效滑动条**: 控制所有音效的音量大小
- **音乐滑动条**: 控制背景音乐的音量大小
- **绿色进度条**: 跟随滑动条Handle的进度实时更新

### 开关按钮功能

- **勾选状态**: 音频正常播放，显示勾选标记
- **取消勾选**: 
  - 记录当前音量设置
  - 将滑动条移到最左侧（音量为0）
  - 隐藏勾选标记
- **重新勾选**: 
  - 恢复之前记录的音量设置
  - 滑动条回到之前的位置
  - 显示勾选标记

### 数据持久化

音频设置会自动保存到本地存储，包括：
- 音效开关状态
- 音乐开关状态
- 音效音量值
- 音乐音量值

## 集成示例

### 在武器系统中添加音效

```typescript
// 在武器发射时播放音效
export class WeaponController {
    private fireWeapon() {
        // 武器发射逻辑...
        
        // 播放发射音效
        Audio.playSFX('audio/sfx/weapon_fire');
    }
}
```

### 在UI按钮中添加点击音效

```typescript
// 在按钮点击事件中添加音效
export class ButtonController {
    private onButtonClick() {
        // 播放按钮点击音效
        Audio.playSFX('audio/sfx/button_click', 0.6);
        
        // 按钮逻辑...
    }
}
```

### 在游戏状态切换时控制音乐

```typescript
// 在游戏管理器中控制背景音乐
export class GameManager {
    private startGame() {
        // 播放游戏背景音乐
        Audio.playMusic('audio/music/background_music');
    }
    
    private pauseGame() {
        // 暂停背景音乐
        Audio.pauseMusic();
    }
    
    private resumeGame() {
        // 恢复背景音乐
        Audio.resumeMusic();
    }
    
    private gameOver() {
        // 停止背景音乐
        Audio.stopMusic();
        
        // 播放游戏结束音效
        Audio.playSFX('audio/sfx/game_over');
    }
}
```

## 注意事项

1. **音频格式**: 推荐使用MP3或OGG格式的音频文件
2. **文件大小**: 控制音频文件大小，避免影响游戏加载速度
3. **音量平衡**: 确保不同音效之间的音量平衡
4. **性能优化**: 避免同时播放过多音效
5. **资源管理**: 及时释放不再使用的音频资源

## 扩展功能

### 音频淡入淡出

可以扩展AudioManager添加淡入淡出功能：

```typescript
// 音乐淡入
public fadeInMusic(musicPath: string, duration: number = 2.0) {
    // 实现音乐淡入逻辑
}

// 音乐淡出
public fadeOutMusic(duration: number = 2.0) {
    // 实现音乐淡出逻辑
}
```

### 音效池管理

对于频繁播放的音效，可以实现音效池：

```typescript
// 预加载常用音效
public preloadSFX(sfxPaths: string[]) {
    // 预加载音效到内存池
}
```

### 3D音效

对于需要空间音效的场景，可以扩展支持3D音效：

```typescript
// 播放3D音效
public play3DSFX(sfxPath: string, position: Vec3) {
    // 实现3D音效播放
}
```

这个音频系统为游戏提供了完整的音频解决方案，支持菜单控制和代码调用，可以根据具体需求进行扩展和定制。