blockbench-pbr-materials

Blockbench PBR Materials

Use get_capabilities to inspect the active project and registered format features, including pbr. Check list_textures and list_materials before assigning existing assets. Texture and material references accept names or UUIDs; prefer returned UUIDs when names overlap.

Preserve the target's material convention. Bedrock MER is not glTF metallic/roughness or an arbitrary ORM packing. A successful Blockbench preview does not prove that a chosen exporter or game supports the material. Align channel maps to the color texture's UV layout and inspect their dimensions before painting. Shared UV and delivery checks are in format and delivery guidance.

Use PBR for Surface Detail

Follow the selected appearance/performance preference. Use aligned normal or height detail for small fasteners, rivets, welds, grooves, and shallow seat ribs instead of multiplying tiny cubes. Add regional metalness and roughness variation in MER; a shared atlas can represent aluminum, rubber, and painted markings without a separate material for each visible surface. Author valid channel data rather than treating an albedo image as a normal/MER map. To derive normal, height or MER maps from an existing color texture, use albedo to normal and import the results with create_texture before assigning them here.

Normal/height shading does not create silhouette thickness, open railing holes, or collision. Preserve geometry where these matter. Confirm the destination's rendering mode actually uses PBR, retain a readable color-only fallback, and account for the memory cost of extra maps. Bedrock's Classic pipeline uses the color layer; normal and heightmap are mutually exclusive texture-set layers. See the official texture-set specification.

Use UV scale and distortion guidance to keep surface relief and material grain at a consistent scale across parts. Align corresponding regions across every channel even when image resolutions differ. UV or atlas edits must preserve those correspondences; verify tangent-space normal orientation after rotation/mirroring. A solid color does not justify stretching a detailed normal or roughness map.

PBR texture groups and .texture_set.json describe surface channels. They do not assign Bedrock block faces to render materials. Use Bedrock material instances for those bindings and accompanying pack files.

Tools and Parameter Names

These are flat tool arguments. Do not wrap channels in textures or settings in config, and do not use material_id, texture_id, or output_path for these PBR tools.

Channel and Value Rules

• Use normal or height in one material. To change between them, remove the old channel in the same configure_material call.
• Use a separate texture for each assigned channel. Replacing a channel detaches its old texture from the material; it does not delete the image.
• Uniform values require no texture assigned to that channel; supplying them while a map remains assigned returns an error. Remove a MER map with mer_texture="none" when switching to mer_value.
• A MER texture requires a color texture in the current Blockbench preview. For uniform color, use uniform MER too.
• Moving a texture to another material changes its group. When moving a color texture away, clear or move its source material's MER texture first so the source remains valid.
• subsurface_value is one number from 0–255; it is not an RGB object. Game/export support depends on the target.

Create a Material

create_texture: name="stone_color", width=16, height=16,
  fill_color="#808080", layer_name="base"
create_texture: name="stone_normal", width=16, height=16,
  fill_color="#8080FF", layer_name="base"

create_pbr_material: name="stone", color_texture="stone_color",
  normal_texture="stone_normal", mer_value=[0, 0, 230]
# → {success, material: {name, uuid, is_material, channels}}

get_material_info: material="stone"

layer_name is required whenever create_texture supplies fill_color. Retain material.uuid from the create response and use its value in subsequent material arguments. The names above work when unique. This example uses a matte nonmetal MER value; 230/255 is approximately 90% roughness.

Edit and Replace Channels

Replace a normal map with another already-created normal texture:

assign_texture_channel: material="stone", texture="stone_normal_v2", channel="normal"

Switch from normal to an already-created height map in one call:

configure_material: material="stone", normal_texture="none", height_texture="stone_height"

The referenced replacement texture must exist; discover its UUID with list_textures. Use get_material_info afterward to verify the new assignment. These project edits are recorded for the dedicated undo / redo tools; undoing a channel replacement restores both the replaced and incoming texture's assignments.

Uniform Properties

With an existing material named stone, clear any MER map before setting uniform values:

configure_material: material="stone", mer_texture="none", mer_value=[0, 0, 204]

To use uniform color, clear both the color and MER textures in the same call:

configure_material: material="stone", color_texture="none", mer_texture="none",
  color_value=[128, 128, 128, 255], mer_value=[0, 0, 204]

Paint and Assign a MER Map

Create a MER texture and assign it together with the material's color texture:

create_texture: name="stone_mer", width=16, height=16,
  fill_color=[0, 0, 204, 255], layer_name="base"

# Metallic spot, retaining roughness at 204 and emission at zero
paint_with_brush: texture_id="stone_mer", coordinates=[{x: 8, y: 8}],
  brush_settings={color: "#FF00CC", size: 4}

# Emissive spot, retaining roughness at 204 and metalness at zero
paint_with_brush: texture_id="stone_mer", coordinates=[{x: 4, y: 4}],
  brush_settings={color: "#00FFCC", size: 2}

configure_material: material="stone", color_texture="stone_color", mer_texture="stone_mer"
get_material_info: material="stone"

A brush color writes all RGB channels. Encode the properties you intend to preserve in that color instead of assuming a red or green brush isolates one channel.

Inspect, Import, and Export

list_materials
# → [{name, uuid, channels: {color, normal, height, mer}, config}]

get_material_info: material="stone"
# → {name, uuid, is_material, textures, config, texture_set_json}

import_texture_set: path="C:/packs/textures/stone.texture_set.json"

Import needs a readable file and its referenced images on the Blockbench desktop host. Inspect the imported material before editing it.

For export, first save the color image through Blockbench so it has a valid file path. get_material_info exposes config.file_path and a texture_set_json preview. The save tool derives the .texture_set.json destination from the color image; it does not take an arbitrary output path:

save_material_config: material="stone"

New textures created only in memory do not have a save path. When the user only needs the JSON content, use the get_material_info preview. Saving a material config writes a disk file and is separate from undoable project edits. Verify the appearance in the intended game/rendering environment when that is part of the requested deliverable.