rfxgen

rFXGen

何时使用此技能

• 根据命名预设生成精简的复古／芯片音乐音效。
• 在桌面 UI 中调整并保存 .rfx 参数文件。
• 将 .rfx 转换为 .wav、.qoa、.raw 或 C 头文件数据。
• 批量生成音效，或诊断 rFXGen 源码构建问题。

将编码 Agent 通知包交给 game-sounds。素材生成后，将运行时事件架构和引擎播放集成交给特定引擎的音频技能。

说明

步骤 1：定义素材规范

记录游戏事件、预设系列、输出格式、采样率、采样位数、声道数、时长／风格约束、循环行为、命名和运行时目标。生成完整音效包之前，先制作一个有代表性的音效。

在所检查的版本中，上游支持的生成预设如下：

coin laser explosion powerup hit jump blip

支持的格式值包括采样率 22050|44100、采样位数 8|16|32，以及声道数 1|2。

步骤 2：优先使用现有二进制文件或在线工具

bash .agent-skills/rfxgen/scripts/setup.sh --check

如果不需要本地安装，可使用官方 WebAssembly 工具进行快速交互式设计。只有在需要可复现的 CLI 或代码变更时，才从源码构建。

bash .agent-skills/rfxgen/scripts/setup.sh --clone
bash .agent-skills/rfxgen/scripts/setup.sh --build

如果 raylib 尚不可用，上游 CMake 项目会获取 raylib，因此构建可能需要网络访问和平台开发库。

步骤 3：通过经过验证的包装脚本生成

bash .agent-skills/rfxgen/scripts/generate.sh \
  --preset explosion --output assets/sfx/explosion.wav \
  --format 44100,16,1

该包装脚本会在调用 rfxgen 前验证预设、扩展名和格式。如果二进制文件不在 PATH 中，请设置 RFXGEN_BIN。

步骤 4：有针对性地转换或导出

原生 CLI 可通过 --input 接受 .rfx 和受支持的音频输入，并输出 .wav、.qoa、.raw 或 .h。如果之后还需要调整，请将 .rfx 与导出的音频一并保留。仅当目标构建适合嵌入字节数据时才使用 .h；否则优先采用外部素材工作流。

步骤 5：集成为事件驱动的音效包

按抽象的游戏事件命名素材，而不是按实现中的调用位置命名。让响度和频率范围保持足够差异，以便快速辨识。测试常见的重叠播放情况、重复触发、暂停／恢复和低音量播放。

步骤 6：验证可观察到的输出

对于每个生成的素材：

• 确认文件存在且非空；
• 使用 ffprobe 或同类工具检查采样率、位深和声道数；
• 在目标硬件上试听；
• 确认没有削波或非预期的长尾音；
• 确认游戏事件触发了语义正确的音效；
• 分发源码或修改版 rFXGen 代码时，保留署名／许可证信息。

示例

生成单声道跳跃音效

bash .agent-skills/rfxgen/scripts/generate.sh \
  --preset jump --output jump.wav --format 22050,16,1

转换已调整的参数

rfxgen --input tuned-hit.rfx --output tuned-hit.wav --format 44100,16,1

最佳实践

1. 为每个语义明确的游戏事件设计一个音效。
2. 保留 .rfx 源文件，以便迭代。
3. 除非立体声能传递有意设计的信息，否则使用单声道。
4. 试听重复和重叠播放效果，而不只是单独播放的文件。
5. 固定源码构建版本，并保留 zlib 许可证声明。

参考资料

• references/cli-and-build.md — CLI 对照表、构建说明和验证清单。
• references/upstream.md — 检查的版本和许可证。
• rFXGen
• 官方 WebAssembly 工具