Entity and Block Materials

Every rendered surface in Bedrock passes through a material. The material links the geometry and textures to the underlying shader pipeline and sets fixed-function GPU states, such as whether the back side of a flat plane should be drawn or discarded, how alpha channels blend with the background, and whether depth testing is active.

With the introduction of the RenderDragon engine, custom shader code is no longer loaded from resource packs, meaning you cannot write new vertex or fragment shaders from scratch. However, material definitions remain the standard way to configure how existing vanilla shaders behave on your models. In day-to-day add-on development, you will spend ninety percent of your time picking the right vanilla material name, and the remaining ten percent writing small overrides in your pack's materials folder.

Connecting a material to a custom entity happens in two steps. First, you declare a short alias mapped to the actual material identifier inside the client entity file. Second, you assign that alias to specific geometry bones inside a render controller.

In the client entity definition, the materials object maps your chosen short name (often just "default") to a vanilla or custom material string. In the render controller, the materials array pairs bone name patterns with `Material.<short_name>`. You can use an asterisk wildcard to apply a base material to every bone, and then follow it with specific bone names to override individual parts—for example, giving a robot entity an opaque body while its glass visor uses a blending material.

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "example:copper_automaton",
      "materials": {
        "default": "entity",
        "visor": "entity_alphablend",
        "eyes": "entity_emissive_alpha"
      },
      "textures": {
        "default": "textures/entity/copper_automaton"
      },
      "geometry": {
        "default": "geometry.copper_automaton"
      },
      "render_controllers": [
        "controller.render.copper_automaton"
      ]
    }
  }
}

When your client entity declares multiple materials, the render controller determines which bones receive which material. The engine evaluates the array in order from top to bottom, meaning later entries overwrite earlier ones if a bone name matches both patterns.

Below is the matching render controller for the entity defined above. It applies `Material.default` to all bones using the `*` wildcard, then overrides the `head_visor` and `eye_*` bones with their respective transparent and glowing materials.

{
  "format_version": "1.8.0",
  "render_controllers": {
    "controller.render.copper_automaton": {
      "geometry": "Geometry.default",
      "materials": [
        { "*": "Material.default" },
        { "head_visor": "Material.visor" },
        { "eye_*": "Material.eyes" }
      ],
      "textures": [
        "Texture.default"
      ]
    }
  }
}

Before writing a custom material file, check whether a built-in vanilla material already solves your problem. Vanilla materials are pre-compiled and cover the most common rendering scenarios for mobs, projectiles, and armor.

Choosing the wrong transparency material is a frequent source of visual bugs. If your texture only has fully opaque and fully invisible pixels (like cutouts on foliage or tattered cloth), use an alpha test material rather than alpha blend. Alpha blending is meant for smooth gradients like stained glass, and using it unnecessarily often causes sorting issues where distant bones draw on top of closer ones.

Custom blocks in the behavior pack do not use client entity files or `entity.material` definitions. Instead, they configure their rendering directly inside the `minecraft:material_instances` block component, which maps block faces or geometry material names to textures and a simplified set of render methods.

The `render_method` field inside a material instance serves the same purpose as an entity material, selecting a pre-defined pipeline for the block. You can also toggle `face_dimming` and `ambient_occlusion` booleans inside each instance to make block faces appear self-lit or flatly shaded.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "example:tinted_lantern"
    },
    "components": {
      "minecraft:geometry": "geometry.tinted_lantern",
      "minecraft:material_instances": {
        "*": {
          "texture": "tinted_lantern_frame",
          "render_method": "alpha_test"
        },
        "glass": {
          "texture": "tinted_lantern_glass",
          "render_method": "blend",
          "ambient_occlusion": false,
          "face_dimming": false
        }
      }
    }
  }
}

When none of the vanilla entity materials match your needs—for example, if you want an `entity` material that disables backface culling while also using additive blending for a ghost effect—you can define a custom material in `RP/materials/entity.material`. This file merges with the vanilla material registry.

Custom materials use an inheritance syntax: `"custom_name:parent_name"`. By inheriting from a vanilla parent such as `entity_static` or `entity_alphatest`, your material automatically receives the correct RenderDragon shader and vertex definitions. You can then add or remove pipeline states using `+states` and `-states`, or alter how source and destination pixels combine using `blendSrc` and `blendDst`.

{
  "materials": {
    "version": "1.0.0",
    "example_ghost:entity_alphablend": {
      "+states": [
        "DisableCulling",
        "DisableDepthWrite"
      ],
      "blendSrc": "SourceAlpha",
      "blendDst": "One"
    },
    "example_solid_cull:entity_alphatest": {
      "-states": [
        "DisableCulling"
      ]
    }
  }
}

Client entity materials, render controllers, and RP/materials/entity.material work in all current Bedrock versions (1.8.0+ format) without experimental toggles. The block minecraft:material_instances component is stable in format_version 1.19.40 and above.

Read out of the game itself, so the ids match the version you are building for.