MCreator 方块着色选项 tintType:基于生物群系颜色着色的原理与源码实现解析

原创2026-10-15 17:20:441,708 阅读
文章标签:低代码代码生成桌面应用游戏开发

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 版本可以看出两点演进:

  1. 内置色调源成为一等公民:新版 BlockTintSources 直接提供 grass()、foliage()、dryFoliage()、water() 等工厂方法,Dry foliage 不再需要常数模拟;
  2. 环境色改为属性探针:Sky / Fog 不再读取生物群系的固定颜色,而是通过 Minecraft.getInstance().gameRenderer.mainCamera().attributeProbe().getValue(EnvironmentAttributes.SKY_COLOR, 0) 这类环境属性探针实时取色,并仍以旧版相同常数(8562943、12638463)作为物品侧回退。

这对使用不同生成器的用户是一个实际约束:同一份工作区在 1.21.1 与 26.3.x 生成器下会为同一 tintType 生成不同形态的着色代码,但 UI 层面的选项取值表保持不变。

6. 实战建议与核对清单

结合选项文档与源码实现,配置着色方块时可按以下清单操作:

  1. 选对色调类型:想要"像草一样随生物群系变化"选 Grass/Foliage/Water 等动态类型;想要全局固定色调(例如统一深绿色)选 Default foliage/Birch foliage/Spruce foliage 等常数类型。
  2. 纹理用灰度图:文档明确建议着色面使用灰度纹理,原因见 §1 的混合原理;这也是为什么 tinted_cross/leaves 模型通常搭配白色或灰色 16×16 纹理使用。
  3. 物品着色单独勾选:需要物品栏图标也呈现色调时,同时启用 isItemTinted(生成 itemColorLoad,blocks.java.ftl 第 122~132 行);不勾选则仅世界中的方块着色。
  4. 核对生成产物:构建后在生成的工作区 src 下检查 <mod>Block.blockColorLoad、init 包中的 BlocksClientSideHandler,以及 models/block 下的 tinted_cross 模型 JSON,确认三层代码与 §3、§4 描述一致。

主要参考文件(均可按仓库根目录相对路径打开):

登录后查看全文
MCreator