mtgodot-poc/audit/contracts/audio.bgm-ambience-3d.md

audio.bgm_ambience_3d —— BGM、区域环境音、角色音效、3D 监听器和前后台恢复

状态：PARTIAL

本合同检查 40250 的 2D/3D/Stream 三类声音实例、BGM 音乐状态机、区域环境声、角色动作音效、监听器坐标/方向、音量曲线、限频和前后台生命周期。判断标准是播放实例的分配、状态转换、坐标/音量公式、重复播放限制、地图卸载和恢复副作用一致；“测试能播放”不等于 SoundManager 生命周期等价。

40250 参考调用链

• MilesLib/SoundManager.cpp / SoundManager2D.cpp / SoundManager3D.cpp / SoundManagerStream.cpp
  • Create 按 2D、Stream、3D 顺序初始化驱动；Destroy 先停止音乐和 3D 实例，再关闭 listener/provider/driver。
  • 2D/3D 音效使用固定实例池，实例完成后才可复用；3D 位置按 (world-listener)/soundScale，环境声使用 ambienceSoundScale。
  • 角色音效可按 5000cm 半径过滤，并按文件名限制 0.3 秒内重复播放；StopAllSound3D 同时清空历史。
• MilesLib/SoundManager.cpp
  • BGM 维护多个 TMusicInstance，状态为 OFF、FADE_IN、FADE_LIMIT_OUT、FADE_OUT、PLAY；Update 每帧递增/递减音量，达到边界后切换状态或停止实例。
  • FadeInMusic 先淡出已有音乐；FadeOutAllMusic 为每个活动实例设置淡出；FadeLimitOutMusic 保留目标音量。
  • SaveVolume 同时把音乐和音效音量置零并保存备份，RestoreVolume 恢复两者；不是只停止或只静音 BGM。
• MilesLib/SoundManager3D.cpp / PythonSoundManagerModule.cpp
  • 暴露 PlaySound、PlaySound3D、PlayMusic、FadeIn/FadeOut、StopAllSound、音乐/音效音量、SoundScale 和 AmbienceSoundScale。
  • 3D listener 维护位置、方向、up 和速度；环境声由 CArea::UpdateAroundAmbience 每次更新。
• GameLib/Area.cpp / Area.h
  • TAmbienceInstance 从 AreaAmbienceData/Property 读取位置、范围、最大音量半径、LOOP/ONCE/STEP 和步进随机间隔。
  • LOOP 在范围内创建循环实例并按距离线性衰减；离开范围停止并清理索引。ONCE 只在进入范围时播放，STEP 按时间到期播放，离开时重置下一次时间。

当前端实现映射

• project/audio.gd
  • 已有 BGM 双播放器、UI 音效池、AudioStreamPlayer3D、listener 重定位、200/1000 缩放、音量比例曲线、.mss 60FPS 事件、角色音效距离/0.3 秒限频，以及 Area LOOP/ONCE/STEP。
  • 3D 播放器按需创建，没有 40250 固定实例池/Provider 生命周期；Godot unit_size/max_distance 衰减也不是 Miles provider 的同一声学模型。
  • BGM 使用 Tween 交叉淡入淡出，不是 TMusicInstance::Update 的逐帧状态机；加载失败时 _bgm_name 先写入，存在“资源失败后同名请求被跳过”的状态风险。
• project/bgm_director.gd / project/game_scene.gd
  • 已按 bgm_changed 和 world_reset 选曲，服务器音量优先，缺省回落 musicInfo.fieldMusic，并保存最近战场曲目。
  • 生产链已创建 Audio、BgmDirector 并在每帧更新 listener/区域环境声；地图切换时会停止 BGM，但没有完整证明参考端多音乐实例的淡出状态被逐个清理。
• project/app_lifecycle.gd
  • 已在后台保存并恢复音量、暂停树、降低 FPS，保持 BGM 名称。
  • 后台入口调用 save_volume 后同步执行 set_music_volume(0.0) 和 set_sound_volume(0.0)；恢复仍由 restore_volume 一次恢复两类音量。
• project/game_scene.gd
  • _exit_tree 在卸载 native world 前调用 Audio.shutdown()，停止 BGM/3D 音效、解绑播放器 stream 并清空声音缓存，覆盖退出时的资源释放边界。
• formats/area_data.* / extension/src/metin2_world.cpp
  • 已读取 AreaAmbienceData、.pra 属性和 playtype/range/maxvolume/playinterval，按流式 tile 暴露 ambience source；world unload 会移除来源。
  • 来源数据和播放状态由不同节点维护，地图卸载/快速切图时音频实例和来源索引的生产级清理尚未有组合测试。

分支等价矩阵

40250 判据/副作用	当前实现	结论
2D/UI/3D/Stream 三类初始化、实例复用和销毁	Audio 创建 BGM/UI/3D 节点，使用 Godot 动态播放器	部分等价；缺少固定实例池、Miles provider/driver 生命周期和完整销毁证据
BGM 多实例 OFF/FADE_IN/FADE_LIMIT_OUT/FADE_OUT/PLAY 状态机	双播放器 Tween 交叉淡入淡出	部分等价；目标可听结果近似，但状态/边界/多个音乐实例和每帧速度公式不一致
FadeIn 先处理旧曲、FadeLimitOut、FadeOutAll	有对应方法和淡出 Tween	部分等价；没有逐实例状态快照和停止时序证明，加载失败状态回滚也不完整
音量比例/等级曲线、音乐/音效独立音量	ratio_to_apply_volume、grade 和 UI 设置测试通过	基础公式等价；后台 BGM/SFX 同时静音与恢复已有回归，真实 3D 播放实例仍需独立证据
SaveVolume/RestoreVolume 同时静音和恢复 BGM/SFX	保存两类值，后台同时调用 set_music_volume(0)/set_sound_volume(0)，前台调用 restore_volume	基础行为等价；真实 Miles provider 实例和 3D 播放器清理仍需独立证据
listener 位置/方向、200/1000 缩放和 3D 播放	GameScene._process 更新 listener，Audio 重定位实例	部分等价；单位与主要公式存在，Godot attenuation/provider 行为不是 Miles 1:1
角色动作 .mss 事件、5000cm 距离和 0.3s 限频	PlayerView/Audio 已实现，相关测试通过	基础路径通过；远端角色、全部动作事件和实例池耗尽/失败回退未覆盖
Area LOOP/ONCE/STEP、距离衰减和离开范围清理	world source + update_ambience_sources 已实现	部分等价；A3 真实来源测试通过，但快速换图、音频实例释放和多 source 乱序缺少证据
地图 BGM/区域声/音效在切图、失焦、暂停、重连后恢复	BGM 停止、listener/ambient 每帧更新、后台 BGM/SFX 恢复存在	部分等价；跨图活动实例清理和真实 3D 播放器释放尚未形成生产级闭环

已执行测试

• project/audio_miles_test.gd：通过；覆盖 200/1000 缩放、音量曲线、.mss 解析、角色音效距离/限频和环境声实例基本路径。
• project/ambience_test.gd：通过；A3 真实地图来源解析出 1 个 LOOP 环境声，范围、类型和声音路径保持。
• project/bgm_test.gd：通过；覆盖地图 BGM 选曲、服务端音量、默认回落、换图信号，以及前后台 BGM/SFX 音量保存、同时静音和恢复。
• project/rendering_scenario_test.gd：通过；Debug 原生库退出无 ObjectDB 音频资源泄漏，验证 GameScene._exit_tree -> Audio.shutdown 的退出边界。
• project/test_bgm_jukebox_parity.gd：18 passed、0 failed；覆盖点唱机曲目注册、停止、音量钳制、地图默认和覆写恢复，不覆盖真实 Audio 实例状态机。
• project/app_flow_lifecycle_test.gd：通过；覆盖 AppLifecycle 单一属主和断线重连流程，不覆盖真实音频实例释放。
• project/system_option_ui_test.gd：通过；覆盖音量设置控件绑定，不覆盖后台和播放失败边界。

Deep audit round 2026-09-21

Fresh regression results

• audio_miles_test.gd、ambience_test.gd、bgm_test.gd、test_bgm_jukebox_parity.gd 18/18、app_flow_lifecycle_test.gd、system_option_ui_test.gd 均退出码 0。
• 回归覆盖了 3D 缩放/限频、A3 环境声、地图 BGM 选择、点唱机覆盖/恢复、生命周期属主和设置绑定；FakeAudio 仍不能证明真实播放实例状态机。

Static parity conclusion

• BGM/区域环境声/角色 .mss 音效的主要入口存在，但 Godot 动态播放器/Tween 不等价于 40250 固定实例池、Provider 和 TMusicInstance 状态机。
• app_lifecycle.gd 后台路径已同步静音并恢复 BGM/SFX；加载失败后 _bgm_name 可能阻止同名重试，跨图快速切换时来源索引和播放器释放仍缺少生产级证据。
• listener、缩放和 0.3s/5000cm 规则有局部验证，但远端 Actor 动作音效、实例池耗尽、失焦/暂停/重连/退出清理和 Godot attenuation 与 Miles provider 的边界未闭合。

Active source group review

• 对 Visual Studio MilesLib 活跃编译单元逐组核对后，参考链补充确认：CSoundManager2D/3D/Stream::Initialize/Destroy 创建并释放固定实例池；CSoundData 维护 pack-backed 数据缓存和 access/play time；CSoundInstance2D/3D/Stream 分别处理 SetSound、Play/Stop、位置/方向/速度与音量；CSoundManager 负责 listener、距离缩放、0.3 秒限频、环境声、音乐实例索引和多状态淡入淡出。
• 当前端 Audio 的动态播放器和 Tween 只覆盖可听结果的部分路径，尚未证明固定池、sound data cache、播放失败/空槽、逐实例停止和 MusicIndex 状态机等副作用一致；本组静态核对完成，合同仍为 PARTIAL。

Implementation fix round 2026-09-22T08:50Z

• 修复前 bgm_test.gd 新增的 40250 SaveVolume 回归失败：进入后台后 master_bgm=0，但 master_sfx=0.9。
• 按 CSoundManager::SaveVolume 的顺序，AppLifecycle._enter_background 在保存备份后同时调用 set_music_volume(0.0) 与 set_sound_volume(0.0)；_exit_background 继续由 restore_volume 同时恢复两者。
• 修复后 bgm_test.gd、audio_miles_test.gd、app_flow_lifecycle_test.gd、disconnect_world_reset_test.gd、netbridge_test.gd 均通过；渲染退出回归无 ObjectDB 泄漏。
• 该轮只闭合后台音量副作用和退出音频缓存清理，BGM 多实例状态机、Miles 固定实例池、真实 3D 衰减/Provider、快速换图来源清理仍保持 PARTIAL。

本轮仍为 PARTIAL，完成后台音量和退出清理的实现及第二轮证据登记。

已确认差异和未验证项

1. 验证正在播放的 3D 实例不会绕过 master SFX，并补真实设备/实例路径的后台静音回归。
2. 建立 BGM 多实例状态快照测试，覆盖 FadeIn、FadeLimitOut、FadeOut、FadeOutAll、相同曲目重入、加载失败回滚和切图清理。
3. 明确 Godot 3D 衰减与 Miles provider 的适配边界，至少固定 unit_size/max_distance、监听器方向/速度和实例池耗尽行为。
4. 增加真实流式地图快速切换、来源删除、重复 key、LOOP/ONCE/STEP 乱序和退出时无悬挂播放器的测试。
5. 补齐远端 Actor 的动作音效触发、重连/死亡/换图清理和资源缺失回退证据。

下一轮验证入口

• 先审计 lifecycle.platform_release，核对 Windows 窗口、导出、自包含资源、崩溃处理和发布门禁。
• 回到实现阶段时，优先建立 BGM 多实例状态机和真实 3D 播放器清理测试，再处理固定实例池/Provider 的适配边界。

2026-09-22 死代码删除

以下文件只被自身测试引用、运行时从不加载，已删除；本文中以它们为实现或证据的结论作废，相关行为需按 40250 源码单元重新移植：test_bgm_jukebox_parity.gd。