How to Make a Custom Block in Minecraft Bedrock (Add-on Guide)

Before you start

A custom block needs files in both packs, even though the block logic lives only in the behavior pack:

Unlike custom entities, blocks do not need a resource-pack definition file. The behavior-pack JSON plus the texture files are all the game needs.

The block file (behavior pack)

Create a new file at BP/blocks/ruby_block.json (the folder must be called blocks, plural). Here is the complete, minimal block definition:

{
  "format_version": "1.26.50",
  "minecraft:block": {
    "description": {
      "identifier": "myaddon:ruby_block",
      "menu_category": {
        "category": "construction"
      }
    },
    "components": {
      "minecraft:geometry": "minecraft:geometry.full_block",
      "minecraft:material_instances": {
        "*": {
          "texture": "myaddon_ruby_block"
        }
      }
    }
  }
}

Let us break down each part:

• format_version: set to "1.26.50". This is the block-file format, not the game version. Do not confuse it with the manifest format version.
• identifier: your block's unique ID. Use the pattern namespace:name (lowercase letters, digits, underscores). The minecraft namespace is reserved, so pick your own short name like myaddon.
• menu_category: controls which creative-inventory tab the block appears in. Valid values: construction, equipment, items, nature. Without this the block will not show in creative.
• minecraft:geometry: "minecraft:geometry.full_block" is the built-in 16×16×16 cube model. Since version 1.21.80 this is required for every custom block; omitting it causes a conflict with vanilla values.
• minecraft:material_instances: maps faces to textures. The key "*" means "all six faces." The value "myaddon_ruby_block" is a short name you will register in terrain_texture.json (next section). It is not a file path.

Add the texture (resource pack)

Two files in the resource pack make the block visible:

1. The PNG image

Create a 16×16 pixel PNG and save it as RP/textures/blocks/ruby_block.png. Any image editor works: Paint, Krita, GIMP, or an online pixel-art tool. For a standard cube block the image is 16 pixels wide and 16 pixels tall.

2. Register it in terrain_texture.json

Create (or edit) the file RP/textures/terrain_texture.json. The file name must be exactly terrain_texture.json: not terrain_textures.json or any other spelling.

{
  "resource_pack_name": "myaddon_rp",
  "texture_name": "atlas.terrain",
  "padding": 8,
  "num_mip_levels": 4,
  "texture_data": {
    "myaddon_ruby_block": {
      "textures": "textures/blocks/ruby_block"
    }
  }
}

• myaddon_ruby_block (the key): this is the short name you used in material_instances. It must match exactly.
• textures/blocks/ruby_block (the value): the path to the PNG without the .png extension, relative to the resource-pack root.
• texture_name: must be "atlas.terrain" for block textures.

Give it a name

Open RP/texts/en_US.lang and add one line:

tile.myaddon:ruby_block.name=Ruby Block

The pattern is tile.identifier.name=Display Name. The display name is what players see in the creative inventory and in their hotbar.

Get the block in-game

There are two ways to pick up your new block:

1. Creative inventory. Open the creative menu and look in the tab you set in menu_category (we used construction). Your Ruby Block should be there with its texture and name.
2. The /give command. Make sure cheats are enabled, then type:

/give @s myaddon:ruby_block

To get five at once: /give @s myaddon:ruby_block 5.

Make it glow, drop items, and more

The block file supports several extra components. Add them inside the "components" object alongside geometry and material_instances:

{
  "format_version": "1.26.50",
  "minecraft:block": {
    "description": {
      "identifier": "myaddon:ruby_block",
      "menu_category": {
        "category": "construction"
      }
    },
    "components": {
      "minecraft:geometry": "minecraft:geometry.full_block",
      "minecraft:material_instances": {
        "*": {
          "texture": "myaddon_ruby_block"
        }
      },
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 3
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 3
      },
      "minecraft:map_color": "#ff3355",
      "minecraft:light_dampening": 0,
      "minecraft:light_emission": 4,
      "minecraft:loot": "loot_tables/blocks/ruby_block.json"
    }
  }
}

Here is what each added component does:

• minecraft:destructible_by_mining: seconds_to_destroy sets how long it takes to break the block with an appropriate tool. Lower = harder.
• minecraft:destructible_by_explosion: explosion_resistance controls how well the block survives explosions. Higher = more resistant.
• minecraft:map_color: a hex colour (e.g. "#ff3355") used when the block appears on a map.
• minecraft:light_dampening: how much the block blocks light. 0 means it lets all light through (useful for glass-like blocks). The default for opaque blocks is 15.
• minecraft:light_emission: the light level the block gives off (0 to 15). Set it to 4 for a soft glow, 14 for near-full brightness (like a lantern).
• minecraft:loot: a path to a loot-table JSON file in the behavior pack (e.g. loot_tables/blocks/ruby_block.json). If you remove this component, the block drops itself by default.

What changed recently (and why old tutorials may be wrong)

Block add-ons have changed a lot in the last year. If you are following an older tutorial, watch out for these:

• 1.21.80: Explicit minecraft:geometry became required for all custom blocks. Tutorials from before this version that skip it will produce a "dirt block with a question mark" in-game.
• 1.26.20: The old tag:* components were removed. Use "minecraft:tags": ["minecraft:is_shears_item_destructible"] instead. Also, ambient_occlusion must now be a float (e.g. 0.5), not a boolean.
• 1.26.30: lava_flammable added to the flammable component; culling_shape released.
• 1.26.40: minecraft:multi_block trait and minecraft:instrument_sound released from experimental. N-way and sixteen-way rotation no longer need the "Upcoming Creator Features" toggle.
• 1.26.50: minecraft:sound and minecraft:block_entity released from experimental. You can now set block sounds directly in the BP component instead of using blocks.json.
• Holiday Creator Features: This experimental toggle no longer exists. You do not need to enable any experiment to create basic custom blocks, items, or entities on the current stable version.

Common mistakes (and how to fix them)

1. Black-and-magenta checkerboard texture. The short name in material_instances does not match the key in terrain_texture.json, or the file path is wrong. Check both spellings character by character.
2. Dirt block with a "?" (the "unknown block"). The JSON is invalid, the identifier was changed after you already placed it, or you are missing minecraft:geometry / minecraft:material_instances.
3. Transparent pixels render as solid. Add "render_method": "alpha_test" inside the material instance: "*": { "texture": "myaddon_ruby_block", "render_method": "alpha_test" }.
4. Block has a shadow it should not. Add "minecraft:light_dampening": 0.
5. Block not in the creative inventory. You forgot menu_category, or the pack is not activated in the world settings.
6. Wrong file name for the texture JSON. It must be exactly terrain_texture.json in RP/textures/. Not terrain_textures.json, not terrain_texture.json.txt.
7. Using old tag:* components. These were removed in format 1.26.20. Use "minecraft:tags" (an array of tag strings) instead.
8. JSON syntax error. One missing comma or extra comma breaks the entire file silently. Paste your JSON into a validator (like jsonlint.com) to check. Note: Minecraft does accept // comments in JSON, but online linters will flag them. That is fine; the game will still read the file.
9. Edits not showing. If your packs are in the normal behavior_packs / resource_packs folders, the game may be using a cached copy. Move them to development_behavior_packs / development_resource_packs, then exit and re-enter the world.

FAQ

Do I need an experimental toggle?

No. Basic custom blocks (geometry, material_instances, hardness, light, loot) work on the current stable version with no experiments enabled.

Can I override a vanilla block (like stone or dirt)?

No. Vanilla blocks are hard-coded into the game. You can only add new blocks with your own identifier.

Do I need a blocks.json file in the resource pack?

Not for basic blocks. Since 1.26.50 the minecraft:sound component in the behavior-pack file handles sounds directly. blocks.json is only a legacy option for older setups.

What size should my block texture be?

16×16 pixels for a standard cube block using minecraft:geometry.full_block. If you use a custom geometry from Blockbench, the texture size must match the texture_width and texture_height set in that model.

Can I make a block that is not a cube?

Yes. Build a custom model in Blockbench (Bedrock Block format), export the geometry JSON, and reference its geometry identifier in the minecraft:geometry component instead of "minecraft:geometry.full_block". The rest of the setup (texture, name, components) stays the same.

My block shows up but the texture is missing. What now?

Check three things: (1) the PNG is at the correct path in the resource pack, (2) the key in terrain_texture.json matches the short name in material_instances exactly, (3) the path value in terrain_texture.json points to the right folder and file name (without the .png extension).

Do I need to restart Minecraft after editing a file?

If your packs are in the development_* folders, exiting and re-entering the world is usually enough. If they are in the normal pack folders, a full restart of Minecraft is safer because of caching.