Packing Behaviour and Resource Packs into an .mcaddon

Minecraft Bedrock Edition uses renamed ZIP archives to handle one-click installations across Windows, mobile devices, and consoles. While developing your add-on, you work with loose folders inside `development_behavior_packs` and `development_resource_packs`. When you are ready to share your work with testers or release it to the public, you package those folders into a single distributable archive so players do not have to manually copy files into their game directories.

Understanding which extension to use depends on what you are shipping. An `.mcaddon` file is specifically designed to hold multiple packs at the root level, whereas an `.mcpack` is meant for a single pack.

The most important difference between an `.mcpack` and an `.mcaddon` is where the `manifest.json` files sit relative to the root of the ZIP archive. In a single `.mcpack`, the `manifest.json` file must be at the very top level of the archive. In an `.mcaddon`, the top level of the archive must contain separate folders (or separate `.mcpack` archives) for each pack, and each of those subfolders contains its own `manifest.json`.

There are two valid ways to structure the inside of your `.mcaddon` archive. The cleanest and most common method is to place your behaviour pack folder and resource pack folder side-by-side at the root of the ZIP. For example, the root of your archive would contain two folders named `MyAddon_BP` and `MyAddon_RP`. Inside `MyAddon_BP`, you place the behaviour pack's `manifest.json`, `pack_icon.png`, `entities/`, and `items/`. Inside `MyAddon_RP`, you place the resource pack's `manifest.json`, `pack_icon.png`, `textures/`, and `models/`.

The second method is to package your behaviour pack into `MyAddon_BP.mcpack` and your resource pack into `MyAddon_RP.mcpack`, and then zip those two `.mcpack` files together into `MyAddon.mcaddon`. Both methods import identically in Minecraft, though the plain folder method is easier to inspect and edit without having to unzip nested archives.

Packing a behaviour pack and a resource pack into the same `.mcaddon` file only ensures they get installed at the same time; it does not automatically activate them together on a world. If a player applies your behaviour pack to their world but forgets to activate the resource pack, custom entities and blocks will appear as missing textures or invisible hitboxes. To prevent this, you should link the two packs using the `dependencies` array in their `manifest.json` files.

When a behaviour pack declares a dependency on a resource pack's header UUID, activating the behaviour pack in a world's settings automatically forces the matching resource pack to activate as well. Below is a complete behaviour pack manifest that links to its companion resource pack. Notice that the `uuid` inside the `dependencies` block must be the exact `header.uuid` from the resource pack's manifest, not its module UUID.

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "84821530-450b-4c5f-9464-000000000001",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "84821530-450b-4c5f-9464-000000000002",
      "version": [1, 0, 0]
    }
  ],
  "dependencies": [
    {
      "uuid": "84821530-450b-4c5f-9464-000000000003",
      "version": [1, 0, 0]
    }
  ]
}

For the dependency link to work, the resource pack must use the exact UUID referenced by the behaviour pack's `dependencies` array in its own `header` section. Every UUID across both files must be unique—you need four distinct UUIDs in total for a basic two-pack add-on (BP header, BP module, RP header, RP module). You can also add a dependency block in the resource pack pointing back to the behaviour pack's header UUID, though putting the dependency in the behaviour pack is the most critical step.

Keep the `version` numbers synchronized between the resource pack's `header` and the behaviour pack's `dependencies` entry. If you bump your resource pack version to `[1, 0, 1]` later, remember to update the dependency version in the behaviour pack as well.

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "84821530-450b-4c5f-9464-000000000003",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "resources",
      "uuid": "84821530-450b-4c5f-9464-000000000004",
      "version": [1, 0, 0]
    }
  ]
}

Before you create the archive, clean up any workspace clutter from your development folders. Remove git directories (`.git`), project configuration files, Photoshop or Blockbench source files (`.psd`, `.bbmodel`), and operating system metadata like `.DS_Store` or `Thumbs.db`. Leaving source files inside the pack bloats the download size and slows down importing on mobile devices.

To build the `.mcaddon` file manually on Windows or macOS, copy your clean behaviour pack folder and resource pack folder into a temporary empty working directory. Select both folders at the same time—do not select the parent working directory itself—and compress them into a standard `.zip` archive using your operating system's built-in compression tool or a utility like 7-Zip. Note that you must use the standard ZIP format; renaming a `.rar` or `.7z` archive to `.mcaddon` will fail to import because Minecraft can only decompress standard ZIP streams.

Once you have your `.zip` file, open its properties or rename it directly in your file explorer, changing the `.zip` extension to `.mcaddon`. On Windows, make sure you have 'File name extensions' checked in the File Explorer View tab; otherwise, renaming `my_pack.zip` to `my_pack.mcaddon` will actually name the file `my_pack.mcaddon.zip`, and double-clicking it will just open your archive manager instead of launching Minecraft.

Always test your finished `.mcaddon` file before distributing it. Move your original folders out of `development_behavior_packs` and `development_resource_packs` temporarily so they do not conflict with the test import. Double-click the `.mcaddon` file to launch Minecraft. You should see the 'Import started...' toast banner at the top of the screen, followed by two separate 'Successfully imported' messages—one for the behaviour pack and one for the resource pack.

When you release an update to your add-on and distribute a new `.mcaddon` file, you must keep the `header.uuid` and `modules.uuid` values identical to the previous release, and increment the `version` array (for example, from `[1, 0, 0]` to `[1, 1, 0]`) in both the headers, the modules, and the dependency declarations.

If you leave the version number at `[1, 0, 0]` when a player tries to import the updated `.mcaddon`, Minecraft will refuse to overwrite the existing installation and will display a duplicate pack error. Conversely, if you generate brand new UUIDs for an update, Minecraft will treat the update as an entirely separate add-on, leaving the old version installed alongside the new one and potentially breaking entities or blocks in worlds that were already using the original UUIDs.

Applies to all modern Bedrock Edition versions (format_version 2 manifests have been standard since 1.13.0). No experimental toggles are required for packaging, importing, or linking packs via dependencies.

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