MCreator 生物群系气氛声音(Mood Sound)配置指南:洞穴环境音效的原理、参数与生成代码
MCreator 生物群系气氛声音(Mood Sound)配置指南:洞穴环境音效的原理、参数与生成代码
导读
Mood Sound(气氛声音)是 Minecraft 生物群系效果(effects)中的一类环境音效,用于在洞穴等场景播放低沉的环境低音(例如原版 ambient.cave)。本指南以 MCreator 官方帮助文档 mood_sound.md 为核心,结合仓库中生物群系数据模型、编辑界面与生成模板的源码实现,完整讲解在 MCreator 生物群系编辑器中配置气氛声音与延迟参数的步骤、参数取值范围,以及最终写入生物群系 JSON 的代码结构,帮助你在自制模组中复刻原版洞穴音效氛围。
一、Mood Sound 是什么:洞穴里的环境低音
根据 MCreator 的帮助文档原文定义:
The ambient sound is the sound used for caves (e.g. Ambient Caves)
即 气氛声音(Mood Sound)是专用于洞穴的场景音效,最典型的例子就是原版声音 ambient.cave。在 Minecraft 中,当玩家身处洞穴等昏暗的地下环境时,游戏会周期性地播放这类低沉、空灵的环境低音,营造出地下空间的幽深感。
MCreator 简体中文本地化对它的描述更加具体(见 texts_zh_CN.properties):
气氛声音:玩家在生物群系中至少延迟一段时间后播放
这说明 Mood Sound 的播放具有两个关键特征:
- 触发条件与洞穴环境相关:它面向洞穴/地下场景,而不是持续循环的背景音;
- 播放存在最小间隔(延迟):两次播放之间至少间隔一定时间,这个间隔由配套的
Mood sound delay参数控制,详见本文第三部分。
二、在 MCreator 中配置气氛声音
MCreator 的生物群系编辑器将声音类配置集中放在一起。打开一个生物群系元素(Biome)的编辑界面,在声音(Sounds)区域即可看到 Mood sound 与 Mood sound delay 两个配置项(源码见 BiomeGUI.java):
- Mood sound:声音选择器,用于指定实际播放的声音;
- Mood sound delay (in ticks):数值输入框,用于设置两次播放之间的最小间隔(以刻为单位)。
声音选择器的工作原理
Mood sound 使用 MCreator 通用的 SoundSelector 组件(SoundSelector.java)。点击编辑按钮会弹出声音选择对话框,其数据来源是 ElementUtil.loadAllSounds()(ElementUtil.java),最终从 sounds.yaml 数据列表中加载全部可用声音。
sounds.yaml 是 MCreator 内置的声音注册表(共约 2000 条),其中洞穴类声音包括:
- ambient.cave
- block.anvil.break
- block.anvil.destroy
...
- block.fire.ambient
...
选择器组件还支持双击文本域直接唤起编辑按钮,以及通过"移除"按钮清空当前选择:
- 双击声音文本 → 打开声音选择对话框(见 SoundSelector.java);
- 点击移除按钮 → 将
moodSound置空,生成的 JSON 中不会输出mood_sound字段。
三、参数详解:声音选择与延迟范围
Mood sound:可选声音
声音字段在数据模型中定义为 public Sound moodSound;(见 Biome.java)。它属于 Sound 类型,是 MappableElement 的子类(Sound.java),映射表为 sounds。
有一个重要的映射细节:Sound.getMappedValue() 会把 MCreator 内部前缀替换为当前工作区的 modid(Sound.java)。这意味着你不仅可以选择原版声音(如 ambient.cave),还可以选择模组自己注册的自定义声音——只要它们出现在 sounds.yaml 的映射列表中,生成时会自动带上模组 ID 前缀。
Mood sound delay:播放延迟
延迟参数在数据模型中的完整定义(Biome.java):
@Numeric(init = 6000, min = 1, max = 30000, step = 1) public int moodSoundDelay;
| 属性 | 取值 | 含义 |
|---|---|---|
| init(默认值) | 6000 | 新建生物群系时默认延迟为 6000 刻(即 300 秒 / 5 分钟) |
| min | 1 | 最小延迟为 1 刻 |
| max | 30000 | 最大延迟为 30000 刻(即 1500 秒 / 25 分钟) |
| step | 1 | 每次步进 1 刻 |
数据模型中还将其默认值显式初始化为 6000(见 Biome.java)。按 Minecraft 每刻 1/20 秒换算,默认配置下气氛声音大约每 5 分钟才播放一次,符合原版"低沉、稀有、点缀性"的环境音设计。
配套帮助文档 mood_sound_delay.md 的定义为:
This value defines the time, in ticks, before the sound is played (loop).
即该值定义了两次(循环)播放之间间隔的刻数。需要注意:这里的"延迟"不是首次播放前的等待,而是每次播放之间的最小间隔,帮助文档中的 "loop"(循环)一词点明了这一点。
四、生成的生物群系 JSON:mood_sound 结构
配置完成后,MCreator 会通过 FreeMarker 模板把生物群系输出为数据包 JSON。生成器模板位于 biome.json.ftl,其中 mood_sound 的输出逻辑如下:
<#if data.moodSound?has_content && data.moodSound.getMappedValue()?has_content>
"mood_sound": {
"sound": "${data.moodSound}",
"tick_delay": ${data.moodSoundDelay},
"offset": 8,
"block_search_extent": 2
},
</#if>
可以看到生成的 mood_sound 对象包含四个字段:
| 字段 | 来源 | 说明 |
|---|---|---|
sound |
用户选择的 Mood sound | 实际播放的声音,映射后自动带 modid 前缀 |
tick_delay |
用户配置的 Mood sound delay | 两次播放之间的最小间隔(刻) |
offset |
模板固定值 8 | 垂直偏移量,控制声音相对搜索位置的播放高度 |
block_search_extent |
模板固定值 2 | 方块搜索范围半径,控制环境判定范围 |
其中 offset 与 block_search_extent 由生成器固定写死,用户在 MCreator 界面中无法直接修改(见 biome.json.ftl)。从字段名可以推断,Mood Sound 的实际播放与"在玩家周围搜索环境方块 + 垂直偏移定位"的机制相关,这也是它专用于洞穴环境的原因。
生成的 JSON 文件由生物群系定义文件 biome.definition.yaml 指定输出位置:
templates:
- template: biome/biome.json.ftl
writer: json
name: "@MODDATAROOT/worldgen/biome/@registryname.json"
即输出到数据包/模组的 worldgen/biome/@registryname.json(NeoForge 生成器同样复用此模板,见 neoforge-1.21.1/biome.definition.yaml)。
只有当你选择了具体声音时,mood_sound 对象才会出现在 JSON 中;未选择时模板直接跳过该字段。
五、源码视角:数据模型与界面联动
从源码可以完整还原 Mood Sound 在 MCreator 中的完整生命周期:
1. 数据存储:Biome.java 中 moodSound 与 moodSoundDelay 是生物群系元素的持久化字段,保存于工作区的生物群系定义中。
2. 界面加载:BiomeGUI.java 创建了 SoundSelector moodSound 与延迟数值微调器 moodSoundDelay:
private final SoundSelector moodSound = new SoundSelector(mcreator);
private final JSpinner moodSoundDelay = ComponentFromAnnotation.spinner(Biome.class, "moodSoundDelay");
值得注意:延迟微调器直接通过注解反射生成(ComponentFromAnnotation.spinner),其取值范围(1–30000)、步长与默认值全部来自 Biome.java 中的 @Numeric 注解,实现"一处定义、处处生效"。
3. 读写同步:打开生物群系时,界面从数据模型回填(BiomeGUI.java):
moodSound.setSound(biome.moodSound);
moodSoundDelay.setValue(biome.moodSoundDelay);
保存时反向写回(BiomeGUI.java):
biome.moodSound = moodSound.getSound();
biome.moodSoundDelay = (int) moodSoundDelay.getValue();
六、与 Ambient Sound、Additions Sound、Music 的区别
Mood Sound 是生物群系四种背景声音之一,MCreator 的帮助文档对它们分别给出了精确定义,容易混淆,整理如下:
| 声音类型 | 帮助文档定义 | 播放特征 |
|---|---|---|
| Mood sound(气氛声音) | The ambient sound is the sound used for caves (e.g. Ambient Caves),见 mood_sound.md | 面向洞穴环境,按 tick_delay 间隔循环播放,配 offset/block_search_extent |
| Ambient sound(环境声音) | The ambient sound is constantly played in the biome,见 ambient_sound.md | 在生物群系中持续循环播放,无间隔 |
| Additions sound(补充声音) | 模板固定 tick_chance: 0.0111 |
以概率随机补充播放 |
| Music(背景音乐) | This is the music of the biome. This sound will be randomly played,见 music.md | 随机播放,模板固定 min_delay: 12000、max_delay: 24000、replace_current_music: true |
从生成模板(biome.json.ftl)可以看出四者的核心差异:
- Ambient sound 只输出一个声音字符串,意味着"一直响";
- Mood sound 带
tick_delay、offset、block_search_extent,是"周期性、带空间判定"的洞穴音效; - Additions sound 带
tick_chance,是"随机概率"点缀音; - Music 带
min_delay/max_delay区间,是"随机间隔"的背景乐。
Mood Sound 是三者的唯一一种与洞穴环境绑定的声音类型,因此如果你希望自制洞穴、矿洞、地下维度等生物群系具备原版洞穴的幽深氛围,优先配置的就是它。
七、配置实践建议
基于上述机制,在实际配置 Mood Sound 时可以参考以下做法:
- 声音选择:优先选择
ambient.cave或同类低沉环境音;如需自定义氛围音,可在工作区中注册自定义声音并使其出现在sounds.yaml映射中,生成时会自动带上modid:前缀(见 Sound.java)。 - 延迟设置:默认 6000 刻(5 分钟)适合大多数洞穴场景;若希望氛围更密集,可下调至 2000–4000 刻;若希望更稀有、更压抑,可上调至 10000 以上。范围上限为 30000 刻,步长 1 刻。
- 区分用途:需要持续背景音时使用 Ambient sound,而不是 Mood sound;两者可以同时配置,Mood Sound 负责点缀,Ambient Sound 负责铺底。
- 验证输出:生成或构建模组后,检查
@MODDATAROOT/worldgen/biome/@registryname.json中effects.mood_sound是否按预期输出sound、tick_delay、offset: 8、block_search_extent: 2四个字段。
参考资料
- 官方帮助文档:mood_sound.md、mood_sound_delay.md、ambient_sound.md、music.md
- 数据模型:Biome.java
- 编辑界面:BiomeGUI.java
- 生成模板:biome.json.ftl、biome.definition.yaml
- 声音数据列表:sounds.yaml
- 中文界面文案:texts_zh_CN.properties