Making an add-on that works on both phone and console

Phones and PCs allow players to import `.mcaddon` and `.mcpack` files directly from the operating system. Consoles do not give players a file browser. Aside from content published to the official Marketplace, the only reliable way a console player will ever run your custom add-on is by joining a Realm, a dedicated server, or a LAN world hosted on a phone or PC that has the pack applied.

To make sure consoles download your resources automatically when joining a hosted world, link your Behavior Pack and Resource Pack in their `manifest.json` files using the `dependencies` array. When the host world enforces pack downloads, the console client pulls the linked Resource Pack cleanly without the player needing to install anything locally.

Console operating systems also run inside strict security sandboxes that reject non-standard file names. While Windows ignores letter casing and Android tolerates deep folders, consoles will fail to mount packs if file paths are too long, contain spaces, or mix uppercase and lowercase letters unpredictably. Stick strictly to lowercase ASCII characters, numbers, and underscores for every folder and file name in both packs.

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "b2c3d4e5-f6a7-4b6c-9d0e-1f2a3b4c5d6e",
      "version": [1, 0, 0]
    }
  ],
  "dependencies": [
    {
      "uuid": "c3d4e5f6-a7b8-4c7d-8e1f-2a3b4c5d6e7f",
      "version": [1, 0, 0]
    }
  ]
}

Budget Android phones, older iPads, and the Nintendo Switch share a tight constraint: limited RAM and video memory (VRAM). A pack filled with 512x512 item icons or 2048x2048 entity sheets will load fine on a desktop PC or Xbox Series X, but on a Switch or a 3GB RAM phone it will either render as magenta-and-black checkerboards or force the operating system to close Minecraft entirely.

Keep block and item textures at 16x16 or 32x32 unless a higher resolution is essential. For entities, avoid single giant texture sheets; break complex models down or use lower-resolution textures that match vanilla pixel density. When saving PNG files, export them as 8-bit paletted images if they do not need smooth alpha gradients, and strip out image metadata created by editing software.

Audio files are the second biggest cause of mobile memory spikes. Short sound effects like footsteps or custom item clicks should be loaded into memory, while long ambient tracks or custom music discs must be streamed from storage. In `RP/sounds/sound_definitions.json`, set `stream` to `true` on any `.ogg` file longer than a few seconds so phones do not decode the entire audio track into RAM at once.

{
  "format_version": "1.14.0",
  "sound_definitions": {
    "custom.music.boss_theme": {
      "category": "music",
      "sounds": [
        {
          "name": "sounds/music/boss_theme",
          "stream": true,
          "volume": 0.8
        }
      ]
    },
    "custom.item.wrench_use": {
      "category": "player",
      "sounds": [
        {
          "name": "sounds/items/wrench_click",
          "stream": false
        }
      ]
    }
  }
}

Never assume the player has a mouse cursor or a full keyboard. A mechanic that requires holding sneak while double-jumping and pressing the interact key might feel natural on PC, but it is nearly impossible for a phone player using thumbs on a glass screen, and awkward on a console controller.

Stick to standard interaction triggers that Bedrock maps natively across all devices. Using an item (`itemUse` in scripts, or standard interact components in JSON), punching a block, and sneaking while interacting all have dedicated on-screen buttons on touch devices and standard binds on controllers.

If you build custom interfaces with the `@minecraft/server-ui` module (`ActionFormData`, `ModalFormData`, or `MessageFormData`), test how they read on a small screen and how they navigate with a D-pad. Console players have to move a selection highlight step-by-step down every button in an `ActionFormData` menu; a list of fifty buttons is tedious with a controller, whereas nested categories of six to eight buttons work comfortably on both touchscreens and gamepads.

When a player runs your add-on locally on a phone, that phone's CPU has to run both the client rendering and the internal server tick, including your `@minecraft/server` JavaScript code. Mobile processors throttle quickly when they heat up, so scripts that take 2 milliseconds on a desktop CPU can easily blow past the 50-millisecond tick budget on a warm phone, causing delayed block breaking and sluggish mob movement.

Avoid running heavy world queries—such as `dimension.getEntities()` or scanning large volumes of blocks—inside a `system.runInterval` loop that fires every single tick. Instead, stagger background checks to run every 10 or 20 ticks, filter entity queries tightly using `EntityQueryOptions` (`type`, `maxDistance`, `location`), or spread heavy work across multiple ticks using `system.runJob`.

Keep strictly to stable `@minecraft/server` and `@minecraft/server-ui` versions. Modules that only exist on PC dedicated servers, such as `@minecraft/server-net` or `@minecraft/server-admin`, will cause the manifest to fail validation immediately on phones and consoles.

import { world, system } from "@minecraft/server";

// Run once every 20 ticks (1 second) instead of every tick to save mobile CPU
system.runInterval(() => {
  for (const player of world.getAllPlayers()) {
    const nearbyMobs = player.dimension.getEntities({
      location: player.location,
      maxDistance: 16,
      families: ["monster"]
    });

    if (nearbyMobs.length > 5) {
      player.onScreenDisplay.setActionBar("Danger nearby!");
    }
  }
}, 20);

Applies to all modern Bedrock versions (1.20.0+). No experimental toggles are required; avoiding experimental toggles is strongly recommended when targeting consoles and Realms, as experimental features frequently fail to sync or crash non-PC clients.

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