How Materials Work in Bedrock
Despite having a `.material` file extension, material definitions in a resource pack are written in standard JSON. They do not contain actual shader code that you can edit directly under the RenderDragon engine. Instead, a material file configures fixed-function graphics pipeline states—such as depth testing, backface culling, and alpha blending—and binds your geometry to pre-compiled internal vertex and fragment shaders.
Every custom material you write for an entity or particle lives inside the `RP/materials/entity.material` file. The game merges your pack's `entity.material` with the vanilla file on load. Rather than writing every render rule from scratch, Bedrock materials use a strict inheritance model. You pick a vanilla base material that is close to what you want, inherit from it using a colon separator, and override only the specific flags or states that need changing.
Blocks handle materials slightly differently than entities. While entities reference names defined inside `.material` files, custom blocks declare their visual behavior directly inside their behavior pack definition using the `minecraft:material_instances` component, selecting from a fixed list of hardcoded render methods.
Defining a Custom Entity Material
To create a new material for an entity or attachable, create a file at `RP/materials/entity.material`. Inside the root `materials` object, you must declare a `version` string (always `1.0.0`) alongside your custom material definitions. The key for each definition follows the format `custom_name:parent_material_name`.
Inside your material object, you modify arrays using prefix operators. Using a plus sign (`+`) adds a state, variant, or define to the list inherited from the parent, while a minus sign (`-`) strips an inherited property away. This lets you take a standard opaque entity material and turn it into an additive, glowing, double-sided material in just a few lines.
{
"materials": {
"version": "1.0.0",
"ghost_glow:entity_alphatest": {
"-defines": [
"ALPHA_TEST"
],
"+defines": [
"USE_EMISSIVE"
],
"+states": [
"Blending",
"DisableCulling",
"DisableDepthWrite"
],
"blendSrc": "SourceAlpha",
"blendDst": "One"
}
}
}Common Material Properties and States
When overriding a parent material, you work primarily with three arrays: `states`, `defines`, and `variants`. The `states` array controls the hardware rasterizer and output merger stages. The `defines` array passes preprocessor macros to the underlying compiled shader, toggling features like emissive glow, UV animation, or color tinting.
If you enable the `Blending` state, you can also specify `blendSrc` and `blendDst` to control the math used when combining your entity's pixels with the background pixels already on screen. Standard alpha transparency uses `SourceAlpha` and `OneMinusSrcAlpha`, whereas additive light effects pair `SourceAlpha` with `One`.
| Property / Value | Category | What it does |
|---|---|---|
| DisableCulling | states | Renders both the front and back faces of polygons. Useful for flat planes like wings, capes, or foliage. |
| Blending | states | Enables semi-transparency and blend factor evaluation. Usually paired with DisableDepthWrite. |
| DisableDepthWrite | states | Stops the geometry from writing to the depth buffer, preventing transparent pixels from occluding objects behind them. |
| InvertCulling | states | Flips which side of a face is considered the front. Used for inverted hull outline tricks. |
| ALPHA_TEST | defines | Discards pixels below an alpha threshold. Creates hard cutouts without sorting issues. |
| USE_EMISSIVE | defines | Tells the shader to use the alpha channel of the texture to control brightness in the dark. |
| USE_COLOR_MASK | defines | Allows the material to be tinted dynamically by a color component or entity color. |
Applying the Material to an Entity
Declaring a material in `entity.material` does nothing until an entity, attachable, or particle references it. For an entity, you first map a short alias to your full material identifier inside the client entity file (`RP/entity/my_entity.entity.json`) under the `materials` object.
Once mapped in the client entity definition, the material is assigned to actual geometry bones via a render controller. In the render controller's `materials` array, you pair bone name patterns (using wildcards like `*`) with the short alias you defined in the client entity.
{
"format_version": "1.10.0",
"minecraft:client_entity": {
"description": {
"identifier": "custom:specter",
"materials": {
"default": "entity_alphatest",
"glow_layer": "ghost_glow"
},
"textures": {
"default": "textures/entity/specter"
},
"geometry": {
"default": "geometry.specter"
},
"render_controllers": [
"controller.render.specter"
]
}
}
}Configuring Block Material Instances
Custom blocks do not read from `RP/materials/entity.material`. Instead, you configure their surface rendering directly inside the behavior pack block JSON using the `minecraft:material_instances` component. Each key inside this component represents a face name or a custom alias (with `*` acting as the catch-all default instance).
Within an instance, the `render_method` property serves the same role as a base material, letting you choose between `opaque`, `alpha_test`, `blend`, or `double_sided`. You can also control lighting properties like `ambient_occlusion` and `face_dimming` directly on the instance without touching resource pack material files.
{
"format_version": "1.20.60",
"minecraft:block": {
"description": {
"identifier": "custom:crystal_glass"
},
"components": {
"minecraft:geometry": "minecraft:geometry.full_block",
"minecraft:material_instances": {
"*": {
"texture": "crystal_glass_tex",
"render_method": "blend",
"ambient_occlusion": false,
"face_dimming": false
}
}
}
}
}Which versions this applies to
Custom entity materials (`entity.material` version 1.0.0) and client entity definitions (`1.10.0`) are stable across all modern Bedrock versions and require no experimental toggles. Block `minecraft:material_instances` is stable in format versions `1.19.40` and newer without experimental toggles.
When it does not work
| What you see | Why | The fix |
|---|---|---|
| Content Log shows `[Materials][error]Material <name> is missing a parent` or entity renders completely invisible. | You defined a new material in `RP/materials/entity.material` without inheriting from an existing vanilla material using the colon syntax, or you misspelled the parent material name. | Ensure the key in `entity.material` is written as `"your_material:parent_material"` (for example, `"custom_mat:entity_alphatest"`). Because custom shader paths are locked in RenderDragon, you must inherit the compiled shader paths from a valid vanilla parent. |
| Parts of the entity model disappear when viewed through other semi-transparent parts of the same model. | The material has the `Blending` state enabled, but it is still writing to the depth buffer. Whichever bone renders first blocks any polygons behind it from drawing. | Add `"DisableDepthWrite"` to the `"+states"` array in your material definition so translucent faces do not occlude geometry behind them. |
| Texture areas that should be transparent render as glowing white or bright neon colors. | Your material inherits from `entity_emissive` or adds `"USE_EMISSIVE"` to `defines`, while your texture uses standard alpha transparency. In Bedrock's emissive shaders, the texture's alpha channel controls glow intensity rather than opacity (0 alpha is normal, 255 alpha is unlit/glowing). | If you need both transparency and glow, use `entity_emissive_alpha` as the parent material. In that setup, completely transparent pixels (alpha 0) are discarded, partially transparent pixels glow in the dark, and fully opaque pixels (alpha 255) render with normal world lighting. |
Reference, straight from the game files
Read out of the game itself, so the ids match the version you are building for.