Goldberg Steam Emulator（gbe_fork）Overlay 通知音效配置指南：成就解锁与好友邀请提示音的放置与触发机制

导读

本文基于 Goldberg Steam Emulator 的 gbe_fork 仓库中 sounds.EXAMPLE/README.md 编写，讲解实验性 Overlay（游戏内覆盖层）的通知音效系统：如何通过放置 overlay_achievement_notification.wav 与 overlay_friend_notification.wav 两个音频文件，让模拟器在成就解锁、好友发送邀请时播放自定义提示音。读完本文，你将掌握两个音效文件的放置位置、命名规则、触发时机、底层加载与播放流程，以及对应的开关配置，可直接在本地游戏 steam_settings 目录中落地使用。

前提说明：该功能目前仅适用于 Windows 平台的 experimental 构建（见 post_build/README.release.md），且 Overlay 本身属于高度实验性功能，可能引发崩溃或兼容性问题，使用时需自行承担风险。

一、功能概述：谁在什么时机播放什么声音

仓库在 overlay_experimental/overlay/steam_overlay.h 中维护了一张音频文件注册表：

std::map<std::string, std::vector<char>> wav_files{
    { "overlay_achievement_notification.wav", std::vector<char>{} },
    { "overlay_friend_notification.wav", std::vector<char>{} },
};

Overlay 启动时会遍历这张表，尝试从游戏配置目录加载对应的 .wav 文件；若用户未提供自定义文件，则使用仓库内嵌的默认音频（overlay_experimental/overlay/notification.h 中以字节数组形式编译进二进制的 notif_invite_wav）。两个音效文件的触发时机如下：

音频文件名	触发场景
overlay_achievement_notification.wav	成就（achievement）被解锁时播放
overlay_friend_notification.wav	好友发送邀请（invitation）时播放

触发调用的三个入口均位于 overlay_experimental/steam_overlay.cpp：

• notify_sound_user_achievement()：成就解锁通知音；
• notify_sound_user_invite()：收到好友邀请（且邀请窗口尚未展示）时播放；
• notify_sound_auto_accept_friend_invite()：启用“自动接受好友邀请”功能时的提示音。

它们分别被成就通知逻辑（steam_overlay.cpp 附近）、好友窗口状态更新（steam_overlay.cpp、steam_overlay.cpp、steam_overlay.cpp）等位置调用。也就是说：只要游戏中出现成就解锁事件或好友邀请事件，Overlay 通知出现的同时就会触发对应音效（旧版本曾一度在 Overlay 可见时静音，该限制已被移除，见 CHANGELOG.md）。

二、文件放置位置：本地目录与全局目录

2.1 两个可选放置位置

按 sounds.EXAMPLE/README.md 与 post_build/README.release.md 的说明，音效文件可放在两个位置之一：

1. 游戏本地目录：<游戏根目录>/steam_settings/sounds/
2. 全局设置目录：GSE Settings/settings/sounds/（即模拟器全局配置目录下的 settings/sounds）

2.2 底层加载顺序

源码中的加载逻辑实现了“本地优先，全局兜底”的策略（见 overlay_experimental/steam_overlay.cpp）：

// try local location first, then try global location
for (const auto &settings_path : { Local_Storage::get_game_settings_path(), local_storage->get_global_settings_path() }) {
    file_path = settings_path + Steam_Overlay::ACH_SOUNDS_FOLDER + PATH_SEPARATOR + kv.first;
    file_size = file_size_(file_path);
    if (file_size) break;
}

其中 ACH_SOUNDS_FOLDER 定义为字符串 "sounds"（overlay_experimental/overlay/steam_overlay.h）。加载流程可以归纳为：

1. 先在游戏本地 steam_settings/sounds/ 下查找对应文件名；
2. 找到则读取文件内容到内存（分配 file_size + 1 字节，额外 1 字节作为后续按 C 字符串处理的空终止符）；
3. 未找到则回退到全局 GSE Settings/settings/sounds/ 目录；
4. 两处都找不到时，wav_files 中对应条目保持为空，播放时自动使用内嵌默认音效。

这一“本地优先、全局兜底”的设计沿用自 2024/4/11 的变更（CHANGELOG.md）：当时 Overlay 音频加载被正式切分为 steam_settings/sounds 与 Goldberg SteamEmu Settings/settings/sounds 两个子目录，属于破坏性变更。若你的配置来自更早版本，需要把旧的音频文件迁移到 sounds 子目录中。

2.3 迁移工具行为提示

仓库自带的 GSE 配置迁移工具 tools/migrate_gse/main.py 在迁移时不会复制 overlay 的字体/音效等额外资源，只生成对应的 .ini 开关文件（tools/migrate_gse/README.md）。因此使用迁移工具后，仍需手动把自定义音效放置到 sounds 子目录。

三、命名与音频格式要求

3.1 文件名必须精确匹配

文件名必须与注册表完全一致，区分大小写，不能改名、不能省略扩展名：

• overlay_achievement_notification.wav
• overlay_friend_notification.wav

播放时源码通过 wav_files.find("overlay_achievement_notification.wav") / wav_files.find("overlay_friend_notification.wav") 精确查找（overlay_experimental/steam_overlay.cpp），并检查数据长度非零才播放，因此放错名字的文件会被静默忽略。

3.2 格式要求：Windows PCM WAV

播放调用使用的是 Windows 多媒体接口 PlaySoundA，并带有 SND_ASYNC | SND_MEMORY 标志（overlay_experimental/steam_overlay.cpp）：

PlaySoundA((LPCSTR)&wav_data->second[0], NULL, SND_ASYNC | SND_MEMORY);

PlaySound 的 SND_MEMORY 模式意味着文件内容会被整体读入内存后播放，且该 API 只支持波形文件（WAV）。为保证兼容，建议使用标准的未压缩 PCM WAV 格式（如 16-bit、44.1kHz 单声道或立体声）。可先用常见的音频工具/在线转换器把 mp3、ogg 等格式转成 PCM WAV 再放入 sounds 目录。仓库自带的两个示例文件为公版音效 "A Tone"（见 sounds.EXAMPLE/LICENSE.md），可先复制测试，确认通路正常后再替换为自己的音频。

3.3 目录结构示例

完整配置目录结构示意如下：

<游戏根目录>/
├── steam_settings/
│   ├── configs.overlay.ini
│   └── sounds/
│       ├── overlay_achievement_notification.wav   ← 成就解锁音
│       └── overlay_friend_notification.wav        ← 好友邀请音

四、启用 Overlay 与开关控制

4.1 先启用实验性 Overlay

音效只有在实验性 Overlay 功能启用后才会生效。在游戏本地 steam_settings/configs.overlay.ini（模板见 configs.overlay.EXAMPLE.ini）的 [overlay::general] 段设置：

[overlay::general]
# 1=enable the experimental overlay, might cause crashes
# default=0
enable_experimental_overlay=1

Overlay 启用后，游戏内按 SHIFT-TAB 打开 Overlay（post_build/README.release.md）。建议同时关注同段下的 hook_delay_sec（渲染器探测前的等待秒数，默认 0）与 renderer_detector_timeout_sec（渲染器探测超时，默认 15）等参数，它们影响 Overlay 注入是否成功，进而影响通知音效能否触发。

4.2 音效开关：两个独立选项

<a href="https://link.gitcode.com/i/0aee8881a449f6316b2f709dde9dc094" target="_blank">overlay::general] 段还提供两个与音效直接相关的开关（[configs.overlay.EXAMPLE.ini）：

# 1=disable the achievements notifications
# default=0
disable_achievement_notification=0
# 1=disable friends invitations and messages notifications
# default=0
disable_friend_notification=0

• disable_achievement_notification：设为 1 时关闭成就通知及成就解锁音（对应 notify_sound_user_achievement 入口的提前 return，见 steam_overlay.cpp）；
• disable_friend_notification：设为 1 时关闭好友邀请/消息通知及邀请音（对应 steam_overlay.cpp）。

这两项默认均为 0，即默认开启通知音效。相关解析代码位于 dll/settings_parser.cpp，读取后存入 dll/dll/settings.h 的 disable_overlay_achievement_notification 与 disable_overlay_friend_notification 布尔字段，供 Overlay 运行时查询。

4.3 其他影响体验的相邻配置

同一 [overlay::general] 段中还有几个与通知显示相关的选项，可按需调整以配合音效体验：

• disable_achievement_progress：关闭成就进度条通知（默认 0）；
• disable_warning_any / disable_warning_bad_appid / disable_warning_local_save：关闭 Overlay 内各类警告弹窗（默认均为 0）。

五、底层播放流程与验证方式

5.1 完整调用链

从配置到出声音的完整链路可以概括为：

1. settings_parser.cpp 解析 configs.overlay.ini，得到两个 disable_*_notification 开关；
2. Overlay 初始化时调用 load_audio()，按“本地 → 全局”顺序把两个 .wav 读入 wav_files 内存映射；
3. 游戏内触发成就解锁 / 好友邀请事件时，Overlay 通知逻辑调用对应的 notify_sound_user_* 入口；
4. 入口先检查对应 disable_*_notification 开关，未禁用则查找 wav_files 中的音频数据；
5. 找到则 PlaySoundA(..., SND_ASYNC | SND_MEMORY) 异步播放，未找到则回退到内嵌默认音 notif_invite_wav（仅好友邀请音有此回退，成就音未提供内嵌回退）。

从源码结构看，好友邀请音（notify_sound_user_invite 与 notify_sound_auto_accept_friend_invite）在自定义文件缺失时会回退到内嵌的 notif_invite_wav；而成就音（notify_sound_user_achievement）没有对应的内嵌回退，若未放置自定义文件则可能静默。

5.2 调试日志

load_audio() 中带有 PRINT_DEBUG("loaded '%s' (read %i/%u bytes)", ...) 调试输出（steam_overlay.cpp）。如果使用带调试日志的构建，可在日志中确认每个音效文件是否被成功找到及读取的字节数，这是排查“文件放对了却没声音”问题的第一步。

5.3 常见排查清单

若放置音效后未听到声音，可按以下顺序检查：

1. 版本限制：确认使用的是 Windows 平台的 experimental 构建；
2. Overlay 已启用：configs.overlay.ini 中 enable_experimental_overlay=1；
3. 文件命名：与注册表完全一致，包含 .wav 扩展名；
4. 目录位置：位于游戏本地 steam_settings/sounds/ 或全局 GSE Settings/settings/sounds/；
5. 音频格式：标准 PCM WAV，可直接被 PlaySound 播放；
6. 开关状态：disable_achievement_notification、disable_friend_notification 未被设为 1；
7. 调试日志：确认 load_audio() 打印了成功读取的字节点数。

六、小结

GSE 的 Overlay 通知音效是一个典型的“约定式资源”功能：只要把名字正确的 .wav 文件放进约定的 sounds 子目录，模拟器便会在成就解锁、好友邀请两个时机自动播放。其核心约定可以浓缩为三点：精确的文件名（overlay_achievement_notification.wav / overlay_friend_notification.wav）、指定的放置目录（本地 steam_settings/sounds 优先，全局 settings/sounds 兜底）、Windows PCM WAV 格式。配合 configs.overlay.ini 中的 enable_experimental_overlay 与两个 disable_*_notification 开关，即可在实验性 Overlay 中实现完全自定义的通知音体验。如需深入了解通知界面本身的布局、颜色与动画参数，可继续阅读 configs.overlay.EXAMPLE.ini 的 <a href="https://link.gitcode.com/i/1302c9579791a0118b3b8bb1110f421e" target="_blank">overlay_appearance] 段与 [overlay_experimental/overlay/steam_overlay.h 中的相关字段定义。