MCreator 生物群系自定义树木指南:Stem Block(树干方块)参数详解

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

MCreator 生物群系自定义树木指南:Stem Block(树干方块)参数详解

导读

本文聚焦 MCreator 生物群系(Biome)元素中的 Stem Block(树干方块) 配置参数——它是「自定义树木(Custom trees)」模式下用于指定树木主干(Trunk)材质的核心字段。读完本文,你将掌握该参数在群系编辑器中的位置与生效条件、它与树冠(Branch)、树高、地面方块等相邻参数的关系,以及它在世界生成 JSON(configured_feature)中的底层映射原理,从而能够独立打造出风格统一、生成稳定的自定义树木群系。

一、参数定位:群系编辑器中的 Stem 字段

在 MCreator 的生物群系编辑器中,树木相关的参数集中放置在「Trees」分组下。其中 Stem 字段的官方帮助说明(stem_block.md)只有一句话,却精准概括了它的全部职责:

This parameter controls the block used to make the stem of your tree if custom trees are selected. (该参数控制:当选择自定义树木时,用于构成树木树干 / 主干(stem)的方块。)

在 BiomeGUI.java 中可以看到,该字段的 UI 构建逻辑如下:

sbbp5.add(HelpUtils.wrapWithHelpButton(this.withEntry("biome/stem_block"),
        L10N.label("elementgui.biome.stem_block")));
sbbp5.add(PanelUtils.join(treeStem));
  • withEntry("biome/stem_block") 正是把帮助按钮链接到本文对应的 stem_block.md;
  • 字段的界面标签来自本地化文件 texts.properties:elementgui.biome.stem_block=Stem:;
  • treeStem 是一个 MCItemHolder,其数据来源为 ElementUtil::loadBlocks,即只允许从工作区已有的方块元素(Block)列表中选择,而不是任意物品或原版方块混选。

关联阅读:branch_block.md(树冠方块)、tree_definition.md(原生树 vs 自定义树)、minimal_tree_height.md(最小树高)。

二、生效前提:必须处于 Custom trees 模式

Stem 字段不是任何时候都生效的,它与树类型开关 treeType 严格绑定。在数据模型 Biome.java 中:

@LimitedOptions({ "Vanilla trees", "Custom trees" }) public int treeType;
@Numeric(init = 7, min = 0, max = 32, step = 1) public int minHeight;
public MItemBlock treeStem;
public MItemBlock treeBranch;
  • TREES_VANILLA = 0(原生树木)、TREES_CUSTOM = 1(自定义树木)两个常量在构造函数中恢复;
  • 当 treeType == TREES_CUSTOM 时,Stem(树干)、Branch(树冠)、Vines(藤蔓)、Fruits(果实)等字段才全部可用;当 treeType == TREES_VANILLA 时,树木完全沿用原版数据(对应 tree_definition.md 中 "use vanilla tree height and block data" 的描述)。

这一逻辑同样体现在 GUI 的交互控制中(BiomeGUI.java):

treeStem.setEnabled(true);
treeBranch.setEnabled(true);
// ... 否则(Vanilla trees):
treeStem.setEnabled(false);
treeBranch.setEnabled(false);

也就是说,只有把树类型切换为「Custom trees」,Stem 字段才会亮起并参与生成。若切换后未填写任何方块,校验器会立即拦截并提示本地化错误 elementgui.biome.error_tree_needs_stem_block(即「自定义树木必须指定树干方块」),相关校验注册见 BiomeGUI.java 与 BiomeGUI.java。Stem 是自定义树木模式下的必填参数。

三、与相邻参数的分工:Stem vs Branch vs Height

自定义树木由一组互相配合的参数共同描述(Biome.java):

参数 数据类型 默认值 / 范围 职责
treesPerChunk int 1,0–64 每区块树木数量;为 0 时 hasTrees() 返回 false,整个树木系统不生成
vanillaTreeType String "Default" 原生树的形状模板(Default / Big trees / Birch / Savanna / Mega pine / Mega spruce)
treeType int 0(Vanilla) 原生树 vs 自定义树的总开关
minHeight int 7,0–32 自定义树的最小高度(参与 trunk_placer 的 base_height 计算)
treeStem MItemBlock 无(必填) 树干 / 主干方块,即本文主角 Stem Block
treeBranch MItemBlock 无 树冠(树叶)方块,对应 branch_block.md
treeVines / treeFruits MItemBlock 无 可选的藤蔓与果实装饰,仅在 TREES_CUSTOM 下生效

其中 treeVines、treeFruits 的启用还依赖辅助方法(Biome.java):

public boolean hasFruits() {
    return hasTrees() && treeType == TREES_CUSTOM && treeFruits != null && !treeFruits.isEmpty();
}
public boolean hasVines() {
    return hasTrees() && treeType == TREES_CUSTOM && treeVines != null && !treeVines.isEmpty();
}

可以看到,自定义树木的树干与树冠是两套独立字段:Stem 决定“骨架”,Branch 决定“树冠”。设计群系时若希望树木色调统一,应让 Stem 与 Branch 的配色风格匹配(例如用深色原木配深色树叶、浅色原木配浅色树叶)。

四、底层实现:treeStem 如何写入世界生成 JSON

MCreator 的生成器插件会为每个带树木的群系输出两个文件(见 biome.definition.yaml):

  • @MODDATAROOT/worldgen/configured_feature/@registryname_tree.json
  • @MODDATAROOT/worldgen/placed_feature/@registryname_tree.json

前者由 configured_tree.json.ftl 模板渲染。模板开头先判断树类型:

<#assign ct = data.treeType == data.TREES_CUSTOM>

然后决定 trunk_provider(树干)与 foliage_provider(树冠)的实际方块来源(configured_tree.json.ftl):

"trunk_provider": {
  "type": "minecraft:simple_state_provider",
  "state":
  <#if ct>
      ${mappedMCItemToBlockStateJSON(data.treeStem)}
  <#else>
    {
      "Name": "${default_log}",
      "Properties": { "axis": "y" }
    }
  </#if>
},
"foliage_provider": {
  "type": "minecraft:simple_state_provider",
  "state":
  <#if ct>
    ${mappedMCItemToBlockStateJSON(data.treeBranch)}
  <#else>
    { "Name": "${default_leaves}", ... }
  </#if>
}

这里揭示了两条关键实现事实:

  1. data.treeStem 只在自定义模式(ct)下被映射为 trunk_provider;原生模式下树干硬编码为对应树型的默认原木(oak_log、jungle_log、spruce_log 等);
  2. 树干方块最终以 minecraft:simple_state_provider + 方块状态 JSON 的形式写入数据包,因此任何能输出合法方块状态的方块(包括自定义方块)都可以作为 Stem。

树干的高度并非由 Stem 参数决定,而是由 trunk_placer 控制。模板依据 vanillaTreeType 选择不同的 placer,并让自定义树的最小高度参与计算(configured_tree.json.ftl):

<#assign trunk_placer = ["minecraft:straight_trunk_placer", ct?then([data.minHeight, 32]?min, 4), 2, 0]>

即:自定义模式下 base_height = min(minHeight, 32),而原生模式下则使用各树型固定的基准高度。因此若想精确控制自定义树的整体高度,需配合 minimal_tree_height.md 对应的 minHeight 字段使用。

兼容性说明:新版本生成器 configured_tree.json.ftl 使用 mappedMCItemToRegistryName(data.treeStem) 输出方块注册名,并额外生成 below_trunk_provider(以 undergroundBlock 作为根部下方方块),但「自定义树 → treeStem 映射到 trunk_provider」的核心逻辑在两个版本中保持一致。

五、藤蔓与果实装饰对 Stem 的影响

自定义树木还可以在树干上追加装饰,这会额外生成两个装饰器类(见 biome.definition.yaml):

  • biome/tree_trunk_decorator.java.ftl → @NAMETrunkDecorator.java(条件:hasVines())
  • biome/tree_leave_decorator.java.ftl → @NAMELeaveDecorator.java(条件:hasVines())
  • biome/tree_fruits_decorator.java.ftl → @NAMEFruitDecorator.java(条件:hasFruits())

在 JSON 中这些装饰器以 decorators 数组注册(configured_tree.json.ftl),藤蔓同时挂接树干与树冠两类装饰器。也就是说,藤蔓装饰会沿 Stem 指定的方块表面生长——若希望藤蔓效果明显,Stem 应选择体积规整、便于贴附的方块;若希望树形干净利落,则不填写 treeVines 即可。

六、实操建议与常见问题

1. 推荐配置流程

  1. 先在「Blocks」元素中创建或导入想要的树干方块(原木类方块效果最自然);
  2. 回到「Biome」元素,将 Tree type 切换为 Custom trees;
  3. 在 Stem 字段选择该方块(此时 Branch 字段也同步亮起);
  4. 在 Minimal tree height(minHeight,0–32)中设定基准高度;
  5. 可选:填写 Branch、Vines、Fruits,并按需调整 vanillaTreeType 以改变整体树形(不同 placer 决定分叉与粗细)。

2. 常见问题排查

  • Stem 字段置灰不可选:说明 treeType 仍为「Vanilla trees」,先切换为「Custom trees」;
  • 保存时报 error_tree_needs_stem_block:自定义模式下 Stem 为必填,需先选择任一有效方块;
  • 树木不生成:检查 treesPerChunk 是否大于 0(hasTrees() 的前提),同时确认群系已被放置到有效的生成位置(Overworld / Nether / Caves 开关);
  • 树干高度不符预期:高度由 trunk_placer 与 minHeight 共同决定,注意自定义模式下 base_height 上限为 32。

3. 代码预览与验证

生成后,可在工作区的数据包目录中检查 worldgen/configured_feature/<群系名>_tree.json 的 trunk_provider.state 是否为所选的 Stem 方块;对于 26.3.x 及以后版本,还可观察 below_trunk_provider 是否按预期使用了 underground_block.md 指定的地下方块。通过对比「Vanilla trees」与「Custom trees」两种模式产出的 JSON,可以直观理解 Stem 参数在生成链路中的作用边界。

结语

Stem Block 虽只是 MCreator 生物群系编辑器中的一个字段,却承担着自定义树木的“骨架”职责:它只在 Custom trees 模式下生效、属于必填项、仅接受工作区已有方块,并通过生成器模板精确映射为数据包中 configured_feature 的 trunk_provider。掌握它的生效条件、参数分工与底层映射关系,是做出高度定制化、可稳定生成的自定义树木群系的第一步。

登录后查看全文
MCreator