Your first custom block

In this guide you will make a Ruby Block: a shiny red cube that glows a little, takes a moment to mine and drops itself when broken. It is the "hello world" of block making, and every fancier block starts the same way.

There are two ways to do it. The quick way takes a few minutes on your phone. The by-hand way teaches you what every file does.

The quick way: GodCraft

GodCraft builds the block, its texture, its name and its loot for you. You never touch a JSON file.

1. Open the Workshop and add a Block to your add-on.
2. Paint the faces in the pixel editor, or start from a vanilla texture and recolor it.
3. Set how long it takes to mine, how much light it gives and what it drops.
4. Tap Export. GodCraft writes the manifests, UUIDs and language files and gives you a .mcaddon.

Want to know what happens under the hood? Keep reading.

By hand

You need a behavior pack (BP) and a resource pack (RP) that are already set up. If you have not made them yet, follow Project setup first. We will use the namespace myname; replace it with your own short name everywhere.

Here are all the files you will touch:

Step 1: the block file

Create this file in your behavior pack:

{
  "format_version": "1.26.50",
  "minecraft:block": {
    "description": {
      "identifier": "myname:ruby_block",
      "menu_category": {
        "category": "construction"
      }
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 3
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 6
      },
      "minecraft:friction": 0.4,
      "minecraft:light_emission": 4,
      "minecraft:map_color": "#9b1c2b",
      "minecraft:geometry": "minecraft:geometry.full_block",
      "minecraft:material_instances": {
        "*": {
          "texture": "ruby_block",
          "render_method": "opaque"
        }
      },
      "minecraft:loot": "loot_tables/blocks/ruby_block.json"
    }
  }
}

The description part says who the block is:

• identifier is the block's ID, made of your namespace and a name. You will type it in commands like /give @s myname:ruby_block.
• menu_category picks the creative inventory tab. The choices are construction, nature, equipment, items and none (hidden).

The components part says how it behaves:

• minecraft:destructible_by_mining: seconds_to_destroy is how long it takes to mine with your bare hand. Stone-like blocks sit around 1.5 to 3.
• minecraft:destructible_by_explosion: a bigger explosion_resistance means TNT and creepers have a harder time.
• minecraft:friction: a number from 0 to 0.9. Higher means more grip; ice-like blocks use a low value.
• minecraft:light_emission: a whole number from 0 (no light) to 15 (as bright as a torch or glowstone).
• minecraft:map_color: the color the block shows on a map, as a hex color.
• minecraft:geometry: the shape. minecraft:geometry.full_block is a plain cube, so you do not need a model file.
• minecraft:material_instances: which texture goes on which face. The key * means "every face". texture is a short name you will define in Step 3.
• minecraft:loot: the loot table to use when the block breaks.

Step 2: the texture

Draw a 16x16 pixel PNG and save it in your resource pack as RP/textures/blocks/ruby_block.png.

New to pixel art? The Pixel textures guide covers sizes, transparency and shading.

Step 3: give the texture a short name

Blocks do not point at PNG files directly. They use a short name from terrain_texture.json. If your pack already has this file, add the ruby_block entry to texture_data. If not, create it:

{
  "resource_pack_name": "myname",
  "texture_name": "atlas.terrain",
  "texture_data": {
    "ruby_block": {
      "textures": "textures/blocks/ruby_block"
    }
  }
}

Notice the path has no .png at the end. The game finds the file by itself.

Step 4: the sound

The resource pack's blocks.json tells the game which sound set to play when you walk on, place or break the block:

{
  "format_version": "1.21.40",
  "myname:ruby_block": {
    "sound": "stone"
  }
}

Other common sound sets used by vanilla blocks are wood, glass, metal, grass, sand, cloth, copper and deepslate.

Step 5: the name

Without a name, the game shows something like tile.myname:ruby_block.name. Add this line to your language file:

tile.myname:ruby_block.name=Ruby Block

Step 6: the loot

The loot table decides what drops. This one drops the block itself, once:

{
  "pools": [
    {
      "rolls": 1,
      "entries": [
        {
          "type": "item",
          "name": "myname:ruby_block"
        }
      ]
    }
  ]
}

Change name to any item ID, like minecraft:diamond, to make the block drop something else.

Test your block

1. Export and install both packs as shown in Export and install, then turn them on in a world.
2. Open the creative inventory and look in the Construction tab, or run /give @s myname:ruby_block. See /give.
3. Place it at night: it should glow softly.
4. Switch to survival and mine it. It should take a few seconds and drop itself.

Common problems

• The block is missing from the inventory. Check menu_category is not none, and that the behavior pack is turned on.
• The block has a weird name. The .lang line must use the full ID, including the namespace.
• The block drops nothing. Check the minecraft:loot path starts with loot_tables/ and matches the file name.

More fixes are in Troubleshooting.

What next

• Browse every block component in the reference, starting from material instances.
• Look at how Mojang builds its own blocks in Vanilla blocks.
• Ready for something alive? Try Your first custom mob.