Writing a Custom Bedrock Add-on Manifest, Explained

Understanding the Bedrock Add-on Manifest

The manifest.json file is the cornerstone of any custom add-on for Minecraft Bedrock Edition. It acts as the identity card for your creation, providing Minecraft with all the essential information it needs to recognize, load, and correctly implement your custom content. Written in JSON (JavaScript Object Notation) format, this file is crucial for both resource packs (which modify appearances, sounds, and UI) and behavior packs (which alter gameplay mechanics, entities, and items).

Core Components of the Manifest

Every manifest.json file is structured around three primary sections: format_version, header, and modules. An optional dependencies field can also be included for linking packs.

• format_version

  This field specifies the version of the manifest syntax your add-on adheres to. It’s vital for Minecraft to correctly interpret the structure of your manifest.json. For most resource and behavior packs, version 2 is commonly used and stable. Version 3 is a newer preview version, often associated with experimental features or newer API functionalities. It’s generally recommended to use the highest stable version available.

• header

  The header section contains the overarching details of your add-on. It’s like the title and introductory information for your pack:

  • name: A user-friendly name for your add-on that will appear in Minecraft’s UI.
  • description: A brief explanation of what your add-on does, also displayed in-game.
  • uuid: A Universally Unique Identifier. This is a critical, unique string of characters that Minecraft uses to identify your specific pack. It is absolutely essential that this UUID is unique to your pack’s header and never reused across different packs or even within the same pack for different purposes (like module UUIDs).
  • version: Defines the version of your add-on itself (e.g., “1.0.0”). This helps users track updates and progress.
  • min_engine_version: This field specifies the minimum version of the Minecraft Bedrock client required for your add-on to function correctly. If a user tries to enable your add-on on an older version of Minecraft than specified here, the add-on will not load. It’s good practice to set this to the version you are currently developing on or the earliest version you’ve tested for compatibility.
• modules

  The modules section defines the specific content types within your add-on. An add-on can have multiple modules, though typically a simple pack will have one. Each module requires its own identification:

  • type: This indicates what kind of content the module contains. For resource packs, the type is “resources”. For behavior packs, the type is “data”.
  • uuid: Just like the header, each module requires its own new and unique UUID. This ensures Minecraft can distinguish between different components or types of content within your add-on.
  • version: Specifies the version of this particular module’s content. This can be the same as the header version or different if you’re tracking module-specific updates.
• uuid (Universally Unique Identifier)

  UUIDs are fundamental for Minecraft to uniquely identify your add-ons and their components. They are 32-character hexadecimal strings, often displayed in a “8-4-4-4-12” format (e.g., xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx). The most important rule regarding UUIDs is to never use the same UUID twice for different packs, or for the header and a module within the same pack. Each manifest.json will typically contain at least two distinct UUIDs: one for the pack’s header and one for each module defined within it.

• min_engine_version

  This setting acts as a compatibility gate. It tells Minecraft the absolute minimum client version (e.g., [1, 16, 0]) that your add-on was designed for. If a player tries to use your add-on with an older Minecraft version, it will be disabled or not appear, preventing potential crashes or unexpected behavior due to unsupported features.

• dependencies (Optional)

  If your behavior pack relies on a specific resource pack to function correctly (e.g., custom textures for custom entities defined in the behavior pack), you can link them using the dependencies field within the behavior pack’s manifest.json. This section will reference the header UUID and version of the resource pack it depends on. This ensures that when the behavior pack is enabled, Minecraft prompts the user to also enable its linked resource pack.

Step-by-Step Process: Creating Your Manifest

Follow these steps to set up your add-on’s manifest files:

1. Set up your workspace:

   Navigate to your Minecraft development folders. Create a dedicated folder for your behavior pack (BP) inside development_behavior_packs and another for your resource pack (RP) inside development_resource_packs. These development folders are crucial because they allow Minecraft to automatically detect and reload your packs without needing to restart the game, simply by exiting and re-entering a world.

2. Create manifest.json:

   Inside both your behavior pack folder and your resource pack folder, create a new file named manifest.json. This filename is case-sensitive and must be all lowercase.

3. Populate manifest.json:

   Open each manifest.json file and fill it with the required JSON structure:

   • Define the format_version. Use 2 for stable packs, or 3 if you are targeting newer features or preview APIs.
   • Within the header section, provide a clear name and description. Generate a new, unique UUID for this header. Set the pack’s version (e.g., [1, 0, 0]) and specify the min_engine_version (e.g., [1, 19, 0]).
   • Inside the modules section, define the type: “resources” for your resource pack’s manifest, and “data” for your behavior pack’s manifest. Generate another new and unique UUID specifically for this module. Set its version, which can often be the same as the header version.
   • (Optional for Behavior Packs) If your behavior pack depends on a resource pack, include a dependencies section in its manifest.json. This section will list the header UUID and version of the resource pack it relies on.
4. Add pack_icon.png:

   Place a square image file named pack_icon.png (e.g., 128×128 pixels) directly into both your behavior pack folder and your resource pack folder. This icon will represent your add-on in Minecraft’s pack selection menus.

5. Test your add-on:

   Launch Minecraft, create a new world, or edit an existing one. Go to the “Resource Packs” and “Behavior Packs” sections and enable your newly created add-ons. If your add-on utilizes features that require experimental gameplay, ensure “Experimental Gameplay” toggles are turned on in the world settings.

Important Tips for Manifest Creation

• Generate UUIDs Carefully: Always use a reliable UUID generator. Online tools like uuidgenerator.net are excellent, as are built-in tools in development environments like VSCode extensions or the `bridge.` tool. Never manually type or guess UUIDs.
• Choose the Correct format_version: Stick to the highest stable version (currently 2) unless you specifically need features from a preview version (like 3). Using an outdated version can lead to warnings or pack loading failures.
• Set min_engine_version Realistically: Set this to the Minecraft version you are actively developing on. This prevents users with older game versions from encountering issues, but also avoids unnecessarily restricting users on slightly older, compatible versions.
• Leverage Development Folders: Working within development_resource_packs and development_behavior_packs is crucial for an efficient workflow. It allows for quick iteration and testing, as changes are loaded simply by re-entering a world without a full game restart.
• Validate JSON Syntax: JSON is strict. Ensure all curly braces {}, square brackets [], commas ,, and quotation marks "" are correctly placed. A single misplaced character can lead to parsing errors. Tools like Visual Studio Code offer excellent JSON validation and formatting.
• Don’t Forget the Pack Icon: A pack_icon.png is not just for aesthetics; it’s essential for your pack to display correctly and be easily identifiable in the in-game menus.
• Use Recommended Tools: Visual Studio Code is highly recommended for its excellent JSON support, extensions for Minecraft add-on development, and general code editing features. Online manifest generators can also be helpful for quickly setting up the basic structure.

Common Mistakes to Avoid

• Duplicate UUIDs: This is a frequent cause of add-on issues. Using the same UUID for your pack’s header and a module, or for two entirely different packs, will confuse Minecraft and lead to errors or packs not loading.
• Incorrect format_version: Using a version that is too old, too new (for a non-preview feature), or simply incorrect will prevent your add-on from loading or generate warnings.
• Incompatible min_engine_version: Setting this value higher than a user’s Minecraft version means your add-on won’t be available to them. Setting it too low might cause your add-on to load on incompatible versions, leading to bugs.
• Incorrect File Naming: The manifest file *must* be named manifest.json, all lowercase, and with correct spelling. Any deviation will make it invisible to Minecraft.
• Missing manifest.json: An add-on folder without this file will not be recognized as an add-on by Minecraft.
• Invalid File Extensions for Distribution: When sharing your add-ons, ensure they have the correct `.mcaddon`, `.mcpack`, or `.mcworld` extensions. If you receive a `.zip` file, remember to unzip it first before attempting to change its extension to `.mcpack`.
• “Unable to parse pack manifest” Errors: This error message almost always indicates a JSON syntax issue. Double-check for missing commas, unclosed brackets, or incorrect quotation marks.
• Mixing Too Many Add-ons: While not a manifest error itself, enabling many complex add-ons simultaneously can lead to conflicts, glitches, or crashes. Test your add-on in isolation first.