MCreator 生物群系自定义树木指南:Stem Block(树干方块)参数详解
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>
}
这里揭示了两条关键实现事实:
data.treeStem只在自定义模式(ct)下被映射为trunk_provider;原生模式下树干硬编码为对应树型的默认原木(oak_log、jungle_log、spruce_log等);- 树干方块最终以
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. 推荐配置流程
- 先在「Blocks」元素中创建或导入想要的树干方块(原木类方块效果最自然);
- 回到「Biome」元素,将 Tree type 切换为 Custom trees;
- 在 Stem 字段选择该方块(此时 Branch 字段也同步亮起);
- 在 Minimal tree height(
minHeight,0–32)中设定基准高度; - 可选:填写 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。掌握它的生效条件、参数分工与底层映射关系,是做出高度定制化、可稳定生成的自定义树木群系的第一步。