动画让生物动起来，而渲染控制器决定生物用什么来绘制：哪个模型、哪张纹理、哪种材质。它还能隐藏模型的某些部分。在本指南中，我们的红宝石傀儡会有三种宝石颜色，还有一顶只在某些时候才戴的王冠。
渲染控制器放在资源包中。和动画一样，它只改变生物的外观。
文件一览
RP/
entity/
ruby_golem.entity.json
render_controllers/
ruby_golem.render_controllers.json
textures/
entity/
ruby_golem/
red.png
pink.png
dark.png你真的需要它吗？
很多生物只有一个模型和一张皮肤。这种情况直接用原版控制器 controller.render.default 就行。它会绘制客户端实体中都叫 default 的几何体、纹理和材质，你不需要写任何文件。你的第一个自定义生物就是这么做的。
以下情况你需要自己的渲染控制器：
- 生物有多张纹理可选，比如不同颜色或皮肤，
- 生物会更换模型，比如被剪了毛的羊，
- 模型的某些部分需要出现或消失，比如鞍或盔甲，
- 生物需要被染上某种颜色。
简称来自客户端实体
渲染控制器从不使用文件路径。它使用你在客户端实体中起的简称，并在前面加上前缀：
| 在客户端实体中 | 在渲染控制器中 |
|---|---|
"geometry": { "default": "geometry.wiki.ruby_golem" } | geometry.default |
"textures": { "red": "textures/entity/ruby_golem/red" } | texture.red |
"materials": { "default": "entity_alphatest" } | material.default |
所以 texture.red 的意思是“我在客户端实体中叫作 red 的那张纹理”。
第 1 步：最简单的控制器
渲染控制器文件放在 render_controllers 文件夹中：
{
"format_version": "1.8.0",
"render_controllers": {
"controller.render.ruby_golem": {
"geometry": "geometry.default",
"materials": [{ "*": "material.default" }],
"textures": ["texture.red"]
}
}
}三个主要部分：
| 字段 | 内容 |
|---|---|
geometry | 一个模型。是单个值，不是列表。 |
materials | 把骨骼和材质对应起来的列表。* 表示所有骨骼。 |
textures | 纹理列表。大多数生物只需要一张。 |
名称必须以 controller.render. 开头。然后在客户端实体中列出它：
"render_controllers": ["controller.render.ruby_golem"]第 2 步：三种宝石颜色
现在进入有趣的部分。先在客户端实体中列出全部三张纹理：
"textures": {
"red": "textures/entity/ruby_golem/red",
"pink": "textures/entity/ruby_golem/pink",
"dark": "textures/entity/ruby_golem/dark"
}然后在渲染控制器中把它们放进一个数组，再用 Molang 选出一张：
{
"format_version": "1.8.0",
"render_controllers": {
"controller.render.ruby_golem": {
"arrays": {
"textures": {
"array.gem_colors": [
"texture.red",
"texture.pink",
"texture.dark"
]
}
},
"geometry": "geometry.default",
"materials": [{ "*": "material.default" }],
"textures": ["array.gem_colors[query.variant]"]
}
}
}array.gem_colors[query.variant] 的意思是“从列表中取第 query.variant 项”。从 0 开始数，所以变种 0 是红色，1 是粉色，2 是深色。
query.variant 从哪里来？
来自行为包。minecraft:variant 组件在生物身上存一个数字，query.variant 读取它。这里每个傀儡在生成时随机选一种颜色：
"component_groups": {
"wiki:color_red": { "minecraft:variant": { "value": 0 } },
"wiki:color_pink": { "minecraft:variant": { "value": 1 } },
"wiki:color_dark": { "minecraft:variant": { "value": 2 } }
},
"events": {
"minecraft:entity_spawned": {
"randomize": [
{ "weight": 2, "add": { "component_groups": ["wiki:color_red"] } },
{ "weight": 1, "add": { "component_groups": ["wiki:color_pink"] } },
{ "weight": 1, "add": { "component_groups": ["wiki:color_dark"] } }
]
}
}红色的权重是 2，所以它出现的概率是其他每种颜色的两倍。
超出范围不会报错
如果数字比列表长度大，会从头绕回：在 3 项的列表中，数字 3 又会选到第 0 项。负数会选第 0 项。所以变种写错只会显示错误的颜色，不会崩溃。
模型和材质也能用数组
arrays 可以放三种列表。每个列表只能放一种东西：
| arrays 中的键 | 内容 | 示例项 |
|---|---|---|
textures | 纹理 | texture.red |
materials | 材质 | material.default |
geometries | 模型 | geometry.default |
并不总是需要数组。二选一的简单情况可以用 Molang 三元表达式：
"geometry": "query.is_baby ? geometry.small : geometry.default"第 3 步：隐藏和显示部件
part_visibility 用来开关骨骼。我们的傀儡有一根 crown 骨骼，只有被驯服时才显示：
"part_visibility": [
{ "*": true },
{ "crown": "query.is_tamed" }
]- 每个条目是一个骨骼名和一个值。
true或任何非 0 的值表示显示，false或 0 表示隐藏。 - 隐藏一根骨骼也会隐藏它的子骨骼。
- 条目按顺序应用，后面的会覆盖前面的。这里先显示所有部分，再由查询决定王冠是否显示。
*可以作通配符："gem_*"会匹配gem_left、gem_right等等。
materials 列表的规则相同：先用 { "*": ... } 设定全部骨骼，再在后面覆盖个别骨骼。
"materials": [
{ "*": "material.default" },
{ "core": "material.glow" }
]要让它生效，glow 必须是客户端实体 materials 中的一个简称，并指向一个真正会发光的材质，比如 entity_emissive_alpha。
颜色和效果
渲染控制器还能改变颜色。以下都是可选的：
| 字段 | 作用 |
|---|---|
color | 给生物染色。需要支持染色的材质。 |
overlay_color | 在整个生物上覆盖一层颜色，a 表示强度 |
is_hurt_color | 生物受伤时的闪烁颜色。原版是红色。 |
on_fire_color | 着火时的颜色 |
ignore_lighting | 设为 true 时以全亮度绘制生物，夜里也一样 |
uv_anim | 用 offset 和 scale 让纹理随时间滑动，做出流动效果 |
每种颜色都有 r、g、b 和 a，取值 0 到 1，而且每个都可以是 Molang：
"overlay_color": {
"r": 1.0,
"g": 1.0,
"b": 1.0,
"a": "variable.is_shouting ? 0.5 : 0.0"
}多个控制器
客户端实体中的 render_controllers 是一个列表。每个控制器都会用自己的模型把生物绘制一遍，所以可以叠加使用。原版就用这种方式做盔甲或发光眼睛这类图层。
你还可以加一个条件，让某个控制器只在特定时候绘制：
"render_controllers": [
"controller.render.ruby_golem",
{ "controller.render.ruby_golem_shine": "query.is_powered" }
]出问题时
| 你看到的现象 | 最可能的原因 |
|---|---|
| 生物看不见 | 客户端实体中的渲染控制器名称拼错了，或文件不在 render_controllers 中 |
| 紫黑格子 | 纹理简称或路径写错了，或路径以 .png 结尾 |
| 每个傀儡都是红色 | 行为包从未设置 minecraft:variant，所以 query.variant 是 0 |
| 隐藏的部件仍然显示 | 后面的 part_visibility 条目又把它打开了，比如放在最后的 * |
| 染色没有效果 | 材质不支持染色。试试为此设计的原版材质 |
更多帮助见故障排查。