自定义音效与音乐
《我的世界》基岩版使用业界知名的 FMOD 音频引擎管理所有游戏音效与音乐。开发者可以通过在资源包中配置 sound_definitions.json 和 music_definitions.json，结合 ModSDK 脚本接口，实现自定义音效与背景音乐的添加和播放。
前置知识
阅读本文前，建议先了解 Addon 开发基础 中资源包的目录结构。
概述（FMOD 引擎）
MC 内置音频管理使用 FMOD 引擎，通过 SoundSystemFMOD 类对 FMOD API 进行封装和调用。在 Mod 中使用自定义音频有三种方式：
- Addon 数据驱动：通过 JSON 配置替换或新增音效
- ModSDK 接口调用：通过脚本控制音乐播放
- Music 指令：通过 MC 原生 music 指令触发
音频格式
当前版本仅支持 .ogg 格式的音频文件，不支持 .mp3 等其他格式。
待补充：三种方式的适用场景对比。
sound_definitions.json
在资源包的 sounds/ 目录下创建 sound_definitions.json，定义具体的音效资源内容。
{
"my_custom_sound": {
"category": "music",
"min_distance": 0.0,
"max_distance": 16.0,
"sounds": [
{
"name": "sounds/custom/my_sound",
"stream": true,
"volume": 0.5,
"load_on_low_memory": true
}
]
}
}字段说明
| 字段 | 说明 |
|---|---|
category | 音频分类（music、ui、weather 等） |
min_distance | 最小播放距离 |
max_distance | 最大播放距离 |
sounds[].name | 音频文件路径（不含扩展名） |
sounds[].stream | 是否流式加载（建议大文件开启） |
sounds[].volume | 音量大小 |
sounds[].load_on_low_memory | 低内存时是否加载 |
流式加载
当 stream 设为 true 时可减小内存占用，但同一时间内该音频只允许播放一个实例。建议较大的 BGM 音频使用流式加载。
待补充：动态加载（dy_load_list）配置说明、LRU 内存管理机制。
music_definitions.json
music_definitions.json 用于指定特定游戏场景下自动播放的背景音乐。
{
"creative": {
"event_name": "music.game.creative",
"min_delay": 60,
"max_delay": 180
}
}支持的场景键名
| 键名 | 含义 |
|---|---|
creative | 创造模式 |
game | 常规游戏 |
menu | 主菜单 |
nether | 下界 |
end | 末地 |
endboss | 末影龙 |
water | 水下 |
credits | 终末之诗 |
待补充：完整的场景键名列表。
说明
event_name 对应 sound_definitions.json 中定义的音效键名。场景键名由 MC 游戏固定，不支持自定义。
音效分类（category）
category 字段控制音效的分类，影响玩家在设置中的音量调节：
| 分类 | 说明 |
|---|---|
music | 音乐 |
ui | 界面音效 |
weather | 天气音效 |
block | 方块音效 |
hostile | 敌对生物音效 |
neutral | 中性生物音效 |
待补充：完整分类列表与自定义分类支持情况。
音效触发
游戏中音效的触发方式包括：
- 自动触发：通过
music_definitions.json配置场景自动播放 - 指令触发：使用
/music指令或/playsound指令 - 数据驱动：在实体或方块的 JSON 中配置音效事件
待补充：各触发方式的详细用法与优先级。
脚本播放音效
通过 ModSDK 的 customAudio 组件接口可以精确控制音效播放：
| 接口 | 说明 |
|---|---|
DisableOriginMusic | 屏蔽原生音乐 |
PlayGlobalCustomMusic | 播放全局自定义 BGM（优先级最高） |
PlayCustomMusic | 在指定位置播放音效（3D 效果） |
待补充：各接口参数说明与代码示例。
完整示例
待补充：一个包含自定义 BGM 替换和位置音效播放的完整 Mod 示例，参考 customMusicDemo。
下一步
- 了解 自定义状态效果 中粒子效果的配合使用
- 了解 Python 脚本开发 中 ModSDK 接口的调用方式
- 查阅 ModSDK 文档中
customAudio组件接口