How to add a Custom Block

Minecraft's behavior packs and resource packs allow you to create custom content for the game. Custom blocks are a great way for creators to start adding interactive content for Players. Through this tutorial, you will build a new block that will be called canvas block that has different textures and can be placed in the world by a Player.

Image of Alex holding the completed custom block

In this tutorial you will learn the following:

  • How to use JSON to define a new block.
  • How to assign textures to a new block.
  • Some of the behaviors and components that blocks can access.
  • What .lang is and how it's used for in-game text.


It’s recommended that the following be completed before beginning this tutorial:

You will also need the following:


Holiday Creator Features contain experimental gameplay features. As with all experiments, you may see additions, removals, and changes in functionality in Minecraft versions without significant advanced warning.

To learn more about Experimental Features, please visit Experimental Features in Minecraft: Bedrock Edition

Setting up the Resource JSON File

Block entity definitions are handled differently in the resource pack. Blocks are stored in a single JSON file that will contain definitions for each custom block.

  1. Open your com.mojang folder.
  2. Double-click on the folder development_resource_packs to open it.
  3. Open the My_RESOURCE_Pack folder. If you do not have this folder, please refer to the tutorials in the Requirements section of this document.
  4. Inside the My_RESOURCE_Pack folder, create a text document and name it blocks.json.
  5. Double-click on blocks.json to open it in a text editor.


The blocks.json file has a similar set up to the manifest.json file and has requirements that need to be met in order for it to work correctly. The canvas block will use a custom texture for four of the sides, and a different texture for the top and bottom that you are going to bring over from the Vanilla Resource Pack.

  1. Copy the following text and paste it into your blocks.json file.

    "format_version": "1.16.0",
      "helloworld:canvasblock": {
        "textures": {
            "up": "log_oak_top",
            "down": "log_oak_top",
            "side": "canvasblock"
  2. Save the file.

Textures and Sub-textures

As shown in the JSON code above, the canvas block is using two textures. The top and bottom are using the existing log_oak_top.png while the other sides are using a custom texture. Blocks can also be assigned a single texture to cover every side of a block with the same texture.

"textures": "canvasblock"

Textures can be broken down into sub-texture groups. up, down, and side are all sub-textures that allow a creator to define which face gets a certain texture. side can also be broken down into cardinal directions north, east, south , and west.


With the block defined in the blocks.json file, the next step is to associate the texture names with a texture file path. This is done in a terrain_texture.json file.

  1. In File Explorer, navigate to the My_RESOURCE_Pack folder and open the textures folder.

  2. Inside the textures folder, create a text document and name it terrain_texture.json.

  3. Double-click on terrain_texture.json to open it in a text editor.

  4. Copy and paste the following code into terrain_texture.json:

      "resource_pack_name": "My_BEHAVIOR_Pack",
      "texture_name": "atlas.terrain",
      "padding": 8,
      "num_mip_levels": 4,
      "texture_data": {
        "canvasblock": {
          "textures": "textures/blocks/canvasblock"
          "textures": "textures/blocks/log_oak_top"
  5. Save the file.

The Canvas Texture

A PNG file that can be downloaded and used in place of a custom texture made in a photo editor

The canvas block texture will need to be created and placed in the Resource Pack.


The image above has been provided for the canvasblock.png but feel free to use a different texture.

If you are using the one provided:

  1. Download the file to your computer.
  2. Place canvasblock.png in the My_RESOURCE_Pack/textures/blocks folder.

If you are creating a custom one:

  1. Check that the Width and Height to are set 16 each.
  2. Save the file as canvasblock.png in the My_RESOURCE_Pack/textures/blocks folder.

Adding the log_oak_top.png

The log_oak_top.png file will also need to be added to the texture folder in the behavior pack because the terrain_texture.json file will look for both textures in the My_RESOURCE_Pack folder.

  1. Navigate to the Vanilla_Resource_Pack\textures\blocks folder and copy log_oak_top.png.
  2. Navigate to My_RESOURCE_Pack/textures/blocks and paste a copy of log_oak_top.png.

Setting up the Behavior JSON file

With the work in the resource pack done, the behavior pack will need to be updated with the canvas block's components.

  1. In File Explorer, navigate to the folder My_BEHAVIOR_Pack, located in the development_behavior_packs folder.
  2. Inside the My_BEHAVIOR_Pack folder, create a folder and name it blocks.
  3. Double-click on blocks to open the folder.
  4. Inside the blocks folder, create a text document and name it canvasblock.json.
  5. Double-click on canvasblock.json to open it in a text editor.


In the file, you will need to define what the block is, similar to the manifest.json file.

  1. Copy and paste the following code into your canvasblock.json file:
    "format_version": "1.16.0",
    "minecraft:block": {
        "description": {
            "identifier": "helloworld:canvasblock",
            "is_experimental": false,
            "register_to_creative_menu": true
        "components": {
            "minecraft:destroy_time": 1,
            "minecraft:explosion_resistance": 5,
            "minecraft:friction": 0.6,
            "minecraft:flammable": {
                "flame_odds": 0,
                "burn_odds": 0
            "minecraft:map_color": "#FFFFFF",
            "minecraft:block_light_absorption": 0,
            "minecraft:block_light_emission": 0.250
  1. Save the file.

The identifier that was used in the resource pack is defined here. The block is also set to appear in the creative menu and is not set as an experimental piece of content.

  • destroy_time is how many player hits does it take to destroy this block.
  • explosion_resistance is how resistent the block is to explosions. Higher values mean the block is less likely to break.
  • friction is used to drive player and entity speeds while stepping on this block. Wood and dirt are set to a friction of 0.6 while ice is set to 0.1.
  • flammable is used to contain properties on how the block handles fire events.
    • flame_odds is how likely the block is to catch fire.
    • burn_odds is how likely the block is to be destroyed when on fire.
  • map_color is the color, in hex format, that is used by the map in order to symbolize the block.
  • block_light_absorption is how much light the block absorbs. Value uses a range of 0 to 1 as an input.
  • block_light_emission is how much light the block produces. Value uses a range of 0 to 1 as an input.

Setting the block name with .lang

Now that both of the packs are set up and completed, the last thing is to add the name of the block using a .lang file.

  1. In File Explorer, navigate to the folder My_RESOURCE_Pack.
  2. Inside the My_RESOURCE_Pack folder, create a folder and name it texts.
  3. Double-click on texts to open the folder.
  4. Inside the texts folder, create a new text document and name it en_US.lang.
  5. Double-click on en_US.lang to open it in a text editor.


.lang is a file type that Minecraft uses to provide in-game text for different languages for concepts within Add-Ons. .lang files are used as a convenient way to organize all custom text within an Add-On in a single location and for localizing creator content.

  1. Copy and paste the following into en_US.lang: Block
  2. Save and close the file.

This code sets the name of the block to be Canvas Block in the game.

Testing the block

With the canvas block defined in both the behavior pack and resource pack, you can now test it in-game.


You will need to have a Minecraft world where cheats are enabled in order to add the block to your inventory.

You will also need to have both My_RESOURCE_Pack and My_BEHAVIOR_Pack enabled in the world so you can get access to the canvas block.

  1. Open up the chat dialogue box (press T or Enter on Windows 10 OS).
  2. Type the following command: /give @p helloworld:canvasblock

What's Next?

With your first custom block completed, it is recommended to view the Block JSON reference documentation to learn more about how blocks are defined within Minecraft.