Understanding manifest.json in Bedrock Add-ons

The manifest file sits at the very top level of your pack folder (for example, directly inside your behavior pack directory, not inside a subfolder). It is divided into three main parts: the format version, the header, and the modules array. You can also include optional sections like dependencies, capabilities, and metadata.

Format version 2 is the current standard for all modern Bedrock packs. The header holds the pack's display information and its main identifier, while the modules section defines what kind of content the pack actually contains. Every UUID in this file must be a valid, randomly generated Version 4 UUID, and no two UUIDs in the same file or across different packs can be identical.

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "a1b2c3d4-e5f6-4789-8012-3456789abcde",
      "version": [1, 0, 0]
    }
  ]
}

The header identifies your pack to the game engine and to the player. While you can write plain text directly into the name and description fields, best practice is to use localization keys like pack.name and pack.description, then define the actual text inside your pack's texts/en_US.lang file.

The min_engine_version field is particularly important inside behavior packs. It tells Minecraft which base game behavior rules to apply to your pack. If you omit it or set it too low, newer block or entity features might fall back to legacy behavior for backward compatibility. Always set this to the current version of Minecraft you are developing on.

The modules array tells Minecraft how to treat the files inside your pack. Almost every pack has just one module, except for behavior packs that combine standard JSON data with custom JavaScript.

Notice that each module has its own uuid field. A very common mistake is copying the header's UUID into the module's UUID. They must be two completely different generated UUIDs. The module version usually matches the header version, though they are tracked separately by the game.

An add-on usually consists of one behavior pack and one resource pack working together. By adding a dependencies array to your behavior pack's manifest, you can force Minecraft to automatically activate the matching resource pack whenever a player activates the behavior pack on a world.

To link them, take the header UUID and header version from your resource pack, and place them inside the dependencies array of your behavior pack. You can also put the behavior pack's UUID inside the resource pack's dependencies to link them both ways.

{
  "format_version": 2,
  "header": {
    "name": "My Add-on Resources",
    "description": "Textures and models for My Add-on",
    "uuid": "11111111-2222-4333-8444-555555555555",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "resources",
      "uuid": "66666666-7777-4888-9999-000000000000",
      "version": [1, 0, 0]
    }
  ],
  "dependencies": [
    {
      "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "version": [1, 0, 0]
    }
  ]
}

If your behavior pack uses the Script API, you must add a script module to the modules array and declare which native script libraries your code imports in the dependencies array.

The script module requires a language field set to javascript and an entry field pointing to your main script file inside the BP/scripts/ folder. Unlike pack dependencies, script library dependencies use a module_name string instead of a uuid. Their version field must be a string rather than an array of numbers.

{
  "format_version": 2,
  "header": {
    "name": "Scripted Behavior Pack",
    "description": "Runs custom JavaScript via the Script API",
    "uuid": "c9a646d3-9c61-4cb7-bfcd-ee2522c8f633",
    "version": [1, 0, 0],
    "min_engine_version": [1, 21, 0]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "382b6e35-6b37-4906-9a3f-9d1d1249a3f2",
      "version": [1, 0, 0]
    },
    {
      "type": "script",
      "language": "javascript",
      "uuid": "74c8c9e0-2a4f-41f8-8c4f-23456789abcd",
      "version": [1, 0, 0],
      "entry": "scripts/main.js"
    }
  ],
  "dependencies": [
    {
      "module_name": "@minecraft/server",
      "version": "1.11.0"
    }
  ]
}

Applies to all modern Bedrock versions (format_version 2 has been standard since 1.13.0). No experimental toggles are needed for the manifest itself, unless you declare a dependency on a '-beta' Script API module version, which requires the Beta APIs toggle on the world.

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