MCreator 结构生成阶段(Generation Step)完全指南:从 GUI 配置到世界生成 JSON

原创2026-10-16 22:46:421,396 阅读
文章标签:桌面应用游戏开发代码生成低代码开发工具模板引擎

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 个阶段的执行顺序与语义,你就能精准控制自定义结构在世界中的出场时机。

登录后查看全文
MCreator