来源: doc/SOUNDPACKS.md src/sound_backend.h src/sdlsound.h src/sounds.h tests/sound_backend_test.cpp commit d32b9cc880a8 source-and-tests

Sound 与 soundpack

CCB 区分玩法 sound event 与音频 sample playback。sounds namespace 记录用于 hearing、AI 与 marker 的 simulation event；sfx/backend 把 ID/variant 映射到 file、playlist、channel、 attenuation 与 SDL playback。

权威路径

• src/sounds.* 定义玩法 sound category 与 event processing；
• src/sound_backend.h 和 SDL2/SDL3 backend 实现定义 device/sample 行为；
• src/sdlsound.* 协调初始化、soundset load、music 与 shutdown；
• doc/SOUNDPACKS.md 解释 pack metadata/JSON，data/sound/Menu_Sound_Test/ 是小型 checked example/fixture。

ID、variant 与所有权

code/data 发出稳定 sound ID、variant 与 context，soundpack 将其映射到有许可证音频。即使 关闭 SOUND 或 device init 失败，玩法 event 仍须工作；audio playback 不能成为 simulation 权威。

贡献流程

每个 sample 记录原始 source、creator、license、edit、loop 状态、format 与 attribution。 normalize 只能使用已记录流程。更新 mapping/fallback variant，绝不硬编码本地绝对路径。

验证

验证 soundpack JSON/引用 file、exact/fallback variant、playlist、loop/fade、channel/group、 indoor/night/season、angle/volume、missing sample diagnostic、device init failure、SDL2/SDL3 与 no-sound build；适用时运行 sound backend test。

性能与打包

preload policy、decoded sample size、同时 channel 数和重复 variant resolution 影响内存/ frame time。只打包可分发 asset 并保持大小写路径。大型第三方 soundpack 除非政策/license 明确允许，应独立分发。

CCB 边界

CCB 可能与上游共享历史 ID，但当前发出的 context 与 bundled mapping 才是契约。移植要 按 CCB event 验证，不能假设上游 soundpack 已完整覆盖。