MCreator 方块着色选项 tintType:基于生物群系颜色着色的原理与源码实现解析
MCreator 方块着色选项 tintType:基于生物群系颜色着色的原理与源码实现解析
本文围绕 MCreator 中方块编辑器内的 tint_type 选项展开。读完你将理解:这个"基于生物群系颜色的着色"选项在 MCreator 工作流中的完整作用链路——它如何决定生成的方块模型类型(cross 还是 tinted_cross)、如何生成 NeoForge 客户端颜色注册代码(RegisterColorHandlersEvent)、以及为什么着色面应当使用灰度纹理。文中所有结论均对应到当前仓库的真实定义文件与 FreeMarker 模板,可直接按路径核对。
1. 选项本身做什么
关联文档 tint_type.md(de_DE 语言版,与 default 英文版 内容对应)的原文核心就两句话:
该选项会基于生物群系颜色(Biome colors)对方块着色,效果类似草(Grass)、树叶(Leaves)和水(Water)。 为了获得最佳效果,着色的方块面应使用灰度纹理(grayscale texture)。
这背后的机制是 Minecraft 客户端的 Block Tint(方块色调) 系统:渲染引擎在绘制方块时会查询一个"色调源"(tint source),把纹理的每个像素与一个 RGB 颜色做乘法混合。原生游戏里草方块顶面、树叶和水面都依赖这套机制随生物群系呈现不同颜色(樱花林的草偏粉、热带树叶更亮)。MCreator 的 tintType 选项就是把这一机制封装成可配置项:选中某个色调类型后,生成器会在你的 Mod 中自动写出对应的颜色注册代码,你不需要手写 BlockColors.register 或 NeoForge 的事件处理。
选择"使用灰度纹理"的原因也源于此:着色结果是 纹理像素 × 色调颜色,如果纹理本身带彩色,最终颜色会被二次染色而偏离生物群系本来的色调;灰度纹理则让色调颜色原样透出来,这是 Minecraft 资源包开发中着色方块的标准做法。
2. tintType 的完整取值表
No tint(不着色)是默认值。在 Block.java 中,选项取值由 @LimitedOptions 注解限定(Plant.java 与 Fluid.java 中有完全相同的定义,说明植物、流体也支持该选项):
@LimitedOptions({ "No tint", "Grass", "Foliage", "Dry foliage", "Birch foliage", "Spruce foliage",
"Default foliage", "Water", "Sky", "Fog", "Water fog" }) public String tintType;
| 取值 | 含义 | 1.21.1 生成代码取色方式(见 §3) |
|---|---|---|
No tint |
不启用着色 | 不生成任何颜色注册代码 |
Grass |
草色,随生物群系变化 | BiomeColors.getAverageGrassColor(world, pos),无世界时回退 GrassColor.get(0.5D, 1.0D) |
Foliage |
树叶色,随生物群系变化 | BiomeColors.getAverageFoliageColor(world, pos),回退 FoliageColor.getDefaultColor() |
Default foliage |
默认树叶色(常数) | FoliageColor.getDefaultColor(),不查询世界 |
Birch foliage |
桦树叶色(常数) | FoliageColor.getBirchColor() |
Spruce foliage |
云杉/针叶色(常数) | FoliageColor.getEvergreenColor() |
Dry foliage |
干燥树叶色 | 1.21.1 中该内置类型不存在,模板改用常数 10710342 |
Water |
水色,随生物群系变化 | BiomeColors.getAverageWaterColor(world, pos),回退 -1 |
Sky |
天空色,随生物群系/环境变化 | 生物群系 getSkyColor(),回退常数 8562943 |
Fog |
雾色,随生物群系/环境变化 | 生物群系 getFogColor(),回退常数 12638463 |
Water fog |
水下雾色 | 生物群系 getWaterFogColor(),回退常数 329011 |
从源码结构看,Grass、Foliage、Water、Sky、Fog、Water fog 属于"动态"类型(颜色随查询位置所在生物群系实时变化,即关联文档所说的"based on biome colors");Default foliage、Birch foliage、Spruce foliage、Dry foliage 属于"常数"类型(全局固定颜色,不查询世界)。
3. 生成代码:blockColorLoad 颜色注册
以 1.21.1 生成器为例,模板 block.java.ftl 在 tintType != "No tint" 时生成如下方法(以 Grass 取值为例,<#if> 分支按上表取色):
@OnlyIn(Dist.CLIENT) public static void blockColorLoad(RegisterColorHandlersEvent.Block event) {
event.getBlockColors().register((bs, world, pos, index) -> {
return world != null && pos != null ?
BiomeColors.getAverageGrassColor(world, pos) : GrassColor.get(0.5D, 1.0D);
}, ModNameBlocks.REGISTRYNAME.get());
}
几个值得注意的实现细节(均可在上表模板行号区间核对):
- 客户端专用:方法标注
@OnlyIn(Dist.CLIENT),色调查询只影响渲染,服务端不产生该代码的运行时逻辑。 world == null回退分支:色调回调在若干无坐标上下文的场景(例如某些 GUI 渲染)会被调用,模板为每个取值生成了不依赖世界的回退颜色——常数类型直接写死调色板颜色,动态类型写入上表所列的回退常数(如 Sky 回退8562943、Fog 回退12638463、Water fog 回退329011)。Dry foliage的模板注释:源码中明确注释This tint type doesn't exist in 1.21.1, we use a constant value instead,即 1.21.1 原生没有"干燥树叶"这一色调类型,生成器以常数10710342模拟。
3.1 中央注册入口 BlocksClientSideHandler
单个方块生成 blockColorLoad 静态方法后,还需要有人去调用它。模板 blocks.java.ftl 首先扫描工作区里所有 block/plant 元素,汇总 hasTintedBlocks / hasTintedBlockItems 两个标志(第 39~57 行);只要存在任意着色方块,就会在 init 包生成一个 @EventBusSubscriber(Dist.CLIENT) 的内部类(第 108~132 行),集中转发 NeoForge 事件:
@EventBusSubscriber(Dist.CLIENT) public static class BlocksClientSideHandler {
@SubscribeEvent public static void blockColorLoad(RegisterColorHandlersEvent.Block event) {
myblockBlock.blockColorLoad(event); // 逐个着色方块转发
otherplantBlock.blockColorLoad(event);
...
}
@SubscribeEvent public static void itemColorLoad(RegisterColorHandlersEvent.Item event) { ... }
}
也就是说,tintType 这一个下拉选项,最终驱动了"每方块一个静态方法 + 全局一个客户端事件转发器"两层代码的生成与开关。
4. 模型联动:cross 与 tinted_cross
着色不只影响颜色,还影响方块模型。在 PlantGUI.java 中可以看到联动逻辑:
plant.renderType = "No tint".equals(tintType.getSelectedItem()) ? 12 : 120;
- 渲染类型
12→ 模型变量model=cross(普通十字交叉模型); - 渲染类型
120→ 模型变量model=tinted_cross(着色十字交叉模型)。
对应的 JSON 模型模板条件写在 block.definition.yaml 与 plant.definition.yaml 中,例如植物定义里的两组条件分支:tintType %= No tint 时输出 model=cross,isBlockTinted() 为真时输出 model=tinted_cross。叶子类方块同样如此:block.definition.yaml 第 260 行附近对 Leaves 基类按 tintType %= No tint / isBlockTinted() 分别生成 model=cube_all 与 model=leaves 模型。而 isBlockTinted() 的定义正是 Block.java 中的 !"No tint".equals(tintType)——它把 UI 选项直接翻译为模板条件。
isItemTinted 选项控制物品形态是否也着色:当其为真且方块存在 BlockItem 时,模板还会额外生成 itemColorLoad(RegisterColorHandlersEvent.Item) 方法(block.java.ftl),为物品纹理注册一组固定颜色(注意物品侧没有世界坐标,因此全部使用常数回退值,如 Water 为 3694022),并在 BlocksClientSideHandler 中同样被集中转发。
5. 新版 26.3.x 生成器的 API 迁移
在 generator-26.3.x 模板中,blockColorLoad 已迁移到新的 RegisterColorHandlersEvent.BlockTintSources API,用 BlockTintSource 列表替代了旧的 lambda 查询:
public static void blockColorLoad(RegisterColorHandlersEvent.BlockTintSources event) {
event.getBlockColors().register(
<#if data.tintType == "Default foliage">
List.of(BlockTintSources.constant(FoliageColor.FOLIAGE_DEFAULT))
<#elseif data.tintType == "Grass">
List.of(BlockTintSources.grass())
<#elseif data.tintType == "Foliage">
List.of(BlockTintSources.foliage())
<#elseif data.tintType == "Dry foliage">
List.of(BlockTintSources.dryFoliage())
<#elseif data.tintType == "Water">
List.of(BlockTintSources.water())
...
对比 1.21.1 版本可以看出两点演进:
- 内置色调源成为一等公民:新版
BlockTintSources直接提供grass()、foliage()、dryFoliage()、water()等工厂方法,Dry foliage不再需要常数模拟; - 环境色改为属性探针:
Sky/Fog不再读取生物群系的固定颜色,而是通过Minecraft.getInstance().gameRenderer.mainCamera().attributeProbe().getValue(EnvironmentAttributes.SKY_COLOR, 0)这类环境属性探针实时取色,并仍以旧版相同常数(8562943、12638463)作为物品侧回退。
这对使用不同生成器的用户是一个实际约束:同一份工作区在 1.21.1 与 26.3.x 生成器下会为同一 tintType 生成不同形态的着色代码,但 UI 层面的选项取值表保持不变。
6. 实战建议与核对清单
结合选项文档与源码实现,配置着色方块时可按以下清单操作:
- 选对色调类型:想要"像草一样随生物群系变化"选
Grass/Foliage/Water等动态类型;想要全局固定色调(例如统一深绿色)选Default foliage/Birch foliage/Spruce foliage等常数类型。 - 纹理用灰度图:文档明确建议着色面使用灰度纹理,原因见 §1 的混合原理;这也是为什么
tinted_cross/leaves模型通常搭配白色或灰色 16×16 纹理使用。 - 物品着色单独勾选:需要物品栏图标也呈现色调时,同时启用
isItemTinted(生成itemColorLoad,blocks.java.ftl 第 122~132 行);不勾选则仅世界中的方块着色。 - 核对生成产物:构建后在生成的工作区
src下检查<mod>Block.blockColorLoad、init包中的BlocksClientSideHandler,以及models/block下的tinted_cross模型 JSON,确认三层代码与 §3、§4 描述一致。
主要参考文件(均可按仓库根目录相对路径打开):
- 选项文档(de_DE / default / zh_CN 三份对应):plugins/mcreator-localization/help/de_DE/block/tint_type.md、plugins/mcreator-localization/help/default/block/tint_type.md、plugins/mcreator-localization/help/zh_CN/block/tint_type.md
- 选项定义与
isBlockTinted():src/main/java/net/mcreator/element/types/Block.java、src/main/java/net/mcreator/element/types/Plant.java - 1.21.1 颜色生成模板:plugins/generator-1.21.1/neoforge-1.21.1/templates/block/block.java.ftl、plugins/generator-1.21.1/neoforge-1.21.1/templates/elementinits/blocks.java.ftl
- 26.3.x 新 API 模板:plugins/generator-26.3.x/neoforge-26.3/templates/block/block.java.ftl
- 模型/渲染类型联动:plugins/generator-1.21.1/neoforge-1.21.1/plant.definition.yaml、src/main/java/net/mcreator/ui/modgui/PlantGUI.java