Intro to Blocks

guide

beginner

FORMAT & MIN ENGINE VERSION 1.20.30

This page discusses basic block features. You can learn more about other block components here.

Vanilla blocks are hardcoded. You may not override or access them.

Minecraft Bedrock allows us to add custom blocks into our world with various vanilla-like properties. Custom blocks can have multiple stages (like plants), directional facing, and other useful features.

This tutorial will cover how to create basic blocks for the stable version of Minecraft.

Registering Blocks

Block definitions are structured similarly to entities: they contain a description and a list of components that defines the block's behavior.

Unlike entities, blocks do not have a resource definition other than in RP/blocks.json.

Below is the minimum behavior-side code to get a custom block into the creative inventory.

BP/blocks/custom_block.jsonCopy

json

{
  "format_version": "1.20.30",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:custom_block",
      "menu_category": {
        "category": "construction", // The creative inventory or recipe book tab that the block is placed into
        "group": "itemGroup.name.concrete", // The expandable group that the block is a part of. (Optional)
        "is_hidden_in_commands": false // Is the block hidden from use in commands? (Optional)
      }
    },
    "components": {} // Must be here, even if empty!
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Block Description

Defines the block's identifier - a unique ID in the format of namespace:identifier.
Configures which menu_category the block is placed into.
- Also takes the optional parameters group and is_hidden_in_commands.

The block description is also home to states and traits, which are covered in their own pages.

Adding Components

Right now, our custom block is using the default component values (which can be found here).

Let's configure our own functionality!

BP/blocks/custom_block.jsonCopy

json

{
  "format_version": "1.20.30",
  "minecraft:block": {
    "description": {
      "identifier": "wiki:custom_block",
      "menu_category": {
        "category": "construction"
      }
    },
    "components": {
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 3
      },
      "minecraft:destructible_by_explosion": {
        "explosion_resistance": 3
      },
      "minecraft:friction": 0.4,
      "minecraft:map_color": "#ffffff",
      "minecraft:light_dampening": 0,
      "minecraft:light_emission": 4,
      "minecraft:loot": "loot_tables/blocks/custom_block.json"
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

minecraft:destructible_by_mining defines how long the player will need to mine the block until it breaks. Currently, it isn't possible to set different destroy times for different tools.
minecraft:destructible_by_explosion defines the resistance to explosions. The higher the value, the lower the chance of destruction.
minecraft:friction defines how much friction the block has. For example, soul sand has a high value for friction, so it slows the players. Ice has a lower friction value, so it has a slippery effect. The friction of classic blocks such as wood or stone is 0.4.
minecraft:map_color is the hex color code that will be displayed on a Minecraft map to represent this block. #ffffff means white. You can get hex codes for other colors here.
minecraft:light_dampening defines how much light will be blocked from passing through.
minecraft:light_emission defines the light level the block will output.
minecraft:loot defines a loot table path for the block to drop. If this is removed, then the block will drop itself. You can learn more about loot tables here.

Browse more block components here!

Applying Textures

WARNING

RP/blocks.json ignores identifier namespaces. You can put anything there or not include a namespace at all, resulting in no difference. This may cause problems if you create a custom block with the same name (but not namespace) as an existing vanilla block.

Block sounds can also be defined within RP/blocks.json.

For our basic 16×16×16 pixel block, textures should be defined in RP/blocks.json.

If you'd like to apply a custom model, the geometry and material instances components should be used instead.

RP/blocks.jsonCopy

json

{
  "format_version": [1, 1, 0],
  "wiki:custom_block": {
    "textures": "custom_block", // This texture shortname should be defined in `terrain_texture.json`, as shown below
    "sound": "grass"
  }
}

1
2
3
4
5
6
7

Now, we need to link the texture shortname to an image file path in RP/textures/terrain_texture.json:

RP/textures/terrain_texture.jsonCopy

json

{
  "texture_name": "atlas.terrain",
  "resource_pack_name": "wiki", // ID for your resource pack
  "padding": 8, // Prevent textures from visually overflowing into each other
  "num_mip_levels": 4, // Quality of texture when viewed from a distance or at an angle
  "texture_data": {
    // Our texture shortname:
    "custom_block": {
      "textures": "textures/blocks/custom_block" // Link to an image file name
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12

Per-Face Textures

Textures can also be applied per face. For example, a custom "compass block" could use the following ✨stunning✨ textures:

textures/blocks/compass_block_down.png

textures/blocks/compass_block_up.png

textures/blocks/compass_block_north.png

textures/blocks/compass_block_east.png

textures/blocks/compass_block_south.png

textures/blocks/compass_block_west.png

The blocks.json entry would look like this:

RP/blocks.jsonCopy

json

{
  "format_version": [1, 1, 0],
  "wiki:compass_block": {
    "textures": {
      "down": "compass_block_down",
      "up":  "compass_block_up",
      "north":  "compass_block_north",
      "east": "compass_block_east",
      "south":  "compass_block_south",
      "west": "compass_block_west"
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

Or, if you're using material instances, they should look like this:

minecraft:block > componentsCopy

json

"minecraft:material_instances": {
  "*": {
    "texture": "compass_block_down" // This texture appears in destruction particles
  },
  "up": {
    "texture": "compass_block_up"
  },
  "north": {
    "texture": "compass_block_north"
  },
  "east": {
    "texture": "compass_block_east"
  },
  "south": {
    "texture": "compass_block_south"
  },
  "west": {
    "texture": "compass_block_west"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

With the following terrain_texture.json data:

RP/textures/terrain_texture.jsonCopy

json

{
  "texture_name": "atlas.terrain",
  "resource_pack_name": "wiki",
  "padding": 8,
  "num_mip_levels": 4,
  "texture_data": {
    "compass_block_down": {
      "textures": "textures/blocks/compass_block_down"
    },
    "compass_block_up": {
      "textures": "textures/blocks/compass_block_up"
    },
    "compass_block_north": {
      "textures": "textures/blocks/compass_block_north"
    },
    "compass_block_east": {
      "textures": "textures/blocks/compass_block_east"
    },
    "compass_block_west": {
      "textures": "textures/blocks/compass_block_west"
    },
    "compass_block_south": {
      "textures": "textures/blocks/compass_block_south"
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Defining Names

Finally, let's define our block names like this:

RP/texts/en_US.langCopy

tile.wiki:custom_block.name=Custom Block
tile.wiki:compass_block.name=Compass Block

1
2

You can learn more about translation here.

Result

In this page, you've learnt about the following:

Basic features of blocks

How to apply a texture to all block faces

How to apply textures per face

...but it's only the beginning, see what else you could do below!

What's Next?

Expand Functionality

Learn about the available block components to craft unique gameplay.

Why not give your block a custom model with the geometry component? You could also configure your own collision and selection boxes to match!

Create Variants

Make use of block states and permutations to conditionally enable components on your blocks.

For example, you could add liquid depth levels to your custom tank block, with support for multiple liquid types.

Replicate Vanilla

Browse several complete replicas of existing blocks in the Vanilla Re-Creations category.

Start simple with custom glass blocks, making use of material instances!

Edit Intro to Blocks on Github.