Tutorials/Bedrock Edition creator guidelines

The guidelines provided here are best practices to have a better experience creating content for Minecraft. It will help ensure creations work and are performant and resilient to changes in the game.

General guidelines

 * Remove any files not related to the content from the world and pack directories.
 * Do not have packs within packs, or have Windows or PhotoShop files. Any of these can cause issues during ingestion, importing, or loading of content.
 * Remove any unused resources from the content before submission.
 * This will help keep content size to a minimum as well reduce the likelihood of content failing validation.
 * Additionally, there will not be unintended changes to your content if vanilla is modified.
 * Different platforms have different allowed path lengths. In addition to the pack or world’s path, the platform counts the directories where they are imported in Minecraft. If this goes past the limit, packs will fail on import and be left in invalid states. Because of this, it is recommended to:
 * Keep path lengths to 70 characters or less, i.e. the longest path to a file from the root of the pack or world template should be 70 characters long.
 * Each part of a path (directory or file name) must be under 60 characters. Otherwise, some platforms will not recognize the part.
 * The name of the directory for the resource or behavior packs should be under 10 characters long. This allows creators to have longer names for files and subdirectories. For example, bp_mw in the following path:
 * MyWorld/behavior_packs/bp_mw.

Definition files

 * Definition files such as blocks.json, mobs.json, sound_definitions.json, and others, include definitions for all elements in vanilla. Make sure packs only include changes to elements and fields that need to change. This means: do not copy/paste all vanilla definitions and then modifying only the pieces needed, but instead only include in the file the pieces that need to change. The game will merge the changes with vanilla.
 * If more than needed is included, and a vanilla change happens on a block or mob that was not intended to be modified, that piece may unnecessarily change content.
 * The following files should not be overwritten. They are not officially supported, as such there is no guarantee the changes will work or continue to work in the future.
 * credits/end.txt
 * font/emoticons.json
 * texts/language_names.json
 * items_client.json
 * items_offsets_client.json
 * Anything in the shaders directory

Functions

 * Use subdirectories to create namespaces to avoid conflicts between multiple behavior packs' functions files. If the path to a function (starting from the /functions/ subdirectory), matches exactly the path of a function on another pack, the top one on the pack stack will override others.
 * To lower the possibility of your functions not working on certain platforms, use lower cases and no spaces when naming your directories and function files, e.g. /functions/awesome_pack/level1_function.mcfuntion.
 * Use recursion with caution. While it is supported, it can cause performance issues if the recursion is too deep.
 * Enter the current version you are developing against as the "min_engine_version" on your behavior pack's manifest. E.g. "min_engine_version" : [1,8,0].
 * This allows you to control which version of the command to use for backwards compatibility.
 * If your command blocks only hold functions, modifying them becomes way easier. More importantly, if you publish an update to a behavior pack holding a function file, worlds using that pack will get the update once the new pack is applied.
 * This last bullet point is informational: Currently Bedrock doesn't support branching conditionals (e.g. execute (if), but this might be available in the future.

Commands

 * Try to avoid running commands every tick. Especially important is to not run dozens of commands every tick.
 * Try not to run more than 30 commands per tick.
 * If it is needed to run commands often, consider putting them on a clock, so they run every 5+ ticks instead.
 * Related to the above, if offset clocks can be set so commands run on different ticks, that can balance the work and get better performance.
 * An easy way to know if content has bad performance because of commands is turning off execution of all command blocks using the commandblocksenabled game rule.
 * Try not to use long running commands often (e.g. big or ). If possible, split this in more than one command that runs at different ticks.
 * Do not target items by their localized names, e.g.

Models

 * Models with a lot of tiny parts can perform badly in low end devices and with some GPUs. Find the right balance between detail and performance.

Sound

 * Stream only long-running sounds, e.g. background music.
 * Better performance in-game.
 * Some platforms have a limited number of files that can be opened at the same time, streaming all sounds will cause content to crash the game.
 * Short sounds (e.g. sound effects) perform best if loaded on memory.
 * Use simple techniques to keep your files small, e.g. remove any silent parts from the beginning and end of a sound.
 * There is a flag that can be used on sound definitions: load_on_low_memory. This flag is set to false by default, which means that, if the computer are low on memory, it won't load any sounds. If it is absolutely necessary for a certain sound to be loaded, set this flag to true. Be smart about its usage.

UI

 * All UI modifications are risky. If a vanilla screen is modified in any way, content using such screen may break. The UI system is built in a way that allows us to flexibly modify all screens through JSON files. Where issue arise is due to how these modifications are handled. Any changes to these UI JSON files (in a custom Resource Pack) are merged with vanilla. If these changes cannot merge properly the game can get into a bad state.
 * Re-skinning the UI, i.e. modifying textures used by it is the less risky change and can make for a nice polish element.
 * Re-sizing elements and moving them around is riskier but will be fine in most cases.
 * Doing big changes to the elements in a screen has a high risk of breaking.

UI modification examples
The following are examples on how to modify a UI definition file without having to make a full copy of the screen. They are based on the Enchanting Screen file (enchanting_screen_pocket.json).

Example 1: Limit variables
Do not include variables that are not being modified. E.g. if only "color" and "shadow" are being changed, don’t copy/paste the other variables into it. Simple targeted changes can be done where it is only necessary to just state the variables needing to be replaced.

Bad copy/paste:

"generic_label": { "type": "label", "color": "$pocket_title_text_color", "anchor_from": "center", "anchor_to": "center", "shadow": false },

Better:

"generic_label": { "color": "$pocket_title_text_color", "shadow": false },

Example 2: Inheritance
There is no need to restate what control a control is being modified in inheriting from. Just state the name of the one that is being modified. In the code below, "common.button" can be skipped:

Bad: "enchanting_confirm_button@common.button": {

Good: "enchanting_confirm_button": {

Example 3: Modifying children
Using the same button as an example, if it is only necessary to modify specific variables in some of the control's children, e.g. the default control. To modify only the children of a control use the syntax control_name/child_name. So instead of having this:

"enchanting_confirm_button@common.button": { "controls": [ {               "default@enchanting_pocket.confirm_default_control": { "type": "image", "texture": "textures/ui/button_borderless_light" //Added fancy button texture to default control }           }        ]    },

Change to:

"enchanting_confirm_button/default": { "texture": "textures/ui/button_borderless_light" //Added fancy button texture to default control },

Example 4: Modifying arrays
This example will show how to modify arrays in a control. For example: to add a new control as a child or to remove a binding from the control's bindings. For this, there is a special variable called "modifications". For each entry of the modifications array, it is possible to specify a specific array to modify, what operation to do, and the result.

Using "enchanting_book_panel" as an example, if it is necessary to add a control to its "controls" array, a modification entry can be made that specifies the "array_name": "controls", "operation": "insert_front", and the "value" is an array with the new control as if it was put in the control array. The following shows what is mentioned above, plus also modifying the offset of the panel.

"enchanting_book_panel": { "offset": [ -4, 1], "modifications": [ {           "array_name": "controls", "operation": "insert_front", "value": [ "panel_outline@beacon_pocket.panel_outline": { "layer": 0 } ]       }        ]    }

To remove the "#player_level_color" binding from the "player_level_label" child control, the following can be done:

"enchanting_book_panel/player_level_label": { "offset": [ 0, 10 ], "layer": 3, "color": "$experience_text_color" "modifications": [ {           "array_name": "bindings", "operation": "remove", "where": { "binding_name": "#player_level_color" }       }        ]    }

Mobs

 * Do not spawn dozens of entities at once. Depending on the device, performance can be bad if there are a lot of entities ticking at the same time.

Redstone

 * Whenever possible, do not let Redstone components that interact with each other cross chunk boundaries.
 * The game is able to handle most of these, however, there are instances when chunks loading can interact with Redstone component ticking, causing some components to lose their state and be broken until replaced.
 * Redstone components include any block that emits, transfers, or consumes Redstone signal, such as:
 * Buttons
 * Command Blocks
 * Comparators
 * Dispensers
 * Hoppers
 * Levers
 * Observers
 * Pistons
 * Rails: Activator, Detector and Powered
 * Redstone Wire
 * Repeaters
 * Among others

Ticking areas

 * Don't over use ticking areas.
 * This is important for devices with a low amount of memory.
 * If possible, unload ticking areas when done using them.
 * This will allow the device to reclaim some memory, as well as creating new ticking areas if needed.