音效系统 · 使用说明

〇它是干什么的

先花 30 秒建立直觉，再动手写。

RevSound.Play("ui_click");                        // ① 2D：界面音、提示音、语音 —— 直接播
RevSound.PlayOn("skill_cast", hero.gameObject);       // ② 3D：挂到物体上（跟着它，物毁音停）
RevSound.PlayBgm("login", fadeSeconds: 1f);       // ③ 背景音乐（自动替换上一首，可淡入）

一条声音的一生

它不干什么（同样重要）

• 不做查询：没有"现在有几条在播""卡在哪一步"这类 API —— 想知道就订阅 RevSound.Failed / RevSound.VoiceFinished 自己记。
• 不打日志：框架自身一条日志都不打，失败一律走 Failed 事件（等框架的日志系统出来再统一接）。
• 不管资源生命周期：音效片段加载后会常驻，直到你 RevSound.Unload(...) / UnloadAll()。

13 分钟跑起来

三步：把音频放对地方 → 一行播放 → （可选）调音量。

① 音频放哪：在打包工具窗口里选（代码里不写死）

菜单 Revolution.Tools/资源/RevAB 打包工具 → 「打包」页签 → 资源目录 → 音效目录：把文件夹拖进槽里，或点「选择…」，或点「默认」。

子目录：随便建，名字里带上就行

音效名本身就是"相对音效根目录的资源路径"，支持任意层子目录 —— 不需要为子目录做任何配置。

• 子目录名直接进 同帧去重 / 上限淘汰 / 句柄 的判定："UI/click" 与 "Battle/click" 是两条不同的声音；
• 手写习惯会被自动规范化：Play("UI\click")（Windows 反斜杠）、Play("/UI//click/")（多余斜杠）都能正确加载 （规范化实现在资源系统的 RevResPathUtil.NormalizeResName，纯 C#、其它模块也能复用）；
• 打包窗口里「音效目录」下面会列出当前已有的子目录（含多级），照着抄就行。

RevSound.Play("Audio/Sfx/UI/click");
// 拼成 Audio/Sfx/Audio/Sfx/UI/click
// → Failed(LoadFailed)

RevSound.Play("UI/click");
// 根目录由打包窗口配置，不写进名字

② 一行播放

// 2D：直接播（界面音、提示音、语音、播报 —— 不会因为距离变小声）
RevSound.Play("ui_click");
RevSound.Play("vo_hello", kind: RevSoundKind.Voice);

// 3D：挂到物体上（技能、脚步、引擎 —— 有距离衰减，跟着物体走）
RevSound.PlayOn("skill_cast", hero.gameObject);
RevSound.PlayOn("run_loop", transform, loop: true);

// 3D：挂在世界坐标点（爆炸、落地 —— 不跟随任何物体）
RevSound.PlayAt("explosion", hitPoint);

// 背景音乐
RevSound.PlayBgm("login", fadeSeconds: 1f);

③ 要停就拿着句柄

RevSoundHandle h = RevSound.Play("vo_hello");
h.Stop();                                   // 停掉这一条
if (h.IsEmpty) { /* 这次播放没发生：被策略拦下 / 超上限 / 系统关闭 / 加载失败 */ }

RevSound.StopAll(fadeSeconds: 0.3f);     // 停掉所有（切场景/退战斗）

2"我要做 X" 对照表

照着抄就行。这一页覆盖 95% 的日常需求。

四类声音的默认行为

可选增强：音效表（逻辑名 → 真实路径）

磁盘目录怎么整理、美术怎么改名，调用点都不想跟着改 —— 那就把映射登记到表里（做了这件事，代码里就只出现"逻辑名"）。

// ① 登记一次（建议在初始化 / 加载界面时；同名重复登记 = 覆盖）
RevSound.Register("ui_click",  "UI/Button/click",  kind: RevSoundKind.Ui, volume: 0.8f);
RevSound.Register("vo_hello",  "Voice/Hero_1001/vo_hello", kind: RevSoundKind.Voice);
RevSound.Register("run_loop",  "Sfx/Run/loop",     loop: true);
RevSound.Register("login_bgm", "Lobby/login",      kind: RevSoundKind.Bgm);

// ② 之后代码只认逻辑名
RevSound.Play("ui_click");                  // → Audio/Sfx/UI/Button/click
RevSound.PlayOn("run_loop", transform);     // → Sfx/Run/loop，并且自动循环
RevSound.PlayBgm("login_bgm", fadeSeconds: 1f);
RevSound.PreloadAll();                      // 表里所有音效一次性预加载（各按自己的分类选根目录）

32D 还是 3D：三种播放方式

先记一句话：2D 直接播；3D 必须说清楚"声音从哪发出"。

三种写法逐个讲透

RevSound.Play("ui_click");                                   // 默认 Sfx 分类
RevSound.Play("ui_click", kind: RevSoundKind.Ui);            // 界面音：同帧去重更严
RevSound.Play("vo_hello", kind: RevSoundKind.Voice);         // 语音：不去重
RevSound.Play("ui_click", volume: 0.6f);                  // 这一次小一点声

RevSound.PlayOn("skill_cast", hero.gameObject);                   // 挂在英雄身上（一次性）
RevSound.PlayOn("run_loop", transform, loop: true);            // 挂在 transform 上（循环）
RevSound.PlayOn("npc_talk", npc.transform, volume: 0.8f, kind: RevSoundKind.Voice);

RevSound.PlayAt("explosion", hitPoint);
RevSound.PlayAt("footstep", transform.position, volume: 0.5f);

层级差别（一眼看懂）

RevSoundRoot
├── RevSoundVoice   ← 2D：spatialBlend = 0
└── RevSoundVoice
（与场景物体无关，永远听得清）

Hero（目标物体）
└── RevSoundVoice   ← 3D：spatialBlend = 1
    (localPosition = 0)
（跟着英雄跑；英雄没了，声音就停）

3D 的 4 条行为（必须知道）

最容易写错的一处

RevSound.Play("skill_hit");
// 技能音变成了 2D：不管距离
// 永远满音量（还以为出了 bug）

RevSound.PlayOn("skill_hit", enemy.gameObject);
// 或只是某个点：
RevSound.PlayAt("skill_hit", hitPoint);

4BGM / 音量 / 开关 / 预加载

把"手感"调好的四个旋钮。

背景音乐

// 播（2D、循环；再调一次会替换上一首）
RevSound.PlayBgm("login");                    // 硬切
RevSound.PlayBgm("battle", fadeSeconds: 1.5f); // 旧歌淡出、新歌淡入（同时进行，不突兀）

// 歌单：一首播完自动下一首，最后一首播完停止
RevSound.PlayBgmList("login_1", "login_2", "login_3");

// 停（可淡出；同时结束歌单）
RevSound.StopBgm(fadeSeconds: 0.8f);

音量：最终音量 = 单次音量 × 分类音量 × 主音量

预加载：把"首次晚一点"提前解决

RevSound.Preload("ui_click", "ui_close", "ui_open");   // 进界面前调一次
RevSound.PreloadBgm("battle");                          // BGM 也可以预加载

RevSound.Unload("ui_click");                          // 不用了：还引用，下次播放会重新加载
RevSound.UnloadAll();                                   // 回登录 / 大版本切换

策略：把"该不该播"留在业务

public sealed class BattleSoundPolicy : IRevSoundPolicy
{
    // 返回 false：这次播放被拦下，并触发 Failed(PolicyRejected)
    public bool CanPlay(string name, RevSoundKind kind)
        => kind != RevSoundKind.Bgm || name.StartsWith("battle_");   // 举例：战斗中只放战斗 BGM
}

RevSound.Policy = new BattleSoundPolicy();

5一块播、一块停（作用域）

把"切界面/一局结束时该收声"从散落各处的 Stop 变成一块边界。

using (var s = RevSound.OpenScope())
{
    s.Play("ui_open_big");                          // 2D：弹窗音
    s.PlayOn("npc_talk", npc.gameObject);           // 3D：挂在 NPC 身上
    s.PlayBgm("battle_prepare", fadeSeconds: 0.5f); // 这一段的 BGM

    s.StopAll();                                        // （可选）中途一键停，作用域还能接着用
}   // ← 出块：上面播的（含 BGM）全部停掉

它解决的现实问题

6新手最容易白干的 10 个坑

十个坑，每个都对应一条"我明明写了却没反应"。

7没声音怎么查（5 分钟定位）

先接上 Failed 事件 —— 这一条能定位 90% 的问题。

第 0 步：把失败原因接出来（一行）

RevSound.Failed += (name, reason) => YourLog.Warn($"[音效] {name} 没播：{reason}");

失败原因表

按顺序查

1. 看 Failed 事件：有原因就照着上表处理，不用猜。
2. LoadFailed 时查路径：窗口里配的目录（常量值见 RevSoundPath.cs，RevSoundPath.Sfx / Bgm）+ 名字 拼出来的路径对不对？ 编辑器下走 AssetDatabase，运行时走 AB 映射（ResMap）—— 音频文件有没有被打进包（AB 标记）？
3. 看整体状态：RevSound.Core.ToString() → RevSoundCore(活跃 3/24，BGM=login)。
4. 3D 听不到：确认用的是 PlayOn（目标有效、在场景里、没被隐藏）或 PlayAt（坐标对不对）；听距范围默认 1~50 米（Set3DRange）。
5. 2D 听着"有远近"：不会 —— 2D 的 spatialBlend = 0。听起来有衰减，说明这条是走 3D 播的。
6. 一切正常但就是不动：确认它真的在被推进 —— 如果你自己调过 RevSound.Tick，就要保证每帧都调（调过一次，自动宿主就永久让位了）。

8一页速查卡

打印出来贴在显示器旁边，写代码时不用回来翻文档。

播放

音量与开关

观察（框架不做查询，都在回调里）

目录配置（不进代码）

9附：设计来源与早期实现对照

给"想改它 / 想评审它"的人：这套东西是从哪来的、丢掉了什么。

向参考实现音效系统学的（精华）

丢掉的（糟粕）

早期实现 MusicMgr（714 行）迁移对照

规模与验证