主题

渲染控制器与材质 ​

版本说明

本文档基于渲染控制器 format_version 1.10.0，适用于我的世界中国版基岩版。

渲染控制器概述 ​

渲染控制器（Render Controller）是基岩版实体渲染管线中的核心组件。它充当实体客户端定义（client_entity）与 GPU 渲染之间的逻辑层，负责将材质（Material）、贴图（Texture）和几何模型（Geometry）的短名称（short-name）组合成最终的渲染指令。

实体定义 (client_entity)
    ├── 短名映射: Material.default, Texture.default, Geometry.default
    └── 引用渲染控制器: controller.render.my_entity
            │
            ▼
渲染控制器 (render_controllers)
    ├── 读取短名 → 选择材质、贴图、几何体
    ├── 应用贴图分层、骨骼可见性、多材质等逻辑
    └── 提交渲染指令 → GPU

简而言之：

  • client_entity 定义"有哪些素材可用"（通过短名注册）
  • 渲染控制器 决定"如何使用这些素材进行渲染"

渲染控制器文件位于资源包的 render_controllers/ 目录下，文件扩展名为 .json。

短名映射 ​

在 client_entity 的 description 中，我们通过键值对为材质、贴图和几何体注册短名称：

json
{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "custom:my_entity",
      "materials": {
        "default": "entity_alphatest",
        "glowing": "entity_emissive_alpha"
      },
      "textures": {
        "default": "textures/entity/my_entity",
        "angry": "textures/entity/my_entity_angry"
      },
      "geometry": {
        "default": "geometry.my_entity",
        "baby": "geometry.my_entity_baby"
      },
      "render_controllers": [
        "controller.render.my_entity"
      ]
    }
  }
}

以上定义了如下短名：

类型短名引用方式
材质defaultMaterial.default
材质glowingMaterial.glowing
贴图defaultTexture.default
贴图angryTexture.angry
几何体defaultGeometry.default
几何体babyGeometry.baby

渲染控制器中通过 Material.xxx、Texture.xxx、Geometry.xxx 的语法来引用这些短名。注意短名区分大小写。

基础渲染控制器 ​

最简单的渲染控制器只需指定一个材质、一个贴图和一个几何体：

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.my_entity": {
      "geometry": "Geometry.default",
      "materials": [
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Texture.default"
      ]
    }
  }
}

字段说明 ​

字段说明
format_version渲染控制器格式版本，推荐使用 "1.10.0"
render_controllers顶层对象，包含一个或多个渲染控制器定义
controller.render.my_entity渲染控制器的标识符，必须以 controller.render. 开头
geometry指定使用的几何体短名，这里为 Geometry.default
materials材质数组，每个元素是一个对象，键为骨骼名匹配模式，值为材质短名。"*" 表示匹配所有骨骼
textures贴图数组，按顺序叠加渲染。此处只有一层 Texture.default

注意

materials 是一个数组，数组中的每个元素是一个对象。骨骼匹配从数组头部开始，第一个匹配到的规则生效。"*" 作为通配符应放在数组最后作为兜底。

多变体渲染 (Arrays) ​

当一个实体拥有多种外观变体时（如不同花色的猫、不同种类的村民），可以在渲染控制器中定义 数组（Array），然后使用 Molang 表达式动态索引。

常用查询函数 ​

Molang 查询说明设置方式
query.variant实体变体索引行为包组件 minecraft:variant 的 value
query.mark_variant实体标记变体索引行为包组件 minecraft:mark_variant 的 value
query.skin_id实体皮肤 ID行为包组件 minecraft:skin_id 的 value

贴图变体示例 ​

假设我们有一个自定义动物，拥有 3 种毛色变体：

client_entity 中注册贴图短名：

json
{
  "textures": {
    "brown": "textures/entity/my_animal/brown",
    "white": "textures/entity/my_animal/white",
    "black": "textures/entity/my_animal/black"
  }
}

渲染控制器中定义贴图数组并索引：

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.my_animal": {
      "arrays": {
        "textures": {
          "Array.skins": [
            "Texture.brown",
            "Texture.white",
            "Texture.black"
          ]
        }
      },
      "geometry": "Geometry.default",
      "materials": [
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Array.skins[query.variant]"
      ]
    }
  }
}

字段说明 ​

  • arrays.textures —— 定义贴图类型的数组
  • Array.skins —— 数组名称，必须以 Array. 开头
  • 数组元素按索引 0、1、2… 排列
  • Array.skins[query.variant] —— 使用 query.variant 的值作为数组下标

行为包中通过 minecraft:variant 组件设置变体值：

json
{
  "minecraft:variant": {
    "value": 0
  }
}

value 为 0 时使用 Texture.brown，1 时使用 Texture.white，2 时使用 Texture.black。

几何体变体 ​

同理，也可以定义几何体数组：

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.my_animal_geo_variants": {
      "arrays": {
        "geometries": {
          "Array.geos": [
            "Geometry.default",
            "Geometry.baby",
            "Geometry.elder"
          ]
        }
      },
      "geometry": "Array.geos[query.variant]",
      "materials": [
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Texture.default"
      ]
    }
  }
}

TIP

如果 query.variant 的值超出数组范围，引擎会对索引取模（mod），循环使用数组中的元素。例如数组长度为 3，query.variant 为 5，则实际索引为 5 % 3 = 2。

贴图分层 ​

渲染控制器支持多层贴图叠加渲染，底层贴图先绘制，顶层贴图覆盖在上方。顶层贴图的透明部分（Alpha 通道为 0）会显示下层内容。

这一技术广泛用于原版村民（衣服 + 职业装饰）、猫（底色 + 花纹）等实体。

村民风格双层贴图示例 ​

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.my_villager": {
      "arrays": {
        "textures": {
          "Array.base": [
            "Texture.skin_brown",
            "Texture.skin_white",
            "Texture.skin_tan"
          ],
          "Array.clothes": [
            "Texture.clothes_farmer",
            "Texture.clothes_librarian",
            "Texture.clothes_priest"
          ]
        }
      },
      "geometry": "Geometry.default",
      "materials": [
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Array.base[query.variant]",
        "Array.clothes[query.mark_variant]"
      ]
    }
  }
}

关键要点 ​

  1. textures 数组中的顺序决定叠加顺序：索引 0 为最底层，索引 1 覆盖在上方
  2. 顶层贴图必须包含 Alpha 通道，不需要覆盖的区域设为完全透明
  3. 使用贴图分层时，通常需要使用支持 Alpha 混合的材质，如 villager_v2_masked

使用 villager_v2_masked 材质的完整示例 ​

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.layered_entity": {
      "geometry": "Geometry.default",
      "materials": [
        {
          "*": "Material.masked"
        }
      ],
      "textures": [
        "Texture.base",
        "Texture.overlay"
      ]
    }
  }
}

对应的 client_entity：

json
{
  "materials": {
    "masked": "villager_v2_masked"
  },
  "textures": {
    "base": "textures/entity/my_entity/base",
    "overlay": "textures/entity/my_entity/overlay"
  }
}

villager_v2_masked 材质专门设计用于处理多层贴图的 Alpha 遮罩效果。

骨骼可见性 (part_visibility) ​

part_visibility 字段允许你根据 Molang 条件动态显示或隐藏特定骨骼（bone）。这在以下场景非常有用：

  • 幼年/成年实体使用同一模型但隐藏部分骨骼
  • 穿戴/卸下装备
  • 不同状态显示不同部件

基础语法 ​

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.my_entity": {
      "geometry": "Geometry.default",
      "materials": [
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Texture.default"
      ],
      "part_visibility": [
        {
          "bone_name": "molang_condition"
        }
      ]
    }
  }
}

part_visibility 是一个数组，每个元素是一个对象：

  • 键：骨骼名称（必须与模型中的骨骼名完全一致）
  • 值：Molang 表达式，返回 true（显示）或 false（隐藏）

幼年实体隐藏成年骨骼示例 ​

假设模型中有 adult_horn（成年犄角）和 baby_bow（幼年蝴蝶结）两个骨骼：

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.my_animal_visibility": {
      "geometry": "Geometry.default",
      "materials": [
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Texture.default"
      ],
      "part_visibility": [
        {
          "adult_horn": "!query.is_baby"
        },
        {
          "baby_bow": "query.is_baby"
        }
      ]
    }
  }
}
  • 当实体为幼年（query.is_baby 为 true）时：adult_horn 隐藏，baby_bow 显示
  • 当实体为成年时：adult_horn 显示，baby_bow 隐藏

装备可见性示例 ​

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.equipment_visibility": {
      "geometry": "Geometry.default",
      "materials": [
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Texture.default"
      ],
      "part_visibility": [
        {
          "helmet": "query.is_item_name_any('slot.armor.head', 0, 'custom:iron_helmet')"
        },
        {
          "cape": "variable.show_cape"
        },
        {
          "left_wing": "variable.has_wings"
        },
        {
          "right_wing": "variable.has_wings"
        }
      ]
    }
  }
}

注意

part_visibility 中的骨骼名称必须与几何模型中定义的骨骼名称完全一致。如果名称不匹配，该规则会被静默忽略，不会产生错误日志。

多材质渲染 ​

在默认情况下，"*" 通配符将同一个材质应用到所有骨骼。但有时我们需要为不同的骨骼指定不同的材质，例如让眼睛发光、让某些部位半透明等。

骨骼匹配规则 ​

materials 数组中的每个元素代表一条匹配规则。匹配从数组的第一个元素开始，一旦某条规则匹配到某个骨骼，该骨骼就使用这条规则的材质，后续规则不再对该骨骼生效。

支持使用 * 通配符进行模糊匹配：

模式匹配说明
"*"匹配所有骨骼
"head"精确匹配名为 head 的骨骼
"eye_*"匹配所有以 eye_ 开头的骨骼
"*_overlay"匹配所有以 _overlay 结尾的骨骼

发光眼睛示例 ​

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.glowing_eyes_entity": {
      "geometry": "Geometry.default",
      "materials": [
        {
          "eye_left": "Material.glowing"
        },
        {
          "eye_right": "Material.glowing"
        },
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Texture.default"
      ]
    }
  }
}

对应的 client_entity 材质映射：

json
{
  "materials": {
    "default": "entity_alphatest",
    "glowing": "entity_emissive_alpha"
  }
}

这样 eye_left 和 eye_right 骨骼会使用自发光材质 entity_emissive_alpha，其余所有骨骼使用标准的 entity_alphatest。

使用通配符的多材质示例 ​

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.complex_materials": {
      "geometry": "Geometry.default",
      "materials": [
        {
          "glass_*": "Material.transparent"
        },
        {
          "glow_*": "Material.emissive"
        },
        {
          "overlay_*": "Material.blend"
        },
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Texture.default"
      ]
    }
  }
}

此配置将：

  • 所有以 glass_ 开头的骨骼使用半透明材质
  • 所有以 glow_ 开头的骨骼使用自发光材质
  • 所有以 overlay_ 开头的骨骼使用混合材质
  • 其余骨骼使用默认材质

材质概述 ​

材质（Material）定义了实体的 着色器（Shader）行为，决定了像素如何被绘制到屏幕上。材质控制以下属性：

  • 是否进行 Alpha 测试（透明像素丢弃）
  • 是否进行 Alpha 混合（半透明）
  • 是否有自发光效果
  • 是否背面剔除
  • 是否接受光照影响
  • 是否显示附魔光泽
  • 以及更多渲染状态

材质继承链 ​

基岩版的材质系统使用继承机制。子材质继承父材质的所有属性，并可以覆盖或新增特定属性。

以下是核心继承链：

entity_static
  └── entity
        ├── entity_nocull
        ├── entity_alphatest
        │     ├── entity_alphatest_glint
        │     ├── entity_alphatest_multicolor_tint
        │     └── entity_custom (自定义)
        ├── entity_alphablend
        ├── entity_emissive_alpha
        └── entity_change_color
  • entity_static：最基础的实体材质，仅支持基本的顶点变换和贴图采样
  • entity：标准实体材质，支持光照、雾效、覆盖色（受伤闪红）
  • entity_nocull：在 entity 基础上关闭背面剔除
  • entity_alphatest：支持 Alpha 测试，Alpha 值低于阈值的像素被丢弃（常用于树叶、花等有透明边缘的模型）
  • entity_alphablend：支持 Alpha 混合，实现半透明效果（如史莱姆外层）

常用内置材质 ​

下表列出了在实体渲染中最常用的内置材质及其特性：

材质名称继承自说明
entityentity_static标准不透明实体材质，支持光照和受伤闪红效果
entity_nocullentity关闭背面剔除，双面可见
entity_alphatestentityAlpha 测试材质，Alpha < 阈值的像素被丢弃，常用于带透明区域的实体
entity_alphablendentityAlpha 混合材质，支持半透明效果
entity_emissive_alphaentity自发光材质，Alpha 通道控制发光强度，不受环境光照影响
entity_alphatest_glintentity_alphatest带附魔光泽的 Alpha 测试材质
entity_alphatest_multicolor_tintentity_alphatest支持多颜色染色的 Alpha 测试材质
entity_change_colorentity支持颜色叠加变化的材质（如彩色羊毛羊）
entity_multitexture_alphaentity多贴图 Alpha 混合材质
entity_multitexture_multiplicativeentity多贴图乘法混合材质
villager_v2_maskedentity村民双层贴图遮罩材质，专用于多层贴图叠加
armorentity盔甲渲染材质
armor_enchantedarmor带附魔光效的盔甲材质
item_in_handentity手持物品渲染材质
item_in_hand_glintitem_in_hand带附魔光效的手持物品材质
entity_beamentity信标光束等射线效果材质
slimeentity_alphablend史莱姆外层半透明材质

TIP

在中国版中，以上材质均可直接在 client_entity 中引用，无需额外定义。大多数自定义实体使用 entity 或 entity_alphatest 即可满足需求。

自定义材质（中国版） ​

当内置材质无法满足需求时，可以通过资源包创建自定义材质。自定义材质文件位于：

RP/materials/entity.material

材质继承语法 ​

自定义材质通过 材质名:父材质名 的格式声明继承关系：

json
{
  "materials": {
    "version": "1.0.0",
    "my_custom_material:entity_alphatest": {
      "+defines": [
        "USE_EMISSIVE"
      ],
      "+states": [
        "DisableCulling"
      ]
    }
  }
}

上例定义了一个名为 my_custom_material 的材质，继承自 entity_alphatest，并添加了自发光宏定义和关闭背面剔除状态。

完整自定义材质示例 ​

以下是一个功能较完整的自定义材质定义文件 RP/materials/entity.material：

json
{
  "materials": {
    "version": "1.0.0",

    "my_ghost_material:entity_alphablend": {
      "+defines": [
        "USE_EMISSIVE",
        "USE_OVERLAY"
      ],
      "+states": [
        "Blending",
        "DisableCulling",
        "DisableDepthWrite"
      ],
      "blendSrc": "SourceAlpha",
      "blendDst": "OneMinusSrcAlpha",
      "depthFunc": "LessEqual"
    },

    "my_hologram_material:entity_alphatest": {
      "+defines": [
        "USE_EMISSIVE",
        "USE_UV_ANIM"
      ],
      "+states": [
        "DisableCulling"
      ]
    },

    "my_tinted_material:entity_alphatest": {
      "+defines": [
        "USE_OVERLAY",
        "USE_COLOR_MASK"
      ]
    }
  }
}

common.json 注册 ​

中国版特殊说明

在中国版中，自定义材质需要在 RP/materials/common.json 中进行注册才能生效。如果不注册，材质可能无法被正确加载。

RP/materials/common.json 示例：

json
{
  "materials": {
    "fancy": {
      "entity.material": [
        "my_ghost_material",
        "my_hologram_material",
        "my_tinted_material"
      ]
    }
  }
}

属性说明 ​

语法说明
"my_mat:parent_mat"声明材质继承关系，my_mat 继承 parent_mat 的所有属性
"+defines"追加宏定义（不覆盖父材质的定义），使用 + 前缀表示追加
"+states"追加渲染状态（不覆盖父材质的状态）
"defines"覆盖父材质的所有宏定义（不带 + 前缀）
"states"覆盖父材质的所有渲染状态
"blendSrc"混合源因子
"blendDst"混合目标因子
"depthFunc"深度测试函数

注意

使用 "defines" 和 "states"（不带 + 前缀）会完全覆盖父材质的对应字段。在大多数情况下应使用 "+defines" 和 "+states" 来追加而非覆盖。

材质宏定义表 ​

Defines（宏定义） ​

以下是可用于 +defines 或 defines 中的宏定义列表：

宏定义说明
ALPHA_TEST启用 Alpha 测试，丢弃 Alpha 值低于阈值的像素
USE_EMISSIVE启用自发光效果，使用贴图 Alpha 通道控制发光强度，不受光照影响
USE_OVERLAY启用覆盖色效果（如受伤时的红色闪烁）
USE_COLOR_MASK启用颜色遮罩，允许按通道染色
USE_UV_ANIM启用 UV 动画，支持贴图坐标随时间偏移
USE_MULTITEXTURE启用多贴图模式
MULTI_COLOR_TINT启用多颜色染色
COLOR_BASED基于顶点颜色进行渲染
TINTED启用颜色着色
GLINT启用附魔光泽效果
ITEM_IN_HAND手持物品渲染模式
INSTANCEDSTEREO实例化立体渲染（VR 相关）
USE_SKINNING启用骨骼蒙皮动画
TRANSPARENT标记为半透明材质
USE_LIGHTING启用光照计算
USE_NORMAL使用法线数据
FANCY高画质模式渲染
LOW_MEMORY低内存模式
USE_MASK使用遮罩
MULTIPLICATIVE_TINT乘法着色模式
MULTIPLICATIVE_TINT_COLOR乘法着色颜色

States（渲染状态） ​

以下是可用于 +states 或 states 中的渲染状态列表：

状态说明
Blending启用 Alpha 混合，支持半透明渲染
DisableCulling关闭背面剔除，模型双面可见
DisableDepthWrite关闭深度缓冲写入，半透明物体通常需要此设置
DisableDepthTest关闭深度测试
EnableStencilTest启用模板测试
StencilWrite写入模板缓冲
InvertCulling反转背面剔除方向
DisableAlphaWrite关闭 Alpha 通道写入
EnableColorWrite启用颜色写入
DisableColorWrite关闭颜色写入

混合因子（blendSrc / blendDst） ​

值说明
SourceAlpha源 Alpha 值
OneMinusSrcAlpha1 - 源 Alpha
DestAlpha目标 Alpha 值
OneMinusDstAlpha1 - 目标 Alpha
SourceColor源颜色
OneMinusSrcColor1 - 源颜色
DestColor目标颜色
OneMinusDstColor1 - 目标颜色
One常量 1
Zero常量 0

玩家渲染控制器 ​

玩家实体在基岩版中有特殊的渲染机制，需要注意以下几点。

原版玩家渲染控制器 ​

原版使用 controller.render.player.first_person 和 controller.render.player.third_person 分别控制第一人称和第三人称渲染。

Persona 渲染控制器 ​

中国版支持角色装扮系统（Persona），使用了专用的渲染控制器来处理角色皮肤的各个部位（头发、上衣、裤子、鞋子、斗篷等）。

使用 netease_override_persona 覆盖 ​

中国版特有功能

netease_override_persona 是中国版特有的字段，用于覆盖 Persona 系统的默认渲染行为。

在中国版中，如果你需要为玩家实体应用完全自定义的渲染控制器（例如自定义皮肤系统），需要在 client_entity 中使用 netease_override_persona 字段：

json
{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "minecraft:player",
      "materials": {
        "default": "entity_alphatest",
        "cape": "entity_alphatest",
        "animated": "entity_alphatest"
      },
      "textures": {
        "default": "textures/entity/player/default_skin",
        "cape": "textures/entity/player/default_cape"
      },
      "geometry": {
        "default": "geometry.humanoid.custom",
        "cape": "geometry.cape"
      },
      "render_controllers": [
        "controller.render.custom_player"
      ],
      "netease_override_persona": true
    }
  }
}

当 netease_override_persona 设置为 true 时，引擎将跳过 Persona 系统的默认渲染控制器，完全使用你自定义的 render_controllers 列表。

自定义玩家渲染控制器示例 ​

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.custom_player": {
      "geometry": "Geometry.default",
      "materials": [
        {
          "cape_*": "Material.cape"
        },
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Texture.default"
      ],
      "part_visibility": [
        {
          "cape": "variable.player_has_cape"
        }
      ]
    }
  }
}

重要注意

覆盖玩家渲染控制器是一个高级操作。错误的配置可能导致玩家模型完全不可见或渲染异常。建议在开发过程中先在测试世界中验证，确认无误后再发布。

条件渲染控制器 ​

client_entity 的 render_controllers 数组支持通过 Molang 条件表达式来动态切换渲染控制器：

json
{
  "render_controllers": [
    {
      "controller.render.normal": "!query.is_angry"
    },
    {
      "controller.render.angry": "query.is_angry"
    }
  ]
}

当 query.is_angry 为 false 时使用普通渲染控制器，为 true 时使用愤怒状态渲染控制器。

TIP

条件渲染控制器是互斥的。在同一帧中，只有条件为 true 的渲染控制器会被执行。如果多个条件同时为 true，则所有满足条件的渲染控制器都会执行（叠加渲染）。

完整实战示例 ​

以下是一个综合运用了多种渲染控制器特性的完整示例——一个拥有多变体、发光眼睛、可隐藏部件的自定义怪物。

行为包 - 实体定义片段 ​

json
{
  "minecraft:entity": {
    "description": {
      "identifier": "custom:shadow_beast"
    },
    "components": {
      "minecraft:variant": {
        "value": 0
      },
      "minecraft:mark_variant": {
        "value": 0
      }
    }
  }
}

资源包 - client_entity ​

json
{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "custom:shadow_beast",
      "materials": {
        "default": "entity_alphatest",
        "emissive": "entity_emissive_alpha",
        "blend": "entity_alphablend"
      },
      "textures": {
        "body_dark": "textures/entity/shadow_beast/body_dark",
        "body_purple": "textures/entity/shadow_beast/body_purple",
        "body_red": "textures/entity/shadow_beast/body_red",
        "glow_overlay": "textures/entity/shadow_beast/glow_overlay",
        "armor_none": "textures/entity/shadow_beast/armor_none",
        "armor_iron": "textures/entity/shadow_beast/armor_iron",
        "armor_gold": "textures/entity/shadow_beast/armor_gold"
      },
      "geometry": {
        "default": "geometry.shadow_beast"
      },
      "render_controllers": [
        "controller.render.shadow_beast"
      ]
    }
  }
}

资源包 - 渲染控制器 ​

json
{
  "format_version": "1.10.0",
  "render_controllers": {
    "controller.render.shadow_beast": {
      "arrays": {
        "textures": {
          "Array.body": [
            "Texture.body_dark",
            "Texture.body_purple",
            "Texture.body_red"
          ],
          "Array.armor": [
            "Texture.armor_none",
            "Texture.armor_iron",
            "Texture.armor_gold"
          ]
        }
      },
      "geometry": "Geometry.default",
      "materials": [
        {
          "eye_left": "Material.emissive"
        },
        {
          "eye_right": "Material.emissive"
        },
        {
          "wing_*": "Material.blend"
        },
        {
          "*": "Material.default"
        }
      ],
      "textures": [
        "Array.body[query.variant]",
        "Array.armor[query.mark_variant]"
      ],
      "part_visibility": [
        {
          "horn_left": "!query.is_baby"
        },
        {
          "horn_right": "!query.is_baby"
        },
        {
          "tail_spike": "!query.is_baby"
        },
        {
          "baby_fin": "query.is_baby"
        }
      ]
    }
  }
}

此渲染控制器实现了：

  1. 贴图变体：通过 query.variant 切换 3 种体色
  2. 贴图分层：通过 query.mark_variant 叠加盔甲贴图
  3. 多材质：眼睛使用自发光材质，翅膀使用半透明材质，其余使用标准材质
  4. 骨骼可见性：幼年隐藏犄角和尾刺，显示幼年鳍

常见问题 ​

实体全黑 / 没有贴图 ​

症状：实体模型可见但全黑，没有贴图。

原因与解决：

  1. 渲染控制器中的 Texture.xxx 短名在 client_entity 中没有定义 → 检查短名拼写是否一致
  2. 贴图路径错误或贴图文件不存在 → 确认 textures/ 下的路径和文件名
  3. textures 数组为空 → 确保至少指定一个贴图

实体不可见 / 完全透明 ​

症状：实体不出现在游戏中，碰撞箱存在但看不到模型。

原因与解决：

  1. 渲染控制器标识符拼写错误 → 检查 client_entity 引用的名称与渲染控制器定义的名称是否一致
  2. 几何体短名不匹配 → 检查 Geometry.xxx 是否正确映射
  3. part_visibility 将所有骨骼都设为隐藏 → 检查 Molang 条件逻辑
  4. 材质问题 → 使用 entity 或 entity_alphatest 替换自定义材质来排查

贴图变体不切换 ​

症状：修改了 minecraft:variant 的值，但实体外观不变。

原因与解决：

  1. 渲染控制器中没有使用 Array + query.variant → 检查渲染控制器是否正确配置了数组
  2. query.variant 和 query.mark_variant 混淆 → 确认行为包组件和渲染控制器使用同一个查询
  3. 数组中的贴图短名有误 → 检查 Array.xxx 中的每个 Texture.yyy 是否在 client_entity 中注册

材质继承错误 ​

症状：自定义材质不生效，实体使用默认外观或报错。

原因与解决：

  1. 父材质名称拼写错误 → "my_mat:entity_alphatset" 应为 "my_mat:entity_alphatest"
  2. 使用了 "defines" 而非 "+defines" → 覆盖了父材质所有宏定义，导致基本功能丢失
  3. 中国版未在 common.json 中注册 → 确保自定义材质已在 RP/materials/common.json 中正确注册
  4. 材质文件语法错误 → 使用 JSON 验证工具检查语法

Alpha 透明不生效 ​

症状：贴图中有透明区域，但在游戏中显示为黑色或白色。

原因与解决：

  1. 使用了不支持 Alpha 的材质 → 将材质从 entity 切换为 entity_alphatest（像素级透明）或 entity_alphablend（半透明）
  2. 贴图格式不正确 → 确保贴图保存为 32 位 PNG（包含 Alpha 通道），而不是 24 位
  3. entity_alphatest 只支持全透明/全不透明 → 如需半透明效果，使用 entity_alphablend
  4. 自定义材质缺少 ALPHA_TEST 定义 → 在 +defines 中添加 "ALPHA_TEST"

多层贴图显示异常 ​

症状：叠加的贴图出现错误的透明/遮挡效果。

原因与解决：

  1. 未使用合适的材质 → 多层贴图推荐使用 villager_v2_masked
  2. 贴图层顺序错误 → textures 数组中索引 0 为底层，后续为叠加层
  3. 上层贴图没有正确的 Alpha 通道 → 确保上层贴图中不覆盖的区域完全透明（Alpha = 0）