Render controllers

Animations move a mob. A render controller decides what the mob is drawn with: which model, which texture and which material. It can also hide parts of the model. In this guide our Ruby golem gets three gem colors and a crown it only wears sometimes.

Render controllers live in the resource pack. Like animations, they only change how a mob looks.

The files

RP/
  entity/
    ruby_golem.entity.json
  render_controllers/
    ruby_golem.render_controllers.json
  textures/
    entity/
      ruby_golem/
        red.png
        pink.png
        dark.png

Do you even need one?

Many mobs have one model and one skin. For those, use the vanilla controller controller.render.default. It draws the geometry, texture and material that are all called default in your client entity, and you do not have to write any file. Your first custom mob does exactly that.

You need your own render controller when:

• the mob has several textures to choose from, like colors or skins,
• the mob changes model, like a sheep that loses its wool,
• parts of the model should appear or vanish, like a saddle or armor,
• the mob should be tinted a color.

Short names come from the client entity

A render controller never uses file paths. It uses the short names you gave things in the client entity, with a prefix in front:

So texture.red means "the texture I called red in the client entity".

Step 1: the simplest controller

Render controller files go in the render_controllers folder:

{
  "format_version": "1.8.0",
  "render_controllers": {
    "controller.render.ruby_golem": {
      "geometry": "geometry.default",
      "materials": [{ "*": "material.default" }],
      "textures": ["texture.red"]
    }
  }
}

The three main parts:

The name must start with controller.render.. Then list it in the client entity:

"render_controllers": ["controller.render.ruby_golem"]

Step 2: three gem colors

Now the fun part. First, list all three textures in the client entity:

"textures": {
  "red": "textures/entity/ruby_golem/red",
  "pink": "textures/entity/ruby_golem/pink",
  "dark": "textures/entity/ruby_golem/dark"
}

Then put them in an array in the render controller and pick one with 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] means "take item number query.variant from the list". Counting starts at 0, so variant 0 is red, 1 is pink and 2 is dark.

Where does query.variant come from?

From the behavior pack. The minecraft:variant component stores a number on the mob, and query.variant reads it. Here each golem picks a random color when it spawns:

"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"] } }
    ]
  }
}

Red has weight 2, so it shows up twice as often as each of the others.

Arrays for models and materials too

arrays can hold three kinds of lists. Each list may only hold one kind of thing:

You do not always need an array. A simple choice between two things can use a Molang ternary:

"geometry": "query.is_baby ? geometry.small : geometry.default"

Step 3: hide and show parts

part_visibility turns bones on and off. Our golem has a crown bone that it only shows when it is tamed:

"part_visibility": [
  { "*": true },
  { "crown": "query.is_tamed" }
]

• Each entry is a bone name and a value. true or anything that is not 0 shows it, false or 0 hides it.
• Hiding a bone hides its children too.
• Entries are applied in order, so later ones win. Here everything is shown first, then the crown is set by the query.
• * works as a wildcard: "gem_*" matches gem_left, gem_right and so on.

The materials list works the same way: start with { "*": ... } for everything, then override single bones after it.

"materials": [
  { "*": "material.default" },
  { "core": "material.glow" }
]

For this to work, glow must be a short name in the client entity's materials, pointing at a real material that glows, like entity_emissive_alpha.

Colors and effects

A render controller can also change colors. All of these are optional:

Each color has r, g, b and a from 0 to 1, and each can be Molang:

"overlay_color": {
  "r": 1.0,
  "g": 1.0,
  "b": 1.0,
  "a": "variable.is_shouting ? 0.5 : 0.0"
}

More than one controller

render_controllers in the client entity is a list. Each controller draws the mob once with its own model, so you can stack them. Vanilla uses this for layers like armor or glowing eyes.

You can also add a condition so a controller only draws sometimes:

"render_controllers": [
  "controller.render.ruby_golem",
  { "controller.render.ruby_golem_shine": "query.is_powered" }
]

When something goes wrong

More help is in Troubleshooting.

What next

• Make the mob move with Entity animations.
• Play sounds and particles from animations with Animation events.
• Paint better skins with Pixel textures.