Minecraft Wiki
Advertisement
Minecraft Wiki
Information icon.svg
This tutorial is exclusive to Bedrock Edition. 
Clock JE3 BE3.gif
This article needs to be updated. 
Please update this page to reflect recent updates or newly available information.
This article needs cleanup to comply with the style guide. [discuss]
Please help improve this page. The talk page may contain suggestions.
Gear (item).gif
This article is a work in progress. 
Please help in the expansion or creation of this article by expanding or improving it. The talk page may contain suggestions.

This tutorial shows how to create a behavior pack.

Getting Started

Behavior packs can be used to add or modify functions, loot tables, villager trades, recipes, items, blocks, mobs and mob's behavior.

Time required

This tutorial should take around 1 to 1.5 hours to complete.

Required tools

You will need the following programs to follow along with this tutorial:

Text editor

Any text editor should work, but it is suggested to use some sort of programming IDE. Notepad++ is an excellent and free, text editor with syntax highlighting for lots of programming languages. You can download Notepad++ from here: https://notepad-plus-plus.org/. If you want to manage multiple files effectively, it is suggested to use Visual Studio Code.

Creating a Behavior Pack

To begin, you can find the unmodified game files on Minecraft's official site.

To find the files, navigate to the bottom of the page, where you will find a paragraph where you can dowload a zip for the unmodified base files. You must then take the downloaded zip file and navigate to the com.mojang folder and place the zip file in the development_behavior_packs folder, and unzip it.

This step is not strictly necessary, and you can create a behavior pack without it, but it makes it much easier.

to start without the downloaded files, you can follow these steps.

  • Again, navigate to the development_behavior_packs folder and create there a new folder named "tutorial_behavior_pack":
    • (%userprofile%\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs\tutorial_behavior_pack)
  • Within that new folder create a JSON file called "manifest.json"

manifest.json

This manifest file already exists in the dowloaded files.

In this manifest file you will want the following:

manifest.json
 1 {
 2     "format_version": 2,
 3     "header": {
 4         "description": "Example vanilla behavior pack",
 5         "name": "Vanilla Behavior Pack",
 6         "uuid": "ee649bcf-256c-4013-9068-6a802b89d756",
 7         "version": [ 0, 0, 1 ],
 8         "min_engine_version": [ 1, 16, 220 ]
 9     },
10     "modules": [
11         {
12             "description": "Example vanilla behavior pack",
13             "type": "data",
14             "uuid": "fa6e90c8-c925-460f-8155-c8a60b753caa",
15             "version": [0, 0, 1]
16         }
17     ],
18     "dependencies": [
19         {
20             "uuid": "66c6e9a8-3093-462a-9c36-dbb052165822",
21             "version": [0, 0, 1]
22         }
23     ]
24 }

The "uuid" is a universal unique identifier, which is necessary to change to your own uuid, even in the downloaded files.

the "version" tells the game what version of the pack is being used, if the number is higher, it will use that pack instead of the old one. this is important for testing your pack.

Testing your behavior pack

The behavior pack is now game ready. to test it, open minecraft, go to a world on which you want to test it. go to the world settings, navigate to the addons menu, and find it under my packs. it will now work on your worlds. this is where the "version" line in the manifest.json file becomes important. anytime you modify anything in the development pack, the world will continue to run the old version unless the pack version is higher.


Functions

Functions are lists of commands that can be run in order.

To add functions, you must make a folder named functions inside the main folder. Then create a file with a .mcfunction extension within this folder or a subfolder. Such as example_file.mcfunction in a subfolder called example_folder. in game these functions woud be run using the /function command and be syntaxed as such /function example_folder/example_file.

Loot Tables

Main article: Loot table

Loot tables are what tells the game what to drop when killing a mob, or what to put in a chest, or what armor mobs wear or even what you get from fishing.

to add loot tables first create a folder called loot_tables within your main folder. Minecraft pulls from 4 subfolders called chests, entities, equipment, and gameplay.

chests is responsible for any loot found in chests throughout the world, and it will also pull form a subfolder within it named village which is responsible for village loot.

entities is responsible for the items dropped by any entities, as well as things such as the armor worn by entities, and things such as piglin bartering.

equipment is responsible for the low tier equipment worn by mobs

And gameplay is responsible for fishing and mooshroom milking, it contains two subfolders, fishing and entities.

Here is an example of a cow's loot table.

 1 {
 2     "pools": [
 3         {
 4             "rolls": 1,
 5             "entries": [
 6                 {
 7                     "type": "item",
 8                     "name": "minecraft:leather",
 9                     "weight": 1,
10                     "functions": [
11                         {
12                             "function": "set_count",
13                             "count": {
14                                 "min": 0,
15                                 "max": 2
16                             }
17                         },
18                         {
19                             "function": "looting_enchant",
20                             "count": {
21                                 "min": 0,
22                                 "max": 1
23                             }
24                         }
25                     ]
26                 }
27             ]
28         },
29         {
30             "rolls": 1,
31             "entries": [
32                 {
33                     "type": "item",
34                     "name": "minecraft:beef",
35                     "weight": 1,
36                     "functions": [
37                         {
38                             "function": "set_count",
39                             "count": {
40                                 "min": 1,
41                                 "max": 3
42                             }
43                         },
44                         {
45                             "function": "furnace_smelt",
46                             "conditions": [
47                                 {
48                                     "condition": "entity_properties",
49                                     "entity": "this",
50                                     "properties": {
51                                         "on_fire": true
52                                     }
53                                 }
54                             ]
55                         },
56                         {
57                             "function": "looting_enchant",
58                             "count": {
59                                 "min": 0,
60                                 "max": 1
61                             }
62                         }
63                     ]
64                 }
65             ]
66         }
67     ]
68 }

Recipes

Main article: Recipe

Recipes allow players to craft items.

To add recipes, you must create a folder names recipes within the main folder. within that folder, the game uses .json to create recipes.

There are many different kinds of recipes.

Shaped Crafting

in a crafting table, there are two types of crafting, shaped and shapeless, we will begin with shaped.

In a shaped recipe, you have a specified pattern and a key of items like so:

The below code is the recipe for a diamond axe.

{
  "format_version": "1.12",
  "minecraft:recipe_shaped": {
    "description": {
    "identifier": "minecraft:diamond_axe"
    },

    
    "tags": [ "crafting_table" ],
    "pattern": [
      "XX",
      "X#",
      " #"
    ],
    "key": {
      "#": {
        "item": "minecraft:stick"
      },
      "X": {
        "item": "minecraft:diamond"
      }
    },
    "result": {
      "item": "minecraft:diamond_axe"
    }
  }
}

in the above code, there is a "pattern", this pattern specifies how a recipe is shaped. the pattern in this case is 2 wide and 3 tall, as the diamond axe is crafted as such. this pattern can be flipped, and put in any place on the grid, and any pattern that is 2x2 or less will work in the inventory crafting grid. the pattern for paper is shaped as such:

"###"

and so it can be placed anywhere on the grid horizontally. they can also be flipped. the pattern for a fishing rod is as such:

" #",

" #X",

"# X"

where # is a stick and X is string, but the fishing rod can also be flipped horizontally, but not vertically.

Shapeless Crafting

there is another type of crafting which is shapeless, the shapeless crafting has no pattern, but instead has a list and number of items for the craft.

The below code is the recipe for a netherite ingot.

{
  "format_version": "1.12",
  "minecraft:recipe_shapeless": {
    "description": {
    "identifier": "minecraft:netherite_ingot"
    },


    "tags": [ "crafting_table" ],
    "ingredients": [
      {
        "item": "minecraft:netherite_scrap",
        "count": 4
      },
      {
        "item": "minecraft:gold_ingot",
        "count": 4
      }
    ],
    "result": {
      "item": "minecraft:netherite_ingot",
      "data": 0,
      "count": 1
    }
  }
}

in this recipe there are ingredients and counts. these define what the ingredients are and how many of each item are needed. there is also a "tags" line which defines what you can craft them in, there are only two "crafting_table" and "stonecutter" the stonecutter recipes can only have one input and one output and are made in the stonecutter.

Smelting

You can also create new furnace, smoker, blast furnace, campfire, and soul campfire recipes.

The below code is the furnace recipe for iron ingots from iron ore.

{
  "format_version": "1.12",
  "minecraft:recipe_furnace": {
    "description": {
    "identifier": "minecraft:furnace_iron_ore"
    },

    
    "tags": ["furnace", "blast_furnace"],
    "input": "minecraft:iron_ore",
    "output": "minecraft:iron_ingot"
  }
  
}

In this you see three things, tags, input and output, the input and output define what goes in and what comes out, the tags define in what you can smelt the item, there are 5 tags: "furnace", "blast_furnace", "smoker", "campfire", and "soul_campfire". so in the example of creating a new recipe that only works on campfires, you would only put the tags campfire and soul_campfire.

Setting up Entity JSON files structure

Now that our pack is set up, let's set up the folder structure for our .json files.

  • In the tutorial_behavior_pack folder, create a new folder called "entities"

The entities folder is where we will put all our JSON files for changing entity behaviors. Let's start by grabbing pig.json and copying it into our entities folder. After downloading the example pack, it can be found on this file path: \Vanilla_Behavior_Pack\entities\pig.json. Once pig.json is copied over, open it up in the text editor of your choice.

Entity JSON overview

Before we start modifying the JSON code, let's take a brief look at how our entity.json files are set up.

The JSON files for Minecraft entities are broken into 4 different sections:

minecraft:entity

This is the main object for every mob, all the behaviors and events that follow are the values contained in this object.

entity.json pseudocode
{
  "format_version": "1.16.0",
  "minecraft:entity": {
    "description": {
      "identifier": "minecraft:pig",
      "is_spawnable": true,
      "is_summonable": true,
      "is_experimental": false
    },
    "component_groups": { component groups go here },
    "components": { components go here },
    "events": { events go here }
  }
}
Note

This is not valid JSON for Minecraft! This is just an example of how our entity json files are laid out to use as reference. If you take a look at pig.json you will notice that "component groups go here" is actually filled in with components.

Note 2 - format_version

Format version is used to tell Minecraft what version of the JSON it should be trying to read. As we update our JSON and add new components, we need to tell the game what things it should be looking for. We do this by changing the format_version number.

DO NOT CHANGE THIS NUMBER! As the Minecraft JSON updates, you will need to update your JSON files to match what was added. However, if you do update your JSON, you will need to change this number to whatever the new number is. Alternatively, you can copy the new version of the JSON from the updated Vanilla files and then copy over the specific behaviors you had changed in the old version.

Component groups

Used to define groups of behavior, allow for easy removal/addition of multiple behaviors, useful for making states (i.e. Pig baby vs pig adult behaviors).

In pig.json there are 6 groups including pig_baby, pig_adult. Note that the behaviors in those groups will only run if the group is currently added to the entity. Thus, when the pig is a baby pig, the pig_baby component group will be added and running, but the pig_adult group will not be.

Components

Used to define individual behaviors that will run on every entity of this type.

Note that things like "minecraft:identifier" and "minecraft:type_family" are here because we want every type of pig to have these components.

Events

Events are used to add or remove component groups and are triggered by components we've added, or by Minecraft's native code.

Events can use a randomize function to pick between different results (see "minecraft:entity_spawned" in pig.json). Note that the weights for randomize can add to over 100. This is because they are not percentages! If you set the weight for making an adult pig to 23 and then the weight for making a pig baby to 100 then you will have a 23/123 chance of getting an adult pig and a 100/123 chance to get a baby pig when a pig is spawned.

Components of note

minecraft:identifier

This is required for every entity. This is how the game knows what entity this .json file will run behaviors for. The identifiers must be named appropriately! If you give an incorrect identifier you will either get unintended results or your entity may not work at all. If you aren't sure what the identifier should be for an entity, please refer to the json file for that entity in the Vanilla Behavior Pack (remember json files are in /Vanilla_Behavior_Pack/entities/)

minecraft:type_family

This sets the family type for the entity. Family types are used for filtering entities for various components. See "minecraft:rideable" and "minecraft:breedable" for examples where type is used!

minecraft:entity_spawned

This is an event that is triggered when an entity of this type is spawned. In pig.json this has a randomize function that determines whether the pig is going to spawn as a baby or an adult pig.

Making pigs explode

Adding components

Now that we've looked at how an entity is setup; it is time to actually modify the pig's code!

Find the creeper.json file in the Vanilla Behavior Pack's entity folder (Vanilla_Behavior_Pack/entities/) and open it in a new text editor window. You should now have the pig.json from our custom add-on and creeper.json from Vanilla open in two separate windows.

The first thing we want to do is to have the pig find a target. We can do this by adding the "minecraft:nearest_attackable_target" and "minecraft:target_nearby_sensor" components into the components object for pig.json.

Find "minecraft:behavior.random_look_around" in the components object, it should be the last component before the "events" section.

Add a comma after the closing bracket of random_look_around. This is where we are going to add the targeting component. Either type or copy and paste the target_nearby_sensor and nearest_attackable_target components from creeper.json into pig.json. The end of Pig.json's "components" section should now look something like this (new text is highlighted in green):

pig.json excerpt:

...

"minecraft:behavior.random_look_around": {
  "priority": 9
},
"minecraft:behavior.nearest_attackable_target": {
  "priority": 1,
  "entity_types": [
    {
      "filters": { "other_with_families": "player" },
      "max_dist": 16
    }
  ], 
  "must_see": true
},
"minecraft:target_nearby_sensor": {
  "inside_range": 3.0,
  "outside_range": 7.0,
  "on_inside_range": {
    "event": "minecraft:start_exploding",
    "target": "self"
  },
  "on_outside_range": {
    "event": "minecraft:stop_exploding",
    "target": "self"
  }
}

...

Notice that the ending brace for target_nearby_sensor does not have a comma after it because it is the last value in the value list for "components".

minecraft:nearest_attackable_target

This component finds the nearest attack target given certain restrictions.

  • Priority – This sets how important this component is. Components with a higher priority will be more likely to be run. Note that a lower number means a higher priority and that priorities can be negative!
  • Entity_types – This is where we filter for what types of entities this entity can set as its target.
  • Max_dist – if the entity we want to be able to targets is within this many blocks from this entity than we can target it
  • Must_see – whether the entity that we want to target must be seen to be able to be set as our target

Notice that in our code, we are filtering for type player and that we will be able to set it as our target once they get within 16 blocks of this entity.

minecraft:target_nearby_sensor

This component will trigger events based on how close the entity's target is.

  • Inside_range – the distance in blocks that a target is considered to be inside this entity's range
  • Outside_range – the distance in blocks that a target is considered to be outside this entity's range
  • On_inside_range – this will trigger the event specified when a target is closer than inside_range
  • On_outside_range – this will trigger the event specified when a target is farther than outside_range

Notice that on_inside_range and on_outside_range are going to be triggering the events "minecraft:start_exploding" and "minecraft:stop_exploding" respectively. This won't currently do anything because we have not added these events yet!

Adding events

Scroll down to the bottom of the "events" object in pig.json and add a comma after the closing curly brace of "minecraft:on_unleash". This is where we are going to add our new start and stop exploding events.

Either type or copy and paste the "minecraft:start_exploding" and "minecraft:stop_exploding" events from creeper.json into pig.json. The end of Pig.jsons events section should now look something like this (new text is highlighted in green):

pig.json excerpt:

...

"minecraft:on_unleash": {
  "remove": {
    "component_groups": [
      "minecraft:pig_leashed"
    ]
  }
},
"minecraft:start_exploding": {
  "remove": {
    "component_groups":[
      "minecraft:hunting"
    ]
  },
  "add": {
    "component_groups": [
      "minecraft:exploding"
    ]
  }
},
"minecraft:stop_exploding": {
  "remove": {
    "component_groups": [
      "minecraft:exploding"
    ]
  },
  "add": {
    "component_groups": [
      "minecraft:hunting"
    ]
  }
}

...

Now that we have brought over the creeper events, we need to do some cleanup. Our pig doesn't need a hunting component group so we can remove the "remove" section from start_exploding and the "add" section from stop_exploding. Our code should now look like:

pig.json excerpt:

...

"minecraft:on_unleash": {
  "remove": {
    "component_groups": [
      "minecraft:pig_leashed"
    ]
  }
},
"minecraft:start_exploding": {
  "add": {
    "component_groups": [
      "minecraft:exploding"
    ]
  }
},
"minecraft:stop_exploding": {
  "remove": {
    "component_groups": [
      "minecraft:exploding"
    ]
  }
}

...

Notice that both events are adding and removing a component group called "minecraft:exploding". Our pig does not have this component group yet!

Adding component groups

Scroll back up to the top of pig.json to the "component_groups" section. Find the last component group, which should be pig_leashed, and add a comma to its closing curly brace. Now either type the following, or copy the "minecraft:exploding" component group from creeper.json. Pig.json should now look like the following (new code in green):

pig.json excerpt

...

  "minecraft:pig_leashed": {
    "minecraft:behavior.move_towards_restriction": {
      "priority": 2,
      "speed_multiplier": 1.0
    }
  },
  "minecraft:exploding": {
    "minecraft:explode": {
      "fuseLength": 1.5,
      "fuseLit": true,
      "power": 3,
      "causesFire": false
    }
  }
},
"components": {
  "minecraft:damage_sensor": {

...

minecraft:explode

fuseLength – how long it takes, in seconds, until this entity explodes from when the fuse is lit

fuseLit – whether the fuse is automatically lit when this component is added

power – this determines the damage done, and how big the explosion radius is

causesFire – this determines whether the explosion will cause nearby blocks to catch on fire or not

Let's add a scale component to this group as well, so that our pig grows in size before it explodes! Add a comma to the closing curly brace of the "explode" component and put in the following (new text in green):

pig.json excerpt

...

  "minecraft:exploding": {
    "minecraft:explode": {
      "fuseLength": 30,
      "fuseLit": true,
      "power": 1,
      "causesFire": false
    },
    "minecraft:scale": {
      "value": 2      
    }
  }
},
"components": {
  "minecraft:damage_sensor": {

...

minecraft:scale

Value – a multiplier to the normal scale of the entity. A value of 2 will double the scale, a value of .5 will halve the scale, etc.

Testing our add-on

  • Launch the game
  • Create a new world
  • Set world to creative
  • Turn on cheats
  • Click on add-ons
  • Find "Tutorial Behavior Pack" in the list on the right and click it
  • Click play
  • Spawn a pig using the pig spawn egg from the creative inventory
  • Run 20 blocks or so away
  • Switch mode to survival by using the slash command: /gamemode s
  • Run toward the pig

Congratulations!

You've only just scratched the surface of what is possible with Add-ons! If you want to be able to do more than just make things explode, check out the Entity Component Reference Guide to see other behaviors and components you can add to entities! You can also always look at how the Vanilla Behavior pack is set up for examples.

Note on available behavior changes

Not all behaviors of a mob are data driven yet! You cannot change the details for special movement behaviors like flying (bat, ghast, blaze) or swimming (squid, guardian, guardian elder). This can also interfere with behaviors you might add to them. For example, giving the squid a melee attack does not work while it is in water as its swimming behavior is still hard coded. Additionally it is not possible to just change some mobs behavior such as for example the witch utilizing potions is not data driven yet and you will be unable to control it.

Look forward to these changes in the future!

Challenges

Now that you've gotten some basic experience, here are some challenges:

  • Make zombies rideable by the player
    • Have the player able to control direction with an item (hint: look at pig's item_controllable and controlled_by_player)
  • Make villagers transform into skeletons when given a bow (hint: look at wolf's tameable and villagers transformation)
  • Change the texture of the sun and moon
  • Make a cow shoot the ghast's projectile

Troubleshooting JSON

If your JSON changes don't appear to be working in game, check the following things:

  • Make sure that you've typed everything correctly. Typos and missing punctuation will cause unwanted behavior!
  • Make sure the .json file is in the correct folder and named correctly!
    • You should have a folder called entities that contains all your .json files
  • Make sure your entity has the correct identifier
    • Check the .json file in the Vanilla Minecraft pack if you aren't sure what it is supposed to be
    • Vanilla's .json files can be found in /Vanilla_Behavior_Pack/entities or downloading it through this link

Exporting and sharing

Now that you've created a behavior pack, you probably want to share it with friends! To do this, perform the following:

  • Navigate into your development_behavior_packs folder
    • (%userprofile%\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs\tutorial_behavior_pack)
  • Select all of the files and folders
  • Right click on the highlighted files and select send to -> compressed zip folder
  • Name the file tutorial_behavior_pack.mcpack
    • Make sure to change the file extension to .mcpack
    • when the popup asks you if you are sure you want to change the file extension. Hit Yes

You can now give your friends that .mcpack file! When they open it, Minecraft will launch if it isn't running yet, and then it will import your resource pack for them to use!

Note

You can test to see if the exported behavior pack works by deleting your copy in your development_behavior_packs folder (make a backup first!), then opening your mcpack to import it. If it doesn't work, make sure you selected the contents of your behavior pack and not the folder itself when making the .mcpack zip.

Note 2

If your behavior pack references a resource pack, the mcpack won't automatically include that resource pack as well, even if you have given the behavior pack_manifest a dependency on that pack. If you have a resource pack dependency either: make a .mcpack for the resource pack as well, or make a world and add the behavior and resource packs you want to export and then export that world. When that world is imported, the save folder for that world will have a folder for the behavior packs and resource packs of that world. You can copy those packs to your local folders to be able to see them in the behavior and resource pack menus and add them to other worlds.

Shortcuts

On Bedrock Edition, there are a few third-party apps you can download to make Add-Ons without the hassle of JSON. Google Play users have access to "Add-Ons Maker" by PA Technologies. The interface is easy to use, and there is no JSON code-writing whatsoever. Exports are as easy as selecting a previously-made world and sending it. Your Minecraft app automatically holds a copy for future uses too.

Advertisement