Bedrock add-ons look like magic from the outside. You tap a file, the game imports it, and suddenly there is a new creature wandering your world. Underneath, though, there is a tidy and fairly logical structure. Once you understand it, installing, fixing and even writing add-ons gets far less mysterious. This article takes you through how Bedrock add-ons are organised, what each part does and why things break when they do.
The big picture
A Bedrock add-on is a folder (or a zipped bundle) of files that the game reads at load time. The game already contains the engine: it knows how to spawn entities, apply damage, render models and play sounds. An add-on supplies data that points those systems in a new direction.
Two kinds of packs carry that data:
- Resource packs describe appearance and sound.
- Behavior packs describe rules and logic.
Everything else, such as skin packs, world templates and texture packs, is a variation on these ideas.
Inside a resource pack
A resource pack folder commonly includes:
manifest.json, the identity card of the pack.pack_icon.png, the small image shown in the menu.textures/, containing block, item and entity images.models/, with geometry files for custom shapes.animations/andanimation_controllers/, which describe movement and state changes.sounds/andsounds.json, for audio.entity/, client-side definitions that link a mob to its model, texture and animations.texts/, for language strings such as item names.
When you retexture a sword, you only need to replace an image and keep the file name that the game expects. When you add a new creature, you must wire together a model, a texture, an animation and a client entity file.
Inside a behavior pack
A behavior pack folder commonly includes:
manifest.json, again as the identity card.entities/, where mob behavior, components and events are defined.items/andblocks/, for custom items and blocks.loot_tables/, deciding what drops from mobs or chests.recipes/, for crafting, smelting and similar recipes.spawn_rules/, controlling where and when mobs appear.trading/, for villager-style trade tables.scripts/, which may hold JavaScript used by the scripting API.functions/, command lists the game can run.
These are mostly JSON files, readable by humans. Editing a number in an entity file, such as health, is an approachable first experiment.
The manifest: the file that decides everything
If you take only one thing from this article, take this: the manifest is the most common reason an add-on fails.
A manifest.json contains:
- A
format_version, which tells the game how to interpret the file. - A
headerwith the pack name, description, a UUID and a version number. - One or more
modules, each with its own UUID and a type such asresources,dataorscript. - Optionally,
dependencies, which list other packs this one needs.
UUIDs
A UUID is a long string that uniquely identifies a pack. The game uses it to tell packs apart. Two different packs with the same UUID will confuse the game, and a pack whose dependency points to a UUID that does not exist will refuse to activate. This is why copying a pack and renaming the folder without changing UUIDs often causes strange behavior.
Version numbers
The version is an array of three numbers. Increasing it tells the game that a pack was updated. The game also has a “minimum engine version” field that signals which game version the pack was designed for. If that number is higher than the player’s game version, the pack may be flagged as incompatible.
Dependencies
When a behavior pack needs a particular resource pack, the dependency entry links them by UUID and version. This is how a creature’s behavior stays tied to its model. Break the link and you may get invisible mobs or mobs that spawn with default models.
How packs are combined in a world
A world can have multiple packs active at once. Each one has a position in a list, and order matters. If two packs define the same entity, the pack higher in priority wins. Practical advice:
- Keep the number of active packs modest.
- Put large texture packs lower than gameplay packs if both touch the same items.
- When you suspect a conflict, turn packs off one by one.
Activating a pack on a world is not the same as importing it. Import puts the files in the game’s storage; activation tells a specific world to use them. Beginners often import and forget to activate.
What scripting adds
Newer Bedrock versions include a scripting API that lets add-ons run JavaScript in response to game events, such as a player using an item. This allows more dynamic behavior: custom commands, UI messages and more elaborate game modes. Scripting is more powerful and also more demanding. It often needs experimental options or specific engine versions, and it can break more often across updates than plain JSON data.
Add-on, texture pack, skin pack: how they differ
- Add-on: typically a behavior pack, a resource pack, or both, aiming to change gameplay and visuals.
- Texture pack: a resource pack focused on look and feel only.
- Skin pack: collections of player skins, handled separately from the others.
- World template: a world with predefined settings and sometimes packs bundled.
If you only want a visual refresh, you do not need a behavior pack at all, which lowers the risk of conflicts.
Where the files live on your device
On a phone, imported packs are stored in the game’s own directory. The location differs by platform and operating system version, and recent versions of mobile operating systems limit direct access to app folders. We will not give exact paths here because they change, and incorrect advice could lead you to delete the wrong thing. If you need to manage packs, use the in-game storage menu where available.
A worked example: how one custom mob comes together
Imagine an add-on that introduces a friendly fox-like creature. The resource pack contains a geometry file describing the body shape, a texture image painted over that shape, an animation file for walking and idling, and a client entity file that links all three together under an identifier. The behavior pack contains a server-side entity file using the same identifier, with components for health, movement, how it follows the player and what it eats, plus a spawn rule that places it in certain biomes. Finally, both manifests point to each other through dependencies.
If any one link is wrong, you see a specific symptom. A wrong identifier gives you a default pig or no mob at all. A missing texture path shows the purple-and-black checkerboard. A missing animation leaves the mob frozen in a T-pose. Learning these symptoms turns a confusing failure into a short checklist.
Notice also how much of the work is naming consistency. Identifiers use a namespace and a name, such as yourname:fox, and that namespace should be unique to you so it never collides with another creator’s content or the game’s own.
Creating your own add-on: a gentle starting point
You do not need to be a programmer to try. A reasonable first project:
- Create a new folder with a name you will recognise.
- Add a manifest.json with fresh UUIDs from a generator you trust.
- Add a small icon so it appears correctly in the menu.
- Copy one entity file from an official sample and change a single value, such as health.
- Zip the folder and rename the extension to.mcpack.
- Import it and test in a throwaway world.
Official sample packs from the game’s publisher are the best learning material because they match the current format. Make one change at a time so you can tell what caused what.
How to Use Behavior Packs to Change Mob Settings
Why add-ons break after updates
Add-ons rely on formats that the game can revise. Typical updates cause:
- Renamed components or deprecated fields, so a mob no longer behaves as designed.
- New validation rules, so a once-tolerated typo now stops the pack loading.
- Changes in engine version requirements.
Creators who maintain their work will refresh it. Users can help by reporting which game version they run, and by keeping a stable copy of a world before updating the game. For a practical troubleshooting walkthrough, see our guide on add-ons that refuse to load.
How to Fix Add-Ons That Won’t Load in Minecraft PE
Content logs: your best debugging friend
Bedrock can display content log messages that explain exactly why a pack failed. In the settings under the creator or storage section there is an option to show content log errors (names vary by version). Turning it on after an import problem gives you messages like missing keys, invalid values or unknown dependencies. Reading these messages is far faster than guessing.
Safety notes for add-on users
Because add-ons are mostly data, they are less risky than programs. But risk is not zero:
- Scripts can display messages or run commands that you did not expect.
- Fake add-on files may be disguised installers for other apps.
- Packs that ask you to leave the game and install a second app are not legitimate add-ons.
Stick with trustworthy sources and read our checklist on spotting unsafe files before installing.
How to Spot Unsafe Mod Files Before Installing
Frequently Asked Questions
Can a behavior pack work without a resource pack?
Yes, if it only changes rules, such as drops or health. Anything that introduces new visuals needs a resource pack as well.
What does.mcaddon contain?
It is a zip-based bundle that can hold several packs. Opening it with Minecraft imports all of them.
Why do my mobs appear invisible?
Often the resource pack with the model or client entity file is missing or inactive, or the dependency link is wrong.
Do I need to know how to code?
Not for installing. For modifying data files, basic JSON is enough. Scripting needs JavaScript.
Conclusion
Bedrock add-ons are structured bundles of data. Resource packs control how things look and sound, behavior packs control what things do, and the manifest ties everything together with UUIDs and versions. When you understand those three ideas, most problems become diagnosable rather than mysterious. Use content logs, change one thing at a time, keep backups and take advantage of official samples to learn the current format.