Beginner's Guide to Minecraft Bedrock Add-ons

Every full-featured add-on is divided into two distinct folders: a Behavior Pack (often abbreviated as BP) and a Resource Pack (abbreviated as RP). Understanding the boundary between these two packs is the most important concept for a new creator. The game engine strictly separates how an object behaves on the server from how it looks and sounds on the client.

A Behavior Pack handles the logic, rules, and server-side state of the game. If you want a custom entity to attack players, a block to drop specific loot when mined, or an item to restore health when eaten, you define those rules inside the Behavior Pack. It contains files for entities, items, blocks, loot tables, crafting recipes, spawn rules, and scripts.

A Resource Pack handles the visual and auditory presentation. It contains PNG textures, 3D geometry models, animation files, sound files, and language localization strings. If you create a custom block in your Behavior Pack but forget to configure the Resource Pack, the block will still exist and function in the world, but it will appear as a magenta-and-black checkered cube with a raw identifier for a name.

Before writing any files, you need a proper text editor and access to Minecraft's development directories. Standard word processors will corrupt JSON files with hidden formatting characters, so you should use a dedicated code editor such as Visual Studio Code. For creating 3D models and textures later on, Blockbench is the standard tool because it exports directly to Bedrock's geometry formats.

On Windows, Minecraft stores add-ons inside its UWP application data folder. While finished packs are installed into the standard packs folders, you should always build your project inside the development folders. The game checks development folders for changes every time you exit and reload a world, meaning you do not have to re-import your pack after every small edit.

To find your workspace on Windows, press Windows Key + R to open the Run dialog, paste the path `%localappdata%\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang`, and press Enter. Inside this directory, locate `development_behavior_packs` and `development_resource_packs`. Create a new folder for your project inside each of them, such as `my_first_bp` and `my_first_rp`.

When you make a typo in a JSON file, Minecraft will not crash; instead, it will silently ignore the broken file or part of it. If you do not turn on the built-in debugging tools, you will have no way of knowing why your content failed to load.

Before creating a test world, open Minecraft and go to Settings, then select Creator from the left sidebar. Turn on both 'Enable Content Log File' and 'Enable Content Log GUI'. With these enabled, whenever you load into a world, any syntax errors or missing references in your packs will be printed directly onto the top of your screen for a few seconds. You can also press Ctrl + H while in a world to open the Content Log history screen and read the exact file path and line number where an error occurred.

For Minecraft to recognize a folder as an add-on, that folder must contain a file named `manifest.json` at its root. Both your Behavior Pack folder and your Resource Pack folder require their own separate manifest file. This file tells the game the pack's name, description, version, and whether it contains behaviors or resources.

The most critical part of a manifest is the `uuid` (Universally Unique Identifier). Every manifest requires two different UUIDs: one in the `header` object to identify the pack itself, and one in the `modules` array to identify the content module. You must generate fresh Version 4 UUIDs for every pack you make using an online UUID generator or a code editor extension. Never copy and paste UUIDs from another pack, and never reuse the header UUID in the module section.

In the example below, the module `type` is set to `data`, which tells Minecraft this is a Behavior Pack. When you create the matching `manifest.json` for your Resource Pack, the structure is identical except you must generate two new UUIDs and change the module `type` from `data` to `resources`.

{
  "format_version": 2,
  "header": {
    "name": "My First Behavior Pack",
    "description": "A starter behavior pack for learning add-on creation.",
    "uuid": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "description": "Behavior data module",
      "type": "data",
      "uuid": "f6e5d4c3-b2a1-4f5e-9d8c-7b6a5f4e3d2c",
      "version": [1, 0, 0]
    }
  ]
}

Once your manifest is in place, you add content by creating specific subfolders inside your pack. Bedrock expects exact folder names. For example, custom items go into `BP/items/`, custom blocks go into `BP/blocks/`, and recipes go into `BP/recipes/`. Within these folders, you can organize your JSON files into further subdirectories however you like, as the game scans the entire folder tree.

Every custom object you create requires an identifier formatted as `namespace:name`. The namespace is a short prefix unique to you or your project (for example, `wiki:ruby_sword` or `myname:copper_lamp`). You must use lowercase letters, numbers, and underscores only.

There is one strict rule regarding namespaces: never use `minecraft` as the namespace for your own custom content. The `minecraft:` namespace is reserved exclusively for vanilla game elements. You only use the `minecraft:` prefix in your files when you are overriding an existing vanilla file or referencing a built-in component, such as `minecraft:icon` or `minecraft:max_stack_size`.

To verify that your Behavior Pack works, you can add a simple custom item that uses an existing vanilla texture. Inside your Behavior Pack folder, create a subfolder named `items`, and inside that folder, create a file named `custom_gem.json`. This file uses a `format_version` to tell the engine which schema rules to apply, a `description` block to set the identifier and creative menu placement, and a `components` block to define how the item works.

In the code below, we assign the item to the `items` category in the Creative inventory, set its maximum stack size to 64, and tell it to use the built-in `emerald` texture via the `minecraft:icon` component. Because we are borrowing a vanilla icon name, this item will display properly in-game even before you set up a custom texture in your Resource Pack.

After saving this file, launch Minecraft and create a new Creative world. Before clicking Create, scroll down to Behavior Packs on the left menu, find 'My First Behavior Pack' under the Available tab, and activate it. Once the world loads, open your chat window and run the command `/give @s wiki:custom_gem`. You will receive your custom item.

{
  "format_version": "1.20.80",
  "minecraft:item": {
    "description": {
      "identifier": "wiki:custom_gem",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:max_stack_size": 64,
      "minecraft:icon": "emerald"
    }
  }
}

When you hold your new item in the game, you will notice its tooltip displays the raw string `item.wiki:custom_gem.name` instead of a clean title. This happens because raw identifiers are meant for the engine, while human-readable names belong in the Resource Pack's language files.

Assuming you have created a valid `manifest.json` inside your Resource Pack folder (`RP/manifest.json` with the `resources` module type), create a subfolder named `texts` inside the Resource Pack. Inside `RP/texts/`, create a file named `en_US.lang`. Language files are plain text files where each line maps a translation key to the text the player sees, separated by an equals sign with no spaces around it. Activate your Resource Pack on the world alongside your Behavior Pack, and the item will display its proper name.

item.wiki:custom_gem.name=Custom Gem

Applies to Minecraft Bedrock 1.20.80 and newer. None of the features on this page require experimental toggles.

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