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界面操作

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

编程接口

# 获取插件实例
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目录中创建新的效果处理器
2. 实现效果处理逻辑
3. 在AudioEffectProcessor中注册新效果

添加新的音频组件

1. 在components目录中创建新的组件类
2. 继承AudioComponent基类
3. 实现组件功能

添加新的工具函数

1. 在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引擎许可证协议。