MCreator 结构生成阶段(Generation Step)完全指南:从 GUI 配置到世界生成 JSON
MCreator 结构生成阶段(Generation Step)完全指南:从 GUI 配置到世界生成 JSON
导读
在 MCreator 中创建自定义结构时,"生成阶段(Generation step)"决定了该结构在 Minecraft 世界生成管线(world generation pipeline)的哪一个环节被放置到世界中。本文以 MCreator 帮助文档 generation_step.md 为核心,结合仓库源码、数据列表与生成器模板,完整讲解生成阶段的概念、全部可选取值、GUI 配置位置、底层数据模型以及最终生成的 JSON 代码,帮助你为地表村庄、地下遗迹、湖泊或植被等不同类型的结构选择正确的生成时机。
什么是结构生成阶段
原文档对这一选项的定义是一句话:
Diese Option legt fest, in welchem Stadium der Weltgenerierung die Struktur hinzugefügt werden soll. (该选项决定结构在世界生成过程中的哪个阶段被添加。)
这句话背后对应着 Minecraft 世界生成的一个核心机制:当区块被生成时,游戏并不是"一次性"把地形、建筑、矿石、植被全部摆好,而是按照一组**有序的阶段(generation steps)**依次执行。每一个阶段只负责一类生成任务——先塑造地形,再放置矿石,最后点缀植被。因此,结构(Structure)和特性(Feature)必须被挂到某个阶段上,游戏才知道应该在哪一步调用它。
在 MCreator 中,这一选项同时服务于两种元素类型:
- 结构(Structure)元素:通过数据包模板生成
minecraft:jigsaw结构放置配置,其中的"step"字段直接取自该选项; - 特性(Feature)元素(NeoForge 端):通过生物群系修改器(Biome Modifier)的
"step"字段控制特性注入时机。
可选的 12 个生成阶段
MCreator 将可选项维护在数据列表文件 generationsteps.yaml 中。该列表共 12 项,且列表顺序即 Minecraft 世界生成阶段的标准执行顺序(先地形、后装饰、最后顶层修饰):
| 阶段(Generation Step) | 数据列表中的图标纹理 | 原版语义(放置时机) |
|---|---|---|
RAW_GENERATION |
STONE#0 |
原始生成阶段,最早的地形/基岩塑造阶段 |
LAKES |
LAVA |
湖泊阶段(水湖、熔岩湖) |
LOCAL_MODIFICATIONS |
AMETHYST_BLOCK |
局部地形修饰(如紫晶晶洞等局部结构) |
UNDERGROUND_STRUCTURES |
MOB_SPAWNER |
地下结构阶段(如废弃矿井、化石等) |
SURFACE_STRUCTURES |
LOG#0 |
地表结构阶段(如村庄、沉船、掠夺者前哨站等) |
STRONGHOLDS |
STONEBRICK#0 |
要塞阶段 |
UNDERGROUND_ORES |
DIAMOND_ORE |
地下矿石生成阶段(如钻石矿、铁矿) |
UNDERGROUND_DECORATION |
NETHER_GOLD_ORE |
地下装饰阶段(矿层之外的各类地下点缀) |
FLUID_SPRINGS |
WATER |
流体泉阶段(水泉、熔岩泉) |
VEGETAL_DECORATION |
TALLGRASS#1 |
植被装饰阶段(树木、花草等) |
TOP_LAYER_MODIFICATION |
SNOW_LAYER |
顶层修饰阶段(雪层、冰面等地表覆盖) |
表中"原版语义"一列属于 Minecraft 原版世界生成管线的通用概念,用于帮助你理解各阶段的发生时机;选项本身的具体取值与顺序以仓库 generationsteps.yaml 为准。
在结构 GUI 中配置生成阶段
在 MCreator 的结构(Structure)元素编辑界面中,"Generation stage:"(生成阶段)位于主设置页中,与"生成生物群系(Biomes to spawn)""间距/分离(Separation/Spacing)""地表检测类型(Ground detection)""起始高度(Start height)"等选项并列。从界面实现源码 StructureGUI.java 可以看出,该下拉框由 DataListComboBox 构建,其候选项直接来自数据列表加载器 DataListLoader.loadDataList("generationsteps")——也就是上一节那张 12 项列表:
private final DataListComboBox generationStep = new DataListComboBox(mcreator,
DataListLoader.loadDataList("generationsteps"));
默认值:当新建一个结构元素时(非编辑模式),MCreator 会自动将生成阶段预置为 SURFACE_STRUCTURES(地表结构),对应源码 StructureGUI.java:
if (!isEditingMode()) {
generationStep.setSelectedItem("SURFACE_STRUCTURES");
...
}
保存与回读时,该下拉框的值会与元素数据模型双向同步(见 StructureGUI.java 与 StructureGUI.java),并封装为 GenerationStep 对象存入结构元素。
底层数据模型:GenerationStep 类
生成阶段在数据模型中是一个独立类型 GenerationStep,定义于 GenerationStep.java。它继承自 MappableElement,本质上是一个"可映射元素"——构造时通过 NameMapper(owner, "generationsteps") 绑定到 generationsteps 数据列表,从而保证 GUI 中选中的名称与代码生成阶段使用的一致:
public class GenerationStep extends MappableElement {
public GenerationStep(@Nonnull Workspace owner, String name) {
super(new NameMapper(owner, "generationsteps"), name);
}
}
结构元素的类型定义 Structure.java 中直接声明了该字段:
public GenerationStep generationStep;
这意味着:每个结构元素在保存时都会携带一个 generationStep 属性,供各生成器(数据包 / NeoForge)在渲染模板时读取。
生成器如何消费该配置:从配置到 JSON
生成阶段配置最终会写入世界生成相关的 JSON 文件中,转换逻辑位于生成器的 FreeMarker 模板。
数据包端(Jigsaw 结构放置配置)
在数据包生成器中,结构元素会渲染出 minecraft:jigsaw 类型的结构放置 JSON,模板 structure.json.ftl 将 generationStep 直接填入 "step" 字段:
{
"type": "minecraft:jigsaw",
"start_pool": "${modid}:${registryname}",
"size": ${data.size},
"max_distance_from_center": ...,
"spawn_overrides": {},
"step": "${data.generationStep}",
"terrain_adaptation": "${data.terrainAdaptation}",
"start_height": { ... },
...
}
也就是说,若你在 GUI 中选择了 SURFACE_STRUCTURES,最终数据包中就会出现 "step": "SURFACE_STRUCTURES",游戏会在地表结构阶段尝试放置该结构。同一逻辑也存在于 26.3.x 生成器(见 structure.json.ftl)。
NeoForge 端(生物群系修改器)
在 NeoForge 生成器中,特性通过生物群系修改器(Biome Modifier)注入,模板 feature_biome_modifier.json.ftl 同样把生成阶段写入 "step":
{
"type": "neoforge:add_features",
"biomes": ...,
"features": "${modid}:${registryname}",
"step": "${data.generationStep}"
}
数据包特性不支持生成阶段
需要特别注意的是:在数据包的 Feature 定义中,generationStep 被显式排除。见 feature.definition.yaml:
field_exclusions: [generationStep, restrictionBiomes, generateCondition]
这表明数据包特性(Feature)的生成时机不由该字段控制,而是由特性定义自身的放置规则(Placement)决定;生成阶段字段主要服务于结构元素与 NeoForge 特性。
实战选型建议
选择合适的生成阶段,取决于你的结构"应该和什么东西一起出现":
- 地表建筑(村庄、哨塔、神殿类):使用
SURFACE_STRUCTURES——它是新建结构时的默认值,也是最贴合直觉的选择; - 地下遗迹(矿井、地牢、化石类):使用
UNDERGROUND_STRUCTURES,并配合"起始高度(Start height)"等设置控制其纵向分布; - 湖泊、流体景观:使用
LAKES(大水体)或FLUID_SPRINGS(泉眼类); - 树木、花草类植被结构:使用
VEGETAL_DECORATION,使其与普通植被在同一阶段参与放置; - 矿石类特性:使用
UNDERGROUND_ORES; - 需要覆盖地表(如积雪、覆冰):使用
TOP_LAYER_MODIFICATION; - 要塞/据点类:使用
STRONGHOLDS。
在 MCreator 界面中,每个选项都配有对应的图标纹理(如地表结构为原木、地下结构为刷怪笼),便于快速辨认阶段类型;同时可结合同目录帮助文档进一步理解相邻设置:biomes_to_spawn.md(限定生成生物群系)、separation_spacing.md(生成间距)、start_height.md(起始高度)、ground_detection.md(地表检测)以及 terrain_adaptation.md(地形适应)。
小结
"生成阶段"是 MCreator 结构/特性元素中一个看似简单、实则直接影响世界生成结果的关键配置:它在数据层面对应 GenerationStep 数据类型与 generationsteps 数据列表,在界面层面对应结构 GUI 的"Generation stage"下拉框(默认 SURFACE_STRUCTURES),在代码生成层面则被渲染为数据包 minecraft:jigsaw 放置配置或 NeoForge 生物群系修改器中的 "step" 字段。理解这 12 个阶段的执行顺序与语义,你就能精准控制自定义结构在世界中的出场时机。