Introduction to Custom Blocks

When you create a custom block, you work across both the Behavior Pack (BP) and the Resource Pack (RP). The Behavior Pack holds the main block definition inside the BP/blocks/ folder. One file per block is the standard convention. This JSON file assigns the block its unique identifier, puts it into the Creative inventory, and lists components that control hardness, collision, light emission, and even which geometry and textures to use.

The Resource Pack does not need a matching file per block. Instead, it uses a single master registry at RP/blocks.json (for vanilla-style cube blocks) and a texture atlas at RP/textures/terrain_texture.json. The terrain atlas assigns short string names to your actual PNG files so that either RP/blocks.json or the BP's material instances component can reference them without typing out full file paths.

Every custom block starts with a JSON file in BP/blocks/. At the top of the file, format_version tells the game which parser rules to use; stick to a modern version like 1.20.80 so you have access to stable components without needing experimental toggles. Inside minecraft:block, the description object sets the identifier and optionally places the block in the Creative menu.

Your identifier must have a namespace followed by a colon and the block name, all in lowercase. Never use minecraft as your namespace for custom blocks—the game rejects or breaks custom content that tries to register under the reserved vanilla namespace.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "my_pack:slate_tile",
      "menu_category": {
        "category": "construction",
        "group": "itemGroup.name.stoneBrick"
      }
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.0
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 6.0
      },
      "minecraft:light_emission": 0,
      "minecraft:map_color": "#3b3d42"
    }
  }
}

Without any components, a custom block uses default fallbacks: it breaks almost instantly, has a standard 16x16x16 unit collision box, and emits no light. You customize this behavior by adding entries to the components object. If you have looked at older packs, you might see names like minecraft:destroy_time or minecraft:block_light_emission; those were experimental names from the 1.16 to 1.18 era and have been replaced by stable equivalents.

The table below covers the foundational components you will put on almost every block you make.

There are two ways to texture a block in Bedrock. The first—and simplest for a standard six-sided cube—is to register the block inside RP/blocks.json in your Resource Pack. There you assign a sound preset and a texture shortname, either one for the whole block or an object specifying up, down, north, south, east, and west.

That shortname is then mapped to a real PNG file inside RP/textures/terrain_texture.json. Always omit the .png file extension in your JSON; the game resolves extensions automatically.

{
  "format_version": "1.20.80",
  "my_pack:slate_tile": {
    "textures": "slate_tile_tex",
    "sound": "stone"
  }
}

Once RP/blocks.json knows the shortname slate_tile_tex, you must define that shortname inside RP/textures/terrain_texture.json. If your PNG is located at RP/textures/blocks/slate_tile.png, your atlas file looks like this.

If you later want a custom 3D model made in Blockbench instead of a plain cube, you can skip the textures line in RP/blocks.json and instead put the minecraft:geometry and minecraft:material_instances components directly inside your Behavior Pack block file. Even when you do that, you still register the texture shortname in terrain_texture.json the exact same way.

{
  "resource_pack_name": "my_pack",
  "texture_name": "atlas.terrain",
  "padding": 8,
  "num_mip_levels": 4,
  "texture_data": {
    "slate_tile_tex": {
      "textures": "textures/blocks/slate_tile"
    }
  }
}

When you load into a world and pull your new block out of the Creative menu, its hover tooltip will read tile.my_pack:slate_tile.name. Bedrock automatically builds this localization key by putting tile. in front of your full identifier and .name at the end.

To give it a clean display name, open or create RP/texts/en_US.lang and add a single line matching that key.

tile.my_pack:slate_tile.name=Slate Tile

Applies to Minecraft Bedrock 1.20.80 and newer. Everything shown on this page is part of the stable API and requires no experimental toggles on the world.

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