EG/plugins/user/spatial_audio/README.md

# 3D空间音效插件

一个功能完整的3D空间音效系统插件，为EG引擎提供基于Panda3D的3D音频处理功能，支持空间音效、环境音效和音频效果处理。

## 功能特性

### 核心功能
- **3D音频定位**: 基于听者位置和方向的实时3D音频定位
- **2D音频支持**: 支持传统的2D音频播放
- **音频源管理**: 完整的音频源创建、播放、暂停、停止和删除功能
- **环境音频**: 区域化的环境音效系统
- **音频效果**: 支持多种音频效果处理（混响、回声、滤波等）
- **音频缓存**: 智能音频文件缓存系统，提高加载性能
- **淡入淡出**: 支持音频的淡入淡出效果

### 音频处理
- **空间化处理**: 基于距离和方向的音量衰减和声道平衡
- **多普勒效应**: 根据音源和听者的相对运动计算频率变化
- **HRTF支持**: 头部相关传递函数实现更真实的3D音效
- **环境混响**: 根据房间尺寸和材质自动计算混响参数
- **音量控制**: 精确的音量控制和淡入淡出效果
- **距离衰减**: 可配置的最小/最大距离和衰减因子
- **音频优先级**: 音频资源管理和优先级控制

### 音频效果
- **混响效果**: 模拟不同环境的混响效果
- **回声效果**: 创建回声和延迟效果
- **滤波效果**: 低通、高通和带通滤波器
- **失真效果**: 音频失真和过载效果
- **压缩效果**: 动态范围压缩
- **均衡器**: 多频段均衡器
- **合声/镶边**: 调制效果
- **效果链**: 支持多个效果的组合应用

### 环境系统
- **音频区域**: 定义具有特定音频属性的3D区域
- **环境音效**: 区域内的背景环境音效
- **区域属性**: 可配置的区域音频参数
- **动态切换**: 听者在不同区域间移动时的音频切换
- **过渡效果**: 区域间平滑的音频过渡
- **遮挡效果**: 音频遮挡和 occlusion 处理
- **回调系统**: 区域进入/离开/内部状态回调

### 编辑功能
- **可视化编辑**: 图形化界面编辑音频场景
- **多种工具**: 选择、添加音效、添加区域等工具
- **场景保存/加载**: 音频场景的序列化和反序列化
- **网格对齐**: 网格对齐功能提高编辑精度
- **实时预览**: 编辑过程中的实时音频预览

### 性能优化
- **资源管理**: 智能的音频资源加载和卸载
- **内存优化**: 音频缓冲区管理和内存复用
- **批量处理**: 支持大量音频源的同时处理
- **LOD支持**: 根据距离调整音频处理质量
- **对象池**: 音频对象池减少GC压力

## 使用方法

### 快捷键操作
- **F1**: 切换音频调试模式
- **F2**: 切换空间音频
- **F3**: 播放测试音效
- **F4**: 停止所有音频
- **F5**: 显示音频统计信息
- **F6**: 切换环境音频
- **F7**: 应用混响效果
- **F8**: 应用回声效果
- **F9**: 创建测试区域
- **F10**: 切换多普勒效应
- **F11**: 切换HRTF
- **F12**: 显示详细统计信息

### GUI界面操作
插件会在屏幕左上角创建控制面板，右上角创建编辑器面板，可以通过按钮直接操作音频功能。

### 编程接口
```python
# 获取插件实例
audio_plugin = world.plugin_manager.get_plugin("spatial_audio")

# 创建3D音效
sound_id = audio_plugin.create_3d_sound(
    "sounds/footsteps.wav", 
    (10, 0, 5),     # 位置
    False,          # 循环
    0.8,            # 音量
    1.0,            # 最小距离
    100.0,          # 最大距离
    1.0             # 衰减因子
)

# 创建2D音效
music_id = audio_plugin.create_2d_sound("sounds/background_music.mp3", True, 0.6)

# 播放音效（支持淡入）
audio_plugin.play_sound(sound_id, fade_in_time=1.0)

# 设置音源位置
audio_plugin.set_sound_position(sound_id, (15, 0, 8))

# 设置音量
audio_plugin.set_sound_volume(sound_id, 0.5)

# 检查音效状态
if audio_plugin.is_sound_playing(sound_id):
    print("音效正在播放")

# 创建音频效果
reverb_effect_id = audio_plugin.create_audio_effect("reverb", {
    "reverb_time": 2.0,
    "early_reflections": 0.3,
    "late_reverb": 0.7
})

# 应用效果到音效
audio_plugin.apply_effect_to_sound(sound_id, reverb_effect_id)

# 创建环境区域
audio_plugin.create_environment_zone("cave", (0, 0, 0), 20.0, {
    "reverb": 0.8,
    "absorption": 0.3,
    "ambient_volume": 0.4
})

# 为区域添加环境音效
audio_plugin.environment_audio_manager.add_ambient_sound_to_zone(
    "cave", "sounds/cave_ambience.wav", 0.4, True)

# 设置听者位置
audio_plugin.set_listener_position((5, 0, 5))

# 设置听者方向
audio_plugin.set_listener_orientation((0, 0, 0))

# 停止音效（支持淡出）
audio_plugin.stop_sound(sound_id, fade_out_time=1.0)

# 删除音效
audio_plugin.delete_sound(sound_id)

# 使用预设效果
cathedral_reverb = audio_plugin.create_preset_effect("cathedral_reverb")
audio_plugin.apply_effect_to_sound(sound_id, cathedral_reverb)

# 设置主音量
audio_plugin.set_master_volume(0.8)

# 绑定音效到对象
audio_plugin.attach_sound_to_object(sound_id, character_node)

# 添加区域回调
def on_enter_zone(zone_id):
    print(f"进入区域: {zone_id}")
    
audio_plugin.add_zone_enter_callback("cave", on_enter_zone)
```

## 核心组件

### 音频源管理器
负责音频源的创建、播放和控制。

主要功能：
- 3D和2D音效创建
- 音频播放控制（播放、暂停、停止）
- 音源位置和属性设置
- 音频状态查询
- 资源管理和缓存
- 淡入淡出效果

### 音频效果处理器
处理各种音频效果的应用和管理。

主要功能：
- 多种音频效果创建
- 效果参数配置
- 效果应用到音源
- 效果启用/禁用控制
- 效果链管理
- 预设效果系统

### 环境音频管理器
管理环境音效和区域音频效果。

主要功能：
- 音频区域创建和管理
- 环境音效播放
- 区域属性配置
- 区域间音频切换
- 动态环境效果
- 区域状态回调

### 音频编辑器
提供可视化编辑音频场景的功能。

主要功能：
- 图形化界面编辑
- 多种编辑工具
- 场景保存和加载
- 实时预览
- 网格对齐

## 音频组件

### 音频源组件
为游戏对象添加音频播放功能。

主要功能：
- 音频文件加载
- 3D空间化处理
- 音频播放控制
- 对象绑定

### 音频听者组件
设置音频听者位置和方向。

主要功能：
- 听者位置设置
- 听者方向设置
- 对象绑定

### 音频效果组件
为音频源应用效果。

主要功能：
- 音频效果创建
- 效果参数配置
- 效果应用和移除

## 音频工具

### 距离计算
计算两点间距离用于音量衰减计算。

### 音量衰减
基于距离的音量衰减计算。

### 声道平衡
根据音源相对位置计算左右声道平衡。

### 多普勒效应
计算音源和听者相对运动引起的频率变化。

### HRTF处理
头部相关传递函数实现更真实的3D音效。

## 性能优化

### 资源管理
- **智能加载**: 根据需要动态加载音频资源
- **内存复用**: 音频缓冲区复用减少内存分配
- **自动卸载**: 不使用的音频资源自动卸载
- **缓存系统**: 音频文件智能缓存

### 处理优化
- **批量更新**: 批量处理音频源更新
- **LOD系统**: 根据距离调整处理质量
- **效果优化**: 根据重要性调整效果处理

### 内存优化
- **对象池**: 音频对象池减少GC压力
- **流式加载**: 大型音频文件流式加载
- **压缩存储**: 音频数据压缩存储

## 扩展开发

### 添加新的音频效果
1. 在[effects](file:///home/hello/EG/plugins/user/spatial_audio/effects)目录中创建新的效果处理器
2. 实现效果处理逻辑
3. 在[AudioEffectProcessor](file:///home/hello/EG/plugins/user/spatial_audio/effects/audio_effect_processor.py#L11-L94)中注册新效果

### 添加新的音频组件
1. 在[components](file:///home/hello/EG/plugins/user/spatial_audio/components)目录中创建新的组件类
2. 继承AudioComponent基类
3. 实现组件功能

### 添加新的工具函数
1. 在[utils](file:///home/hello/EG/plugins/user/spatial_audio/utils)目录中创建新的工具模块
2. 实现工具函数
3. 在需要的地方使用工具函数

## 故障排除

### 音频无法播放
1. 检查音频文件路径是否正确
2. 确认音频格式是否支持
3. 检查音频系统是否正确初始化
4. 验证音频文件是否损坏

### 3D音效不工作
1. 确认听者位置是否正确设置
2. 检查音源位置是否正确设置
3. 验证音频系统是否支持3D音效
4. 检查音频格式是否支持3D处理

### 性能问题
1. 使用音频统计功能分析性能瓶颈
2. 减少同时播放的音频数量
3. 降低音频处理质量
4. 使用LOD系统优化远处音频

### 环境音频问题
1. 检查区域定义是否正确
2. 确认听者位置是否在区域内
3. 验证环境音效文件是否正确加载
4. 检查区域属性设置

## API参考

### Plugin类主要方法

#### 初始化和控制
- `initialize()` - 初始化插件
- `enable()` - 启用插件
- `disable()` - 禁用插件
- `finalize()` - 清理插件资源
- `update(dt)` - 更新插件状态

#### 音频源操作
- `create_3d_sound(filepath, position, loop, volume, min_distance, max_distance, rolloff_factor)` - 创建3D音效
- `create_2d_sound(filepath, loop, volume)` - 创建2D音效
- `play_sound(sound_id, fade_in_time)` - 播放音效
- `stop_sound(sound_id, fade_out_time)` - 停止音效
- `pause_sound(sound_id)` - 暂停音效
- `resume_sound(sound_id)` - 恢复音效
- `set_sound_position(sound_id, position)` - 设置音源位置
- `set_sound_volume(sound_id, volume)` - 设置音源音量
- `set_sound_loop(sound_id, loop)` - 设置音源循环模式
- `is_sound_playing(sound_id)` - 检查音效是否正在播放
- `get_sound_duration(sound_id)` - 获取音效时长
- `get_sound_position(sound_id)` - 获取音源位置
- `delete_sound(sound_id)` - 删除音效
- `stop_all_sounds()` - 停止所有音频
- `attach_sound_to_object(sound_id, obj)` - 绑定音效到对象
- `detach_sound_from_object(sound_id)` - 解绑音效从对象

#### 音频效果操作
- `create_audio_effect(effect_type, parameters)` - 创建音频效果
- `apply_effect_to_sound(sound_id, effect_id)` - 应用效果到音效
- `remove_effect_from_sound(sound_id, effect_id)` - 从音效移除效果
- `create_preset_effect(preset_name)` - 创建预设效果
- `enable_audio_effects(enable)` - 启用/禁用音频效果处理

#### 听者操作
- `set_listener_position(position)` - 设置听者位置
- `set_listener_orientation(orientation)` - 设置听者方向
- `get_listener_velocity()` - 获取听者速度

#### 环境音频操作
- `create_environment_zone(zone_id, position, radius, properties)` - 创建环境区域
- `set_zone_property(zone_id, property_name, value)` - 设置区域属性
- `add_zone_enter_callback(zone_id, callback)` - 添加区域进入回调
- `add_zone_exit_callback(zone_id, callback)` - 添加区域离开回调

#### 系统控制
- `set_master_volume(volume)` - 设置主音量
- `get_master_volume()` - 获取主音量
- `set_audio_quality(quality)` - 设置音频质量
- `set_doppler_factor(factor)` - 设置多普勒效应因子
- `set_environment_occlusion(enable)` - 启用/禁用环境遮挡效果

#### 统计和信息
- `get_stats()` - 获取插件统计信息
- `get_cached_sound_files()` - 获取已缓存的音频文件列表
- `clear_sound_cache()` - 清空音频文件缓存

## 音频格式支持

支持的音频格式：
- **WAV**: 未压缩的PCM音频
- **OGG**: Ogg Vorbis压缩音频
- **MP3**: MPEG音频层III

## 性能调优建议

### 音频源管理
1. 合理控制同时播放的音频数量
2. 及时删除不需要的音频源
3. 使用对象池管理音频对象
4. 预加载常用的音频资源
5. 合理设置音频缓存大小

### 效果处理
1. 根据重要性选择效果
2. 限制同时应用的效果数量
3. 使用简化的效果处理远处音频
4. 及时移除不需要的效果

### 环境音频
1. 合理设置区域大小
2. 控制区域内环境音效数量
3. 使用LOD系统优化远处区域
4. 及时清理不需要的区域

### 内存管理
1. 定期清理音频缓存
2. 及时释放不需要的音频资源
3. 使用流式加载大型音频文件
4. 监控内存使用情况

## 版本信息

- 版本: 1.0.0
- 作者: EG Team
- 发布日期: 2024年

## 许可证

本插件遵循EG引擎许可证协议。