# How to Install Behavior Packs & Addons on Your Bedrock Server (/docs/minecraft-bedrock/addon-setup)



import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Files, Folder, File } from 'fumadocs-ui/components/files';

Behavior packs (BPs) change gameplay mechanics — entity behaviors, loot tables, spawn rules, recipes, custom blocks, and items. On Bedrock Dedicated Server, installing them requires placing files in the right directories and activating them in your world.

How Addons Work on BDS [#how-addons-work-on-bds]

Unlike Java Edition's single plugin system, Bedrock uses a **pack system**:

* **Behavior Packs** — server-side gameplay changes (entities, loot, recipes, scripts)
* **Resource Packs** — client-side visual changes (textures, models, sounds). See [Add Resource Pack](/docs/minecraft-bedrock/add-resource-pack)
* **Addons** — a behavior pack and resource pack bundled together as a `.mcaddon` file

Every pack has a `manifest.json` with a unique UUID and version number. The server uses these to identify and load packs.

Server File Structure [#server-file-structure]

<Files>
  <Folder name="(server root)" defaultOpen>
    <Folder name="behavior_packs" defaultOpen>
      <Folder name="my_addon_BP">
        <File name="manifest.json" />

        <File name="pack_icon.png" />

        <Folder name="entities" />

        <Folder name="loot_tables" />

        <Folder name="spawn_rules" />

        <Folder name="recipes" />
      </Folder>
    </Folder>

    <Folder name="worlds" defaultOpen>
      <Folder name="Bedrock level" defaultOpen>
        <File name="world_behavior_packs.json" />

        <Folder name="db" />
      </Folder>
    </Folder>
  </Folder>
</Files>

Install a Behavior Pack [#install-a-behavior-pack]

<Steps>
  <Step>
    Download and extract the pack [#download-and-extract-the-pack]

    Download your behavior pack (`.mcpack`, `.mcaddon`, or `.zip` file).

    * `.mcpack` — rename to `.zip` and extract
    * `.mcaddon` — rename to `.zip` and extract. You'll find separate BP and RP folders inside
    * `.zip` — extract directly

    You should end up with a folder containing `manifest.json` at the root.
  </Step>

  <Step>
    Find the UUID and version [#find-the-uuid-and-version]

    Open `manifest.json` inside the pack folder. Note the `uuid` and `version` from the `header` section:

    ```json
    {
      "format_version": 2,
      "header": {
        "name": "My Behavior Pack",
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "version": [1, 0, 0]
      },
      "modules": [
        {
          "type": "data",
          "uuid": "different-uuid-here",
          "version": [1, 0, 0]
        }
      ]
    }
    ```

    The `modules.type` should be `"data"` for a behavior pack (or `"script"` for Script API packs).
  </Step>

  <Step>
    Upload to the server [#upload-to-the-server]

    In the [XGamingServer Panel](https://panel.xgamingserver.com), click **Files** in the sidebar. Navigate to the `behavior_packs/` directory in the server root and upload the extracted pack folder.

    {/* Screenshot needed: File Manager showing behavior_packs/ directory */}
  </Step>

  <Step>
    Activate the pack in your world [#activate-the-pack-in-your-world]

    Navigate to `worlds/<your-world-name>/` and open `world_behavior_packs.json`. Add your pack's UUID and version:

    ```json
    [
      {
        "pack_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "version": [1, 0, 0]
      }
    ]
    ```

    If the file doesn't exist, create it. If it already has entries, add yours to the array.

    > The `pack_id` is the **header UUID** from manifest.json, not the module UUID.
  </Step>

  <Step>
    Restart the server [#restart-the-server]

    Restart from **Console**. Check the console output for pack loading messages or errors.
  </Step>
</Steps>

Script API Packs [#script-api-packs]

Some addons use the Bedrock **Script API** (JavaScript/TypeScript). These require additional setup:

1. The `manifest.json` will have `"type": "script"` in modules and list `@minecraft/server` as a dependency
2. Enable `content-log-file-enabled=true` in `server.properties` for script error logging
3. If using beta APIs, you must enable the **Beta APIs** experiment. See [Enable Experimental](/docs/minecraft-bedrock/enable-experimental)
4. Script watchdog settings in `server.properties` control memory limits and hang detection

If the Pack Has a Resource Pack [#if-the-pack-has-a-resource-pack]

If the addon came with both a BP and RP:

1. Upload the RP to `resource_packs/` in the server root
2. Add its UUID to `worlds/<world>/world_resource_packs.json`
3. Set `texturepack-required=true` in `server.properties` to force clients to download it

See [Add Resource Pack](/docs/minecraft-bedrock/add-resource-pack) for the full process.

Troubleshooting [#troubleshooting]

| Problem                     | Fix                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| Pack not loading            | Verify the UUID in `world_behavior_packs.json` matches the header UUID in `manifest.json` exactly |
| "Unknown pack" error        | The pack folder must be inside `behavior_packs/`, not nested in a subfolder                       |
| Script errors on startup    | Enable `content-log-file-enabled=true` and check the content log in the server root               |
| Pack requires newer version | Update your BDS to the version listed in `min_engine_version` in the pack's manifest              |
| Multiple packs conflicting  | Pack order in `world_behavior_packs.json` matters — last pack wins for overlapping content        |

Related Guides [#related-guides]

* [Add Resource Packs](/docs/minecraft-bedrock/add-resource-pack)
* [Enable Experimental Gameplay](/docs/minecraft-bedrock/enable-experimental)
* [Server Properties Reference](/docs/minecraft-bedrock/server-properties)