xiaokun/netease-modsdk-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

搬运一批Bedrock wiki内容，完善翻译

Browse Source
This commit is contained in:
boybook
2025-03-20 00:13:44 +08:00
parent ead7392a76
commit 4896c1a4f2
163 changed files with 33930 additions and 1464 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/wiki/guide/addons.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Addons Explained
category: Guide
description: The basics of Addons
nav_order: 2
prefix: '2. '
mentions:
- SirLich
- Dreamedc2015
- sermah
- cda94581
- RedSmarty
- TheItsNameless
- MedicalJewel105
- ChibiMango
- profeplaysminecraft
- retr0cube
- SmokeyStack
---
## What are addons?
Addons allow us to modify the contents of our Minecraft Experience by _modifying_ or _removing_ existing content and _adding_ our own. Addons are very powerful and allow us to create custom entities, items, and blocks, as well as things like custom loot tables and crafting recipes. Your imagination is the limit!
Addons are primarily written in [json](/guide/understanding-json), which is a structured data-format. An addon is essentially a collection of json files, images, and sounds, which modify or add to the game in some way.
## What's the difference between a Behavior Pack & a Resource Pack?
Addons are split into two pack types: Resource Packs, and Behavior Packs. Both can function independently, but they are most commonly used together. When you have both a Resource Pack and Behavior Pack, this is referred to as an _addon_.
### Resource Pack
The Resource Pack, also known as the _client_, or RP, is responsible for the _visuals_ and _sounds_ in your addon. This includes things like:
- Textures
- Sounds
- Geometry
- Animations
- Particles
### Behavior Pack
The Behavior Pack, also known as the _server_, or BP, is responsible for the _logic_ of your addon. This can include things like:
- How your entity acts
- Crafting recipes
- Loot tables
- Custom functions
### Communication between packs
In most cases, you will have both a RP and a BP together. These packs can communicate with or will require each other for them to function properly, in the sense that assets defined in one can be accessed in the other. For example, when creating a custom entity, you need two files:
- An RP entity definition, which describes how your entity will _look_
- A BP entity definition, which describes how your entity will _act_
## What you have learned
:::tip
- Addons modify Minecraft content or add their own
- Addons are written in json
- An addon is split into the **Resource Pack** and the **Behavior Pack**: - Resource Packs contain Textures, Sounds, ... and control how the game looks - Behavior Packs contain entity-files, crafting recipes, ... and control the logic of your game
:::
## What to do now?
<BButton
link="/guide/software-preparation"
color=blue
>Check out software and preparation page!</BButton>

47
docs/wiki/guide/advancedmanifest.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: Advanced Manifest
category: Extra
description: How to work with manifests - a more detailed guide [UNDER CONSTRUCTION]
nav_order: 4
prefix: 'd.'
mentions:
- MRBBATES1
- Luthorius
- SirLich
- smell-of-curry
- MedicalJewel105
- QuazChick
---
::: tip
This is an appendix page. You can start the guide from the beginning [here](/guide/index).
:::
This page is desgined to go into more detail about the manifest.json file, here we will cover what UUIDs are in more detail and how to add them. We will explain the use of dependencies, the different format versions, and how to include meta-data.
We will also go over the version differences between Behaviour packs, Resource packs, and Skin packs.
## UUIDs
UUID is an abbreviation for Universal Unique Identifier, there are 5 UUID versions plus one common unofficial version, A UUID is a 36 character string containing numbers, letters, and dashes.
Minecraft uses Version 4: Variant 1, which is completely random. This is what creates your pack's unique identity in Minecraft.
### How to Generate the correct UUID
You can use online sites such as [UUID Generator](https://www.uuidgenerator.net/version4/) and [UUID Tools](https://www.uuidtools.com/generate/v4) to generate the correct version required for Minecraft.
##
### UUID FAQ
- **Are UUIDs Case-sensitive?**
- _No, UUIDs are written in base 16 which uses numbers 0-9 and characters a-f. There is no distinction between upper and lowercase letters._
- **Can I use the same UUID for the header and the modules UUID?**
- _No, the UUID for the header and the module needs to be different._
:::warning
This page is under construction!
:::

283
docs/wiki/guide/blockbench.md Normal file
View File

@@ -0,0 +1,283 @@
---
title: 'Blockbench: Modeling, Texturing and Animating'
category: Guide
description: A first peek into Blockbench
prefix: '7. '
nav_order: 7
mentions:
- KaiFireborn
- SirLich
- Dreamedc2015
- SmokeyStack
- sermah
- cda94581
- TheItsNameless
- ThijsHankelMC
- MedicalJewel105
- ChibiMango
- smell-of-curry
---
Blockbench is a free software designed to make Minecraft modeling, texturing, and animating possible. It is available for mobile browsers, Windows 10, and macOS. Please install it at [blockbench.net](https://blockbench.net/).
Let's get started.
1. Open Blockbench.
2. Choose _File>New>Bedrock Model_. This is important because Minecraft Bedrock will not be able to read Java models.
3. A screen like this will have popped up.
![](/assets/images/guide/create_entity_project_menu.png)
- `"File name:"` is self-explanatory. My file will generate as "skele_yaklin.geo.json".
- `"Model Identifier:"` is the model identifier (namespace not required), a short name for this ID will be defined later.
- `"Box UV"` has to be checked on for automatic UV editing and unwrapping for texturing.
- `"Texture Height"` and `"Texture Width"` define the resolution of the model's textures.
4. Press confirm. You'll see a screen like this:
![](/assets/images/guide/create_entity_workspace.png)
- You can see many tools here: move, resize, rotate, etc.
- You can add bones and cubes in the menu on the right-bottom corner. Cubes can rotate on their own; the bones will carry everything in them along;
5. Now, you are ready to create your model! For more in-depth tutorials on modeling, please check out the videos by Everbloom Studio below.
<YouTubeEmbed id="XqzxL_-XjA0" />
<YouTubeEmbed id="j7ISUImhgpc" />
## Texturing
Now that you have your model in place let's start texturing!
1. On the left-bottom panel, click "Create Texture"
1. Write down your image file name under "Name:". Mine will export as `ghost.png`. Check "Template:" to make a template texture - it'll be easier to work with.
![](/assets/images/guide/create_entity_texture_1.png)
1. Check everything and change your resolution to the one you set in the very first step.
![](/assets/images/guide/create_entity_texture_2.png)
1. Go to "Paint" in the upper right corner and paint your texture.
## Animating
Once your model and texture are done, you can start animating. Go to "Animate" in the upper right corner.
You might want to adjust one of the toolbars by adding "Export Animations" and "Import Animations" like this:
![](/assets/images/guide/create_entity_animation_1.png)
1. Click "Add Animation" [the plus icon on the top right side] and name it `animation.{yourEntityName}.move`.
Create the first frame of your walking animation under 0 on the timeline by moving the legs.
![](/assets/images/guide/create_entity_animation_2.png)
1. Create the second frame under 0.5 on the timeline.
![](/assets/images/guide/create_entity_animation_3.png)
1. Finally, copy the first frame to the third frame by placing your timeline cursor on 1.0 and selecting the first frame, then ctrl+c, ctrl+v.
1. Right-click the animation and tick "Loop" for the animation to loop.
![](/assets/images/guide/create_entity_animation_4.png)
## Saving your work
Now that our model, texture, and walk animation are complete, you can save your work.
Go to _File > Save Model_ or _File > Export Bedrock Geometry_. Save the model in `RP/models/entity`, the texture in `RP/textures/entity/` and the animation in `RP/animations`. Congratulations! You've successfully created your first entity's visuals! You can see the file examples below.
_Meanwhile, why not upgrade the visuals of your own unique entities' or create another one?_
<Spoiler title="Show code">
<CodeHeader>RP/models/entity/ghost.geo.json</CodeHeader>
```json
{
"format_version": "1.12.0",
"minecraft:geometry": [
{
"description": {
"identifier": "geometry.ghost",
"texture_width": 64,
"texture_height": 64,
"visible_bounds_width": 3,
"visible_bounds_height": 3.5,
"visible_bounds_offset": [0, 1.25, 0]
},
"bones": [
{ "name": "root", "pivot": [0, 3, 0] },
{
"name": "body",
"parent": "root",
"pivot": [0, 4.625, 0],
"cubes": [
{
"origin": [-4, 3, -4],
"size": [8, 13, 8],
"uv": [0, 20]
}
]
},
{
"name": "leftArm",
"parent": "body",
"pivot": [4.6, 15.5, 0.5],
"cubes": [
{
"origin": [4.1, 7, -1],
"size": [3, 9, 3],
"uv": [32, 32]
}
]
},
{
"name": "rightArm",
"parent": "body",
"pivot": [-4.5, 15.5, 0.5],
"cubes": [
{
"origin": [-7.1, 7, -1],
"size": [3, 9, 3],
"uv": [32, 20]
}
]
},
{
"name": "head",
"parent": "body",
"pivot": [0, 16, 0],
"cubes": [
{
"origin": [-5, 16, -5],
"size": [10, 10, 10],
"uv": [0, 0]
}
]
}
]
}
]
}
```
<CodeHeader>RP/animations/ghost.a.animations.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"animations": {
"animation.ghost.idle": {
"loop": true,
"animation_length": 3,
"bones": {
"body": {
"rotation": { "0.0": [10, 0, 0], "3.0": [10, 0, 0] },
"position": {
"0.0": [0, 0, 0],
"1.5": [0, 1, 0],
"3.0": [0, 0, 0]
}
},
"leftArm": {
"rotation": {
"0.0": [-10, 0, 0],
"1.5": [-5, 0, 0],
"3.0": [-10, 0, 0]
}
},
"rightArm": {
"rotation": {
"0.0": [-10, 0, 0],
"1.5": [-5, 0, 0],
"3.0": [-10, 0, 0]
}
},
"head": {
"rotation": {
"0.0": [-7.5, 0, 0],
"1.5": [-2.5, 0, 0],
"3.0": [-7.5, 0, 0]
}
}
}
},
"animation.ghost.attack": {
"animation_length": 0.75,
"bones": {
"body": {
"rotation": {
"0.0": [10, 0, 0],
"0.2917": [10, 15, 0],
"0.5": [22.5, -12.5, 0],
"0.75": [10, 0, 0]
},
"position": {
"0.0": [0, 0, 0],
"0.2917": [0, 0, 3],
"0.5": [0, 0, -3],
"0.75": [0, 0, 0]
}
},
"leftArm": {
"rotation": { "0.0": [-10, 0, 0], "0.75": [-10, 0, 0] }
},
"rightArm": {
"rotation": {
"0.0": [-10, 0, 0],
"0.2083": [-10, 0, 0],
"0.2917": [-10, 62.5, 117.5],
"0.5": [-80, -17.5, 22.5],
"0.75": [-10, 0, 0]
}
},
"head": {
"rotation": { "0.0": [-7.5, 0, 0], "0.75": [-7.5, 0, 0] }
}
}
},
"animation.ghost.move": {
"loop": true,
"animation_length": 1,
"bones": {
"body": {
"rotation": {
"0.0": [15, 0, 0],
"0.25": [15, -2.5, 0],
"0.5": [15, 0, 0],
"0.75": [15, 2.5, 0],
"1.0": [15, 0, 0]
},
"position": [0, 0, 0]
},
"leftArm": {
"rotation": {
"0.0": [15, 0, 0],
"0.5": [20, 0, 0],
"1.0": [15, 0, 0]
}
},
"rightArm": {
"rotation": {
"0.0": [15, 0, 0],
"0.5": [20, 0, 0],
"1.0": [15, 0, 0]
}
},
"head": {
"rotation": {
"0.0": [-12.5, 0, 0],
"0.5": [-15, 0, 0],
"1.0": [-12.5, 0, 0]
}
}
}
}
}
}
```
</Spoiler>
## What you have learned
<Checklist>
- [x] How to create an entity in Blockbench
- [x] How to use Blockbench to model, texture, and animate your entity
</Checklist>

1431
docs/wiki/guide/custom-entity.md Normal file
View File

File diff suppressed because it is too large Load Diff

322
docs/wiki/guide/custom-item.md Normal file
View File

@@ -0,0 +1,322 @@
---
title: 'Create a custom Item'
category: Guide
description: How to create your first custom Item
nav_order: 5
prefix: '5. '
mentions:
- KaiFireborn
- SirLich
- cda94581
- TheItsNameless
- MedicalJewel105
- ChibiMango
- TheDoctor15
- SmokeyStack
- unickorn
- Sprunkles317
- ThomasOrs
- davedavis
---
In Minecraft, we can create custom items, which can be dropped, traded, crafted, and otherwise used like a normal item. There is a lot of power in the system, including the ability to make food, fuel, and tools.
In this tutorial we are going to learn how to create a simple "ectoplasm" item, which we will later use as a loot-table drop for our ghost entity.
<br>
<img src="/assets/images/guide/custom_item/ectoplasm_view.png" width=150>
<br>
<br>
Conceptually, items are made up of two parts:
- The visuals (texture, name)
- The behaviors (how the item should behave)
First, we will learn how to create a new simple item & define its behaviors. In the next section we will assign a texture to this item, so you can see it in game.
:::warning
This guide requires experimental features toggled on.
:::
## Item Behavior
To make an item we will need a way to identify it and define how we want it to behave. To do this we will be making a file which tell Minecraft to apply certain behaviors to a specific item of our choice.
At the end of this section we will have fully defined the behavior of our item.
### Components
Different items behave differently; you can eat a porkchop, enchanted items glow & eggs can only stack to 16. These are all examples of how the item behaves.
We are able to define how our custom item will behave by using behavior components.
<Spoiler title="Example Components">
<CodeHeader>BP/items/example.json/components/</CodeHeader>
```json
"minecraft:food":
"minecraft:foil": true,
"minecraft:max_stack_size": 16
```
</Spoiler>
Components contain information which tells the game what our item should do. For example the component `"minecraft:foil"` determines whether the item should have an enchanted foil to it, so setting it to `true` will apply it.
All components have a `value` attached to it which we can edit to get the behaviour we want.
For our ectoplasm, we will set it to have a stack size of 16, similar to eggs. To do this we use the component `"minecraft:max_stack_size"` and set its value to `16`.
### Identifier
In order for the game to apply the correct components to the correct item, we need to be able to tell the game which item is ours. We do this by defining an identifier for our item.
An identifier is a name unique to this item. For a vanilla minecraft egg it's identifier is `minecraft:egg`. An identifier is made of two parts,
- The namespace (`minecraft`)
- The id (`egg`)
The namespace is unique to your addon and you will use it throughout the project. This is to reduce issues if someone adds two packs to your game which both add an ectoplasm item; the namespace reduces the chance of the identifier being the same.
The namespace that Minecraft use is `minecraft`. Your namespace should be unique to you, for example the authors initials or an abbreviation of the pack name. We will use the namespace `wiki` in our example; for more information on making a namespace check out our page [here](/concepts/namespaces).
The id is an informative shorthand name for your item. Here we will use `ectoplasm`.
Together our custom identifier becomes `wiki:ectoplasm`. Note that we use a colon, `:`, to spilt the namespace and id. When we want to reference our item we will use this identifier, for example using the `/give` command.
### Item File
Now that we have our components and identifier, we can now start defining our item. We define an item by creating an item definition file in our behavior pack. This is where all our information will go.
All item definitions go in `BP/items/`. The name of your file doesn't affect anything, but for ease of navigation it's recommend to name it after your id.
We will create a file `BP/items/ectoplasm.json`. Here is the the basic layout of the file:
<CodeHeader>BP/items/ectoplasm.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {...},
"components": {...}
}
}
```
Most files in your pack will have 2 top level definitions, `"format_version"` and `"minecraft:<file_type>"`.
The format version defines which version of the Addon system Minecraft will use to read this file. For our item, we will be using `1.16.100` to allow us to use the experimental features. For more information on format version you can check [here](/guide/format-version).
The second definitions defines what kind of file this is. In our case, as this is an item definition, it is `minecraft:item`. Under this is where we will put all our information. This will always contain a `description` key.
Let us look closer at the `"description"`:
<CodeHeader>ectoplasm.json/minecraft:item/</CodeHeader>
```json
"description": {
"identifier": "wiki:ectoplasm",
"category": "Items"
},
```
The description key contains the `identifier` and any other information required. The `identifier` allows the file to know which item to apply the components to.
The `category` key defines which tab of the creative inventory the item would show up in. There are four tabs to choose from: `"Nature"`, `"Equipment"`, `"Construction"` and `"Items"`. If this key is not included, then the item will not show in the creative inventory, but you can still get the item by using `/give`.
Now we can actually define the behavior of our item, under `components`. Here we simply place any components we want our item to have.
This will be our `"minecraft:max_stack_size"` component. For other components you can use, check out our more in depth guide on Items [here](/items/item-components).
<CodeHeader>ectoplasm.json/minecraft:item/</CodeHeader>
```json
"components": {
"minecraft:max_stack_size": 16
}
```
With that, we have now fully defined our item's behavior. This is what your file should currently look like.
<CodeHeader>BP/items/ectoplasm.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:ectoplasm",
"category": "Items"
},
"components": {
"minecraft:max_stack_size": 16
}
}
}
```
If you open a world with your addon, your item should be in the correct menu but invisible and have a strange name.
This is because we haven't defined the visuals yet. However, you should see that it does stack as expected. In the next section, we will define the items texture and assign it to our item.
## Item Visuals
Now that we have an item that works, we want to add a texture and name to it.
Textures are stored in the resource pack under `RP/textures` as images. In order for Minecraft to know which texture to use where, we need to assign a shortname to it, so we can access it.
### Texture
To start we need a texture for our item. For our ectoplasm, we will be using this image.
![ectoplasm.png](https://raw.githubusercontent.com/Bedrock-OSS/wiki-addon/86b0380310d3d5748a43a4be1f93d4c59668e4bf/guide/guide_RP/textures/items/ectoplasm.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/wiki-addon/86b0380310d3d5748a43a4be1f93d4c59668e4bf/guide/guide_RP/textures/items/ectoplasm.png">Download texture here</BButton>
All item textures are stored in `RP/textures/items/`. From here, you can create any subdirectories you wish.
It's best to name your texture image files with the items' _id_, in our case it will be `ectoplasm.png`.
It is recommended to have your images in `.png` format and be of size `16x16`, though Minecraft will accept other formats such as `.jpg` or `.tga`.
Your folder layout should look like this:
<FolderView
:paths="[
'RP/textures/items/ectoplasm.png'
]"
/>
### Shortname
A shortname is essentially a name that is assigned to the folder path of the texture, so whenever we want to use a texture somewhere, we will use its shortname instead of its folder path.
All item shortnames are stored in one file called `item_texture.json` which is in `RP/textures`. This contains a list of shortnames and its assigned textures.
<CodeHeader>RP/textures/item_texture.json</CodeHeader>
```json
{
"resource_pack_name": "Ghostly Guide",
"texture_name": "atlas.items",
"texture_data": {...}
}
```
Here we have 3 top level definitions, `texture_data` is where we will define our shortnames, the other two define the type of file this is.
The `resource_pack_name` is simply our resource pack's name and `texture_name` is what kind of texture file this is. Since this is for _items_, this will always be set to `atlas.items`.
Under `texture_data` will our list of item shortname definitions. An example definition looks like this:
<CodeHeader>RP/textures/item_texture.json/texture_data</CodeHeader>
```json
"wiki.ectoplasm": {
"textures": "textures/items/ectoplasm"
}
```
Here `wiki.ectoplasm` is our shortname and under `textures` we have the path to our item. Notice that this is relative to the resource pack, and does not include the file extension. Your shortname should be short and unique. We recommend setting it as the namespace and id for the item we are assigning it to.
Now whenever we want to refer our image, we will use the shortname `wiki.ectoplasm`.
### Icon
To finally apply our texture to our item, we add the `minecraft:icon` component to our item definition and set its value to our shortname.
<CodeHeader>ectoplasm.json/minecraft:item/</CodeHeader>
```json
"components":{
"minecraft:max_stack_size": 16,
"minecraft:icon" : {
"texture": "wiki.ectoplasm"
}
}
```
Now your texture should appear on your item.
### Item Name
The last thing to add is a nice name to your item. Currently it will look like `item.wiki:ectoplasm`. This is the translation key for your item name, and it is used to allow for [localization](/concepts/text-and-translations). To set it, we just have to define it in our language files.
We already created these files when making our `RP` and `BP`, so we just need to add to them.
<CodeHeader>RP/texts/en_US.lang</CodeHeader>
```
item.wiki:ectoplasm=Ectoplasm
```
Now when you enter your world, your item should have a name.
## Overview
Now your first custom item, Ectoplasm, is complete! If everything has been done correctly, the item should now be obtainable through the `/give` command in-game, as well as appearing in your creative inventory.
Your folder structure should look like this:
<FolderView :paths="[
'RP/textures/item_texture.json',
'RP/textures/items/ectoplasm.png',
'RP/texts/en_US.lang',
'RP/texts/languages.json',
'RP/manifest.json',
'RP/pack_icon.png',
'BP/items/ectoplasm.json',
'BP/texts/en_US.lang',
'BP/texts/languages.json',
'BP/manifest.json',
'BP/pack_icon.png',
]"></FolderView>
<Spoiler title="Full ectoplasm.json">
<CodeHeader>BP/items/ectoplasm.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:ectoplasm",
"category": "Items"
},
"components": {
"minecraft:max_stack_size": 16,
"minecraft:icon": {
"texture": "wiki.ectoplasm"
}
}
}
}
```
</Spoiler>
<Spoiler title="Full item_texture.json">
<CodeHeader>RP/textures/item_texture.json</CodeHeader>
```json
{
"resource_pack_name": "Ghostly Guide",
"texture_name": "atlas.items",
"texture_data": {
"wiki.ectoplasm": {
"textures": "textures/items/ectoplasm"
}
}
}
```
</Spoiler>
If you're having some trouble, check the [Troubleshooting page](/items/troubleshooting-items). If that doesn't help, compare your results with the [example files](https://github.com/Bedrock-OSS/wiki-addon/tree/main/guide).
## Your progress so far
<Checklist>
- [x] Setup your pack
- [x] Create a custom item
- [x] How to format the behavior and resource files for an item
- [x] What components are and how to use them
- [x] How to set an items texture
- [ ] Create a custom entity
- [ ] Create the entity's loot, spawn rules, and a custom recipe
</Checklist>

33
docs/wiki/guide/download-packs.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Download Example Packs
category: Extra
description: Appendix for downloading example Packs
prefix: 'b. '
nav_order: 2
show_toc: false
mentions:
- SirLich
- Joelant05
- Dreamedc2015
- sermah
- SmokeyStack
- MedicalJewel105
- Luthorius
- TheDoctor15
- TheItsNameless
---
::: tip
This is an appendix page. You can start the guide from the beginning [here](/guide/index).
:::
To get the most out of the guide, you should always attempt all guide-exercises yourself! However if you get very stuck, the example packs should give you some valuable reference material.
Download here:
<BButton
link="https://github.com/Bedrock-OSS/wiki-addon/releases/download/download/legacy_guide.mcaddon"
color=gray
>Download Add-On</BButton>
To install, simply unzip the behavior pack into the Minecraft folder: `com.mojang\development_behavior_packs` or `com.mojang\development_*_packs`, depending on which pack you downloaded.

110
docs/wiki/guide/format-version.md Normal file
View File

@@ -0,0 +1,110 @@
---
title: Format Versions
category: Extra
description: How to work with Format Versions
prefix: 'e. '
nav_order: 5
mentions:
- SirLich
- SmokeyStack
- ThomasOrs
- Xterionix
---
Format versions are an important part of Minecraft: Bedrock Edition's Addon System. They appear at the top of most files, formatted like this: `"format_version": "1.16.100"`. You can think of this as the "version number" of the file, and the number you select here is really important! The format version you select will define which syntax and features are available to you, in that particular file.
:::tip
Selecting the wrong format version is a common source of errors. When troubleshooting, people may ask you questions like 'what format version is your item'. Ensure that you know how to answer that question.
:::
## Why do format versions exist?
Format versions exist to *version* the Addon system, and allow Minecraft to introduce new features into the addon system, without breaking old Addons. For example, a `1.8.0` format version RP Entity file has very different syntax than a `1.10.0` format version RP Entity file. By using the 'format_version' key in the json *you* can decide which version you want to use.
By using format versions *per file*, Minecraft gives you a lot of control over how your addon will be interpreted by the game. It is completely possible and expected to mix different format versions in your addon.
## Experimental Format Versions
Format versions are also used for the purpose of versioning experimental features. Since Minecraft releases bedrock experiments directly into stable, some format versions will be 'locked' under experimental, unless you toggle the correct experiment.
A well known example is the item/blocks system, where `1.16.100` denotes experimental, and `1.10.0` denotes stable. If you want to make an item, it's important to select a format version early, as it will effect everything else you add to the files. If you are going with an experimental format version for your item/block you may want to go higher than `1.16.100` because some experimental features won't work properly in that format version, for example if you are making a custom spawn egg and you want it to be able to set the entity type of a monster spawner, then you need to the format version to `1.19.80` or higher.
## Format Version is not Game Version
It is really important to understand that format version is *per subsystem*, and is generally not equal to the base game version. This simply means that every type of file (item, rp entity, bp entity, recipe) will use a different versioning system.
For example: `"format_version": "1.8.0"` in an RP entity file means "use version `1.8.0` of the *item system*". It does *not* mean "use version `1.8.0` of the *addon system*".
For this reason, some file types will have very "old" format versions. Do not be tempted to replace this version with the latest game version, such as `1.17.0`.
## Format Version Fixing
Minecraft has a system that will "fix" your format version if you've written it wrong. This system isn't well understood, isn't enabled for all systems, and shouldn't be relied upon. But it's important to note that an incorrect format version will often "regress" downwards until it hits a valid format version. For example a `1.11.0` RP entity file will simply be interpreted as `1.10.0`, and cause no errors.
This system is useful, as it means you are less likely to generate a broken file, by selecting the wrong format version.
## Picking a Format Version
Generally speaking, there is a cool tricky to pick the correct format version, for any file type.
For example, imagine you are creating a Recipe file:
1) Install the [Vanilla Packs](/guide/download-packs).
2) Look at some recipe files, to judge which format version is most used, or the most recent
3) Use this format version in your file
This simple trick will help you select a valid format version for your file.
## Format Versions per Asset Type
This section will list the format versions used in the vanilla game, alongside how many times it appears.
- The '⭐' is the recommended *stable* version.
- The '🚀' is the recommended *experimental* version, where applicable.
### Resource Pack
| Resource Pack | Version | Count |
|----------------------|----------|-------|
| Entity | 1.10.0 ⭐ | 82 |
| Entity | 1.8.0 | 74 |
| Animation Controller | 1.10.0 ⭐ | 56 |
| Animation | 1.8.0 | 120 |
| Animation | 1.10.0 ⭐ | 6 |
| Attachables | 1.10.0 ⭐ | 29 |
| Attachables | 1.8.0 | 25 |
| Attachables | 1.10 | 1 |
| Models | 1.8.0 | 92 |
| Models | 1.12.0 | 19 |
| Models | 1.10.0 | 4 |
| Models | 1.16.0 | 7 |
| Particles | 1.10.0 ⭐ | 131 |
| Render Controllers | 1.10.0 ⭐ | 83 |
### Behavior Pack
| Category | Version | Count |
|-------------|------------|-------|
| Entities | 1.8.0 | 2 |
| Entities | 1.16.210 | 1 |
| Entities | 1.13.0 | 7 |
| Entities | 1.16.0 ⭐ | 58 |
| Entities | 1.16.100 | 3 |
| Entities | 1.12.0 | 21 |
| Entities | 1.17.20 | 7 |
| Entities | 1.17.10 | 4 |
| Entities | 1.10.0 | 1 |
| Entities | 1.14.0 | 1 |
| Items | 1.10 ⭐ | 44 |
| Items | 1.16.0 | 1 |
| Items | 1.16 | 1 |
| Items | 1.14 | 1 |
| Items | 1.16.100 🚀 | 0 |
| Items | 1.19.80 | 0 |
| Items | 1.20.40 | 0 |
| Recipes | 1.12 | 991 |
| Recipes | 1.16 ⭐ | 194 |
| Recipes | 1.14 | 2 |
| Spawn Rules | 1.8.0 ⭐ | 48 |
| Spawn Rules | 1.17.0 | 1 |
| Spawn Rules | 1.11.0 | 1 |

13
docs/wiki/guide/index.md Normal file
View File

@@ -0,0 +1,13 @@
---
title: Beginners Guide
nav_order: 1
categories:
- title: Guide
color: green
- title: Extra
color: blue
---
Welcome to the Bedrock Beginners Guide!
<BButton color="blue" link="introduction">Get Started!</BButton>

60
docs/wiki/guide/introduction.md Normal file
View File

@@ -0,0 +1,60 @@
---
title: Introduction
category: Guide
description: Introduction to our "Getting Started" Guide
tags:
- guide
nav_order: 1
prefix: '1. '
mentions:
- KaiFireborn
- SirLich
- BlueFrog130
- sermah
- SmokeyStack
- TheItsNameless
- MedicalJewel105
- smell-of-curry
- Hatchibombotar
- retr0cube
---
## What are Addons?
An "Addon" is the Minecraft Bedrock Edition (_Windows 10, iOS, Android, Consoles_) equivalent to Java mods. However, in contrast to Java, the Bedrock Edition API is officially maintained by Mojang instead of the community.
In general, you can think of _mods_ as _modifying_ the game, and _addons_ as _adding onto_ the game, following the development opportunities provided by Microsoft.
## What is this guide?
This guide is a beginner tutorial, intended to walk you through the first stages of addon-creation. You will create your very own fully-functional Ghost entity, as well as an Ectoplasm item, and some other associated files.
By the end of this guide, you will have created an entire addon all by yourself, which you can play with and modify!
In this guide you will find boxes like these:
:::tip
Some very helpful information!
:::
:::warning
Attention! Watch out for these common mistakes.
:::
Watch out for these boxes! They contain very important information that could help you with problems.
## Is the guide up to date?
This guide is written for the most recent _stable_ release of Minecraft Bedrock Edition. Many things won't work in previous versions, and some will be changed in later ones. We will keep the guide as up-to-date as possible, so no need to worry.
## Appendix Pages
Alongside the step-by-step guide, we have a few other files here, which may be interesting to you:
- [Understanding JSON](/guide/understanding-json)
- [Downloading Example Packs](/guide/download-packs)
- [Troubleshooting](/guide/troubleshooting)
## What to do after finishing the Guide
At the end of the guide section, your first addon will be done! To further expand your knowledge, consider doing these:
- Start your project!
- To dive into the other aspects of adding onto MCBE (Minecraft Bedrock Edition), you can use the different sections' sub guides listed in the Appendix. This includes but is not limited just to custom Blocks, Biomes, advanced Items, Animation Controllers, and even JS scripts. Some sections provide more technical in-depth tutorials and documents for each relevant topic.

179
docs/wiki/guide/loot-table.md Normal file
View File

@@ -0,0 +1,179 @@
---
title: 'Adding a Loot Table, a Spawn rule and a crafting recipe'
category: Guide
description: How to add your first Loot Table, Spawn Rule and Crafting Recipe
nav_order: 8
prefix: '8. '
mentions:
- KaiFireborn
- SirLich
- sermah
- cda94581
- Ultr4Anubis
- TheItsNameless
- Ciosciaa
- MedicalJewel105
- ChibiMango
- FrankyRay
---
Next, we'll enhance the custom Ghost entity by adding some more basic mechanics to it:
## Loot tables
First, we'll make the ghost drop Ectoplasm upon death: create the following file:
<CodeHeader>BP/loot_tables/entities/ghost.json</CodeHeader>
```json
{
"pools": [
{
"rolls": 1,
"entries": [
{
"type": "item",
"name": "wiki:ectoplasm",
"weight": 1,
"functions": [
{
"function": "set_count",
"count": {
"min": 1,
"max": 3
}
}
]
}
]
}
]
}
```
- Loot Tables consist of `"pools"`. Each pool defines a different loot. A pool consists of 3 parts, `"rolls"`, `"entries"` and `"conditions"`. The `"conditions"` are optional and won't be covered in this guide. To learn more about conditions, look at [Loot Tables](/loot/loot-tables).
- The `"rolls"` section defines how many times a random entry will be chosen from the following `"entries"`object.
- The `"entries"` part defines the items, from which the loot table can choose. Each roll a new item will be chosen.
- `"type"` defines what will be chosen. You can set it to `"item"` or `"loot_table"` to either chose an item or an different loot table.
- `"name"` will be set to an item identifier with its namespace. It defines which item will be selected.
- `"weight"` is optional and defines how likely it is, that this item will be selected. If there is more than one item in the `"entries"` section, the `"weight"` attribute can be used to make the probability of one item more or less likely. If it isn't set, it defaults to 1.
- `"functions"` provide a powerful way of customizing the item that will be returned. They can add enchantments to an item, setting an items' name or simply setting the number of items that will be dropped. To define the number of items, we use `"set_count"`. It takes the `"count"` attribute, which sets the maximum and minimum amount of items that will be dropped.
For more information on loot tables, see our extended guide: [Loot Tables](/loot/loot-tables)!
## Spawn rules
Next, we'll make the ghost spawn in deserts at night:
<CodeHeader>BP/spawn_rules/ghost.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"minecraft:spawn_rules": {
"description": {
"identifier": "wiki:ghost",
"population_control": "monster"
},
"conditions": [
{
"minecraft:spawns_on_surface": {},
"minecraft:brightness_filter": {
"min": 0,
"max": 7,
"adjust_for_weather": true
},
"minecraft:difficulty_filter": {
"min": "easy",
"max": "hard"
},
"minecraft:weight": {
"default": 80
},
"minecraft:herd": {
"min_size": 1,
"max_size": 3
},
"minecraft:biome_filter": {
"test": "has_biome_tag",
"operator": "==",
"value": "desert"
}
}
]
}
}
```
- You already know what `"format_version"`does.
- Inside the `"minecraft:spawn_rules"` part we define our spawn rules.
- The `"description"` defines the basic properties of the file. The `"identifier"` is used to define on which entity this spawn rule applies on. `"population_control"` is used to limit the amount of entities that will be spawned. Once the pool that is defined inside of `"population_control"` is full, no more entities will be spawned.
- With `"conditions"` we can define rules that limit the spawning of this entity to special cases. We will shortly describe each condition used here, but you can learn more conditions and how to use them [here](/entities/vanilla-usage-spawn-rules).
- `"spawns_on_surface"` allows the mob to only spawn on surfaces.
- `"minecraft:brightness_filter"` limits the spawning to areas with a lighting level thats between the defined values. If `"adjust_for_weather"` is `true`, the light level decrease during rain and storms will be ignored.
- `"minecraft:difficulty_filter"` defines the difficulty level needed to spawn the entity.
- `"weight"` defines how often this entity will spawn. The higher this value, the more often the mob will spawn.
- `"minecraft:herd"`defines how many entities will be spawned at once.
- With `"minecraft:biome_filter"` we define the biomes in which the entity is able to spawn.
To learn more about spawn rules, take a look on our guide on [Vanilla spawn rules](/entities/vanilla-usage-spawn-rules).
## Crafting recipes
And finally, as an introduction to recipes, we'll make the Ectoplasm craftable into Slime Blocks:
<CodeHeader>BP/recipes/ectoplasm_slime_blocks.json</CodeHeader>
```json
{
"format_version": "1.12.0",
"minecraft:recipe_shaped": {
"description": {
"identifier": "wiki:ectoplasm_slime_block"
},
"tags": ["crafting_table"],
"pattern": ["###", "###", "###"],
"key": {
"#": {
"item": "wiki:ectoplasm"
}
},
"result": {
"item": "minecraft:slime"
}
}
}
```
- `"format_version"` is already known.
- With `"recipe_shaped"` we define, that each ingredient has a set place in the crafting grid. There are some other types that can be used, you can find more information [here](/loot/recipes).
- Inside `"description"` we define the `"identifier"` of this recipe, which is the name of the recipe.
- `"tags"` is a list of benches (crafting table, furnace, etc) that are able to use this recipe. After version b1.16.100 it was possible to use custom benches, created by an addon.
- `"pattern"` defines the arrangement of the items inside the crafting grid. Each `#` represents the item that is set under `"key"`. In this case, the whole 3x3 grid has to be filled with `"wiki:ectoplasm"`, our own item. It is possible to define more items, just add an entry to `"key"` and set the key to a character, that you can use inside `"pattern"`.
- `"result"` contains an `"item"`, which is set to the item that will be the output of this recipe.
For more information on this topic, visit our page about [recipes](/loot/recipes)!
## What you have learned
:::tip What you have learned:
- How to create a loot table and define which items a mob is able to drop
- How to set the rules for a mob to spawn
- How to create new crafting recipes
:::
## Your progress so far
**What you've done:**
<Checklist>
- [x] Setup your pack
- [x] Create a custom item
- [x] Create a custom entity
- [x] Create the entity's loot, spawn rules, and a custom recipe
</Checklist>
Congratulations! you have finished the Guide and created your first Add-on. 🎉

261
docs/wiki/guide/project-setup-android.md Normal file
View File

@@ -0,0 +1,261 @@
---
title: Project Setup Android
category: Guide
description: How to setup your project on Android
mentions:
- Etanarvazac
- MedicalJewel105
- TheItsNameless
- ThomasOrs
hidden: true
---
## Tools
It is not easy to find good apps to make add-ons for android platform, but we tried our best and collected Google Play apps for you.
For development on Android, you'll need a combination of 3 applications.
1. A file manager that can create ZIP archives if your device is running Android 12 or newer.
2. A code editor (any text editor will work, but only code editors will show syntax highlights).
3. An image editor (no device comes with a editor that can go down to the pixels).
### File Managers
These file managers are known to have ZIP archiving and view-only access to the `Android/data` folder:
1. [**X-Plore**](https://play.google.com/store/apps/details?id=com.lonelycatgames.Xplore) - a powerful file manager with dual-pane tree view, a built-in text editor (not code), several file compression formats (ZIP, 7zip, RAR, etc.), and more. On rooted devices, X-Plore has edit access to `Android/data` and root directories.
2. [**Total Commander**](https://play.google.com/store/apps/details?id=com.ghisler.android.TotalCommander) - not as powerful out of the box compared to X-Plore, but contains some of the same features including dual pane, ZIP and RAR archives, and view-only access to `Android/data`. Total Commander has list view instead of tree and many other features that require plugins (apps from Google Play) to use.
### Code Editors
1. **Acode:** [Free version](https://play.google.com/store/apps/details?id=com.foxdebug.acodefree) comes with ads that can be toggled off without paying. Supports GitHub integration using a Personal Access Token, FTP/SFTP, syntax highlighting for over 100+ languages including JSON, tab-view for multi-file editing, dozens of themes, and more. This app is open source and does have a [paid version](https://play.google.com/store/apps/details?id=com.foxdebug.acode) that allows a much deeper theme customization.
:::info
Acode is the only powerful code editor actively being developed on Android at this time. Other editors are very limited or have been abandoned long enough to vanish from the Google Play store. If you know of a code application, you can contribute to this guide.
:::
### Image Editors
1. [**Pocket Paint**](https://play.google.com/store/apps/details?id=org.catrobat.paintroid) - lightweight editor with the bare minimum features needed for any add-on creation. This app is easy to use and allows importing other images over others. Saves in JPG (compressed), PNG (lossless, with transparency), and ORA (multi-layer images). This app is open source.
2. [**Pixly**](https://play.google.com/store/apps/details?id=com.meltinglogic.pixly&hl=en) - very lightweight, no ads or in app purchases. Plentiful tools and customizable brushes, ability to save palettes internally or externally.
3. [**Pixel Art editor**](https://play.google.com/store/apps/details?id=net.spc.app.pixelarteditor&hl=en) - a simple lightweight app. Would be the best if you need just to draw some texture-placeholder.
## Your Workspace
:::tip
In this version of the guide, "BP" refers to your behaviour pack folder and "RP" refers to your resource pack folder in your workspace. For locations in files or directories, `../<current location>` indicates "From last location" followed by the added space (e.g.: `/one/two/three/file.txt` would be shortened to `../three/file.txt`)
If your device is rooted, you can follow the main project setup using the `/Android/data/com.mojang.minecraftpe/files/games/com.mojang` development behaviour and resource pack folders directly. Otherwise, follow the steps below.
:::
Before we begin, you need a workspace. Using your file manager, navigate to your Internal Storage (In most cases, it's `/`. In others, the full path (e.g.: `/storage/emulated/0/`) is displayed. Both are acceptable.) and create a folder that will contain your packs. For this example, our full directory is `/Minecraft Packs/MyFirstAddon`. From there, you'll need one folder for both your behaviour and resource packs (e.g.: `../MyFirstAddon/addonBP` and `../MyFirstAddon/addonRP`).
Now that you have the workplace setup, code editors should have a way for you to open a folder as a workplace. In this guide, we'll be walking through Acode.
1. Open Acode.
2. Tap the file browser button (3 bars in the top-left), followed by "Open folder"
3. Tap "Add a storage", followed by "select folder"
4. This should have opened your device's file browser. Navigate to the _main_ folder for your projects (for us, `/Minecraft Packs`) then tap "Use this folder". If your device asked you to allow Acode access, tap "Allow".
5. You should be back in Acode now. Tap "OK" and your folder should now be in the list. Tap on it and then "Select Folder" on the bottom of the screen.
6. Now when you open the file browser (3 bars in top-left), you should see your folder in the list. You now have quick access to your addon's behaviour and resource pack folders. The file browser uses tree view to display your active workspace.
:::tip
You can create new files and folders inside your packs from the file browser by tapping and holding on the folder you want to create the item in.
:::
## BP & RP Manifests
:::warning
From here on out, all files and folders have very specific names unless otherwise noted. Wrongly named files and/or folders are a common reason of an error. Please ensure you're checking your work carefully in accordance to the examples provided. If a file or folder mentioned has not yet been created, please create it in it's appropriate directory.
When creating a new file in a file manager or some text or code applications, the `.txt` extension is added automatically to the end of the file name. To ensure our files work as intended, be sure to remove `.txt`. Like names, the wrong file extension is also a common reason of an error. If you're using Acode, you'll notice `untitled.txt` is completely highlighted instead of just `untitled`. This is a common practice for naming programming language files.
:::
The manifest file is the file Minecraft uses to identify your packs. Every pack has one (and only one) manifest. A folder with a correctly formatted manifest will show up in Minecraft. Before we begin adding content, we will ensure our "minimal" pack is visible. Manifests are written in the `JSON` programming language. If you're unfamiliar with JSON, you can learn more about it [here](/guide/understanding-json).
Create a new text file in your addon's behaviour pack folder called `manifest.json`. To begin, copy and paste the following code into the `manifest.json` file. A full breakdown of the manifest file is provided after creating these files.
<codeHeader>BP/manifest.json</codeHeader>
```json
{
"format_version": 2,
"header": {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
"version": [0, 0, 1],
"min_engine_version": [1, 16, 0]
},
"modules": [
{
"type": "data",
"uuid": "...",
"version": [0, 0, 1]
}
]
}
```
Now create another `manifest.json` file in your addon's resource pack folder. Again, copy and paste the following code inside the new file.
<codeHeader>RP/manifest.json</codeHeader>
```json
{
"format_version": 2,
"header" {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
"version": [0, 0, 1],
"min_engine_version": [1, 16, 0]
},
"modules": [
{
"type": "resources",
"uuid": "...",
"version": [0, 0, 1]
}
]
}
```
## Manifest Breakdown
- `format_version` defines the version the syntax your manifest is written in. Version 2 is the most recent stable version. Always use this version.
- `name` is name of your pack. We will be defining the this in "code form" later so they can easily be translated into other languages, should you create a pack with multiple languages.
- `description` is a short description about your pack that will show up under the `name` in-game. This will also be defined later in "code form".
- `uuid` is required to help identify your pack from other packs and will have a breakdown of it's own below. Once explained, you'll need to replace all of the `...` with them.
- `version` is literally the version of your addon. Upon completing your addon, you can always change this to `[1, 0, 0]`. However, it'll be easier to use the hotfix spot while making your changes on mobile.
- `min_engine_version` tells Minecraft what the minimum version it needs to be in order for your pack to work. For example, if your pack has a crafting recipe that involves concrete, your pack can't run on Minecraft 1.5 because concrete doesn't exist in that version.
- Under `modules`, you have the `type` field. This tells Minecraft what your pack is. So `data` in your BP tells the game that pack is a behaviour pack and `resources` in your RP tells the game that pack is a resource pack.
## UUID Breakdown
A UUID, or **U**niversally **U**nique **ID**entifier, both identifies your pack for other programs (Minecraft, for example) and separates your pack from someone else's pack for the program it's for. A version 4 UUID (UUID-4) is usually in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` and made of a random string of letters and numbers. For example: `5c830391-0937-44d6-9774-406de66b6984`.
You should **NEVER** use the same UUID twice! Use the [Online UUID Generator Tool](https://www.uuidgenerator.net/version4) to generate the UUID's needed for your manifest files. Every manifest file uses two different UUID's. So to ensure your packs will work correctly, get 4 different UUID's to replace all of the `...` in both manifests. When finished, each UUID entry should look similar like this: `"uuid": "5c830391-0937-44d6-9774-406de66b6984`
## Pack Icon
Notice how other packs have a icon? It's a image file which can quickly identify how your addon will appear in-game. Got a low-resolution square image as a PNG? You can use it! Otherwise, you can use this example icon.
<WikiImage src="/assets/images/guide/project-setup/pack_icon.png" alt="Pack Icon" pixelated/>
<BButton
link="/assets/images/guide/project-setup/pack_icon.png" download
color=default
>Download Image</BButton>
You must place a copy of your desired image in both the behaviour and resource packs. In order for the image to be read correctly, the name must be `pack_icon.png`.
## Language Files
Remember when we said we'll define the pack name and description in code form earlier? Now is that time as it's the last thing we need to do to setup your addon. You will need to create 4 new files and 2 new folders (2 files and 1 folder for each pack). You can You can learn more about how Minecraft handles localization [here](/concepts/text-and-translations). You can also format your definitions using the `§` symbol. You can view a list of colors and formats [here](https://htmlcolorcodes.com/minecraft-color-codes/). If you use any formatting, make sure you `§r`eset when changing formats: `§kl My pack l` will render "My pack" unreadable whereas `§kl §rMy pack §kl` can be read properly.
<codeHeader>BP/texts/en_US.lang</codeHeader>
```
pack.name=§2My §lFIRST §r§2Addon's Behaviour Pack!
pack.description=This addon is made by a Wiki Contributor!
```
<codeHeader>BP/texts/languages.json</codeHeader>
```json
["en_US"]
```
<codeHeader>RP/texts/en_US.lang</codeHeader>
```
pack.name=§2My §lFIRST §r§2Addon's Resource Pack!
pack.description=This addon is made by a Wiki Contributor!
```
<codeHeader>RP/texts/languages.json</codeHeader>
```json
["en_US"]
```
## Importing Your Addon
Now that your addon has all of the required content, we need to import it to Minecraft. To do this, we need to create a file with the extension `.mcaddon`.
1. Open your preferred file manager and navigate to the folder containing your behaviour and resource packs.
2. Using multi-select, select both packs and create a ZIP file.
3. When asked for the name of the file, ensure that `.zip` is changed to `.mcaddon`.
![](/assets/images/guide/project-setup-android/zip-addon.png)
4. When your file manager finishes, it should be a `MCADDON` file with Minecraft as it's icon. Tapping on this file should launch Minecraft.
If done correctly, Minecraft will display a banner for both packs. First is `Importing...`. After should be `Successfully imported "<your pack name>"`. You can also go to `Settings > Storage` if you don't see the import messages to verify your packs were imported. If you do not see either pack, check out our [troubleshooting guide](/guide/troubleshooting).
## Turn on Content Log
:::warning
Content log is the most useful tool you have for debugging your addons. Please do not skip this step.
:::
![](/assets/images/guide/content_log.png)
Content Log is an extremely important debugging tool, which you should always have on.
Turn on both content log settings in `settings > creator`. This will show you any errors in your add-on when you enter a world with it applied. You can also open the content log GUI in-game by pressing `ctrl+h`. Learn more about the content log [here](/guide/troubleshooting).
## Creating your testing world
Now we create a world to test your new add-on!
1. Click "**Create new world**";
2. Ensure that the following settings are set.
![](/assets/images/guide/project-setup/settings_1.png)
![](/assets/images/guide/project-setup/settings_2.png)
3. Now activate your behavior pack, and your resource pack. You can do this by selecting the packs, and clicking 'apply'.
4. Now click '**Create**'!
## Final Notes
**Here is how your project should look, after completing this page:**
Remember that in future, we will represent `com.mojang/development_behavior_packs/guide_RP/` as `RP`, and `com.mojang/development_behavior_packs/guide_BP/` as `BP`.
<FolderView :paths="[
'com.mojang/development_resource_packs/guide_RP/manifest.json',
'com.mojang/development_resource_packs/guide_RP/pack_icon.png',
'com.mojang/development_resource_packs/guide_RP/texts/en_US.lang',
'com.mojang/development_resource_packs/guide_RP/texts/languages.json',
'com.mojang/development_behavior_packs/guide_BP/manifest.json',
'com.mojang/development_behavior_packs/guide_BP/pack_icon.png',
'com.mojang/development_behavior_packs/guide_BP/texts/en_US.lang',
'com.mojang/development_behavior_packs/guide_BP/texts/languages.json',
]"></FolderView>
## What you have learned
:::tip What you have learned:
- What and where your `com.mojang` folder is and what it contains
- How to setup your mobile workspace
- What a `manifest.json` file is
- What are UUID's and how to use them
- How to create icons for your addons
- What a `.lang` file is
:::
## Your progress so far
<Checklist>
- [x] Setup your pack
- [ ] Create a custom item
- [ ] Create a custom entity
- [ ] Create a custom block
</Checklist>

300
docs/wiki/guide/project-setup.md Normal file
View File

@@ -0,0 +1,300 @@
---
title: Project Setup
category: Guide
description: How to setup your project
nav_order: 4
prefix: '4. '
mentions:
- SirLich
- sovledDev
- Joelant05
- Dreamedc2015
- BlueFrog130
- sermah
- cda94581
- MedicalJewel105
- TheItsNameless
- ThijsHankelMC
- TheHyperWhale
- stirante
- ChibiMango
- Etanarvazac
- retr0cube
- ThomasOrs
- lescx
---
## The com.mojang folder
The `com.mojang` folder is a special folder where Minecraft stores data (Addons, Worlds, Player info...). Minecraft understands this location, and all files we access or create will be placed somewhere in this folder!
You should create a shortcut to the `com.mojang` folder on your Desktop or on your mobile device, so you can easily access it at any time. The exact location of the `com.mojang` folder will depend on your device OS.
### Windows
_Tip: You can type %appdata% into the searchbar to jump directly into the 'C:\Users\USERNAME\AppData\' folder._
`C:\Users\USERNAME\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang`
### Android
Android 11 or older: `Phone > games > com.mojang`
Android 12 and newer: `Phone > Android > data > com.mojang.minecraftpe > files > games > com.mojang`
### ChromeOS
Before you can see the `com.mojang` in your files, make sure to change the `File Storage Location` to `External` in your Minecraft Settings:
- Go to `Minecraft Settings`.
- Navigate to `Settings > General > Storage`.
- Change the `File Storage Location` to `External`.
After that you can access the `com.mojang` folder in your Android Subsystem:
`My Files > Play Files > Android > data > com.mojang.minecraftpe > files > games > com.mojang`
### iOS
`My iDevice > Minecraft > games > com.mojang`
### Development Packs
We will develop our addon in `development_behavior_packs` and `development_resource_packs`. When you make changes within these folders, you can _exit and re-enter a world with the packs applied_, to automatically reload the content. This allows you to quickly test your addon without reloading Minecraft.
`resource_packs` and `behavior_packs` on the other hand contain stable addons, including those imported via `.mcpack`. We can ignore these folders for now.
## Your Workspace
:::tip
Project setup is different for android and other platforms. Consider looking into our guide for android platforms.
:::
<BButton
link="./project-setup-android"
color=blue
>Android guide</BButton>
:::tip
In this guide, BP refers to the folder you created in `development_behavior_packs` ("the behavior pack"), and RP refers to the folder you created in `development_resource_packs` ("the resource pack")
:::
First of all, you will need to create the proper folders in suitable locations and set up your workspace.
_The remainder of this guide assumes you are using VSCode. You may also follow along with other editors._
Let's create your first add-on workspace in Visual Studio Code now.
1. Open VSCode (_Visual Studio Code, the code editor_)
2. Create a folder named "`your_pack_name_RP`" in `development_resource_packs`. **I'll refer to this folder as `RP`**
3. Create a folder "`your_pack_name_BP`" in `development_behavior_packs`. **I'll refer to this folder as `BP`**.
4. Go to `File > Add folder to workspace...` and choose `BP`. Do the same with `RP`.
5. Press `File > Save Workspace as...` to save the workspace file to your Desktop. Whenever you're working on your addon, all you have to do is open the workspace by double-clicking, and you will get quick access to both BP and RP folders.
## BP Manifest
:::tip
In this guide, you will often be instructed to create files with specific names, placed in specific folders. If the folder doesn't exist yet, please create it!
:::
:::warning
Wrongly named files/folders is a common source of errors. Please check your work carefully against the examples.
:::
The manifest is a file that identifies your pack to Minecraft. Every pack has one manifest. A folder with a correctly formatted manifest will show up in Minecraft, and we consider this the "minimal" pack before we can add additional content.
Manifest files are written in `json`. If this isn't familiar to you, you can learn more about json [here](/understanding-json).
First, create a new file in your BP folder by right-clicking on the folder and selecting `New File`. Call the file `manifest.json`. To begin, you can copy paste the following code into the file.
<CodeHeader>BP/manifest.json</CodeHeader>
```json
{
"format_version": 2,
"header": {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
"version": [1, 0, 0],
"min_engine_version": [1, 16, 0]
},
"modules": [
{
"type": "data",
"uuid": "...",
"version": [1, 0, 0]
}
]
}
```
### Manifest Explained
- "`format_version`" defines what version of manifest syntax you are using. Version 2 is the most recent stable version; use it.
- "`name`" is the name of your behavior pack. "`description`" will show up under it in-game. We are defining these files in "code form" so we can translate them later into other languages. For more information about localization, look [here](/concepts/text-and-translations).
- The "`UUID`" field is **essential**, and will be discussed in more detail below.
- "`version`" defines the version of your add-on. When you import an add-on with a newer version on a device with an older version installed, the more recent version will overwrite the older one. You don't need to change the version if you have the add-on in `development_*_packs` folders and only use them on private worlds.
- "`min_engine_version`" defines the minimum Minecraft client version that'll be able to read your add-on.
- In "`modules`", the "`type`" is defined to be "`data`". This makes your pack a _Behavior Pack_.
### UUID Explained
A UUID (_Universally Unique Identifier_) identifies your pack for other programs (in this case, Minecraft) to read. It looks something like this: `5c830391-0937-44d6-9774-406de66b6984`
**NEVER USE THE SAME UUID TWICE.** You can generate your own UUIDs [here](https://www.uuidgenerator.net/version4) or, if you use VSCode, you can install [this](https://marketplace.visualstudio.com/items?itemName=netcorext.uuid-generator) extension. Many other tools like _bridge._ generate UUIDS automatically. Every manifest file uses two different UUIDs.
To ensure that your add-on will work correctly you should generate two new UUID's which you will paste into the BP `manifest.json` file, at each `"..."`. When you are finished, it should look something like this:
`"uuid": "5c830391-0937-44d6-9774-406de66b6984"`
## RP Manifest
The next step is to create the `manifest.json` for the RP. The format for a resource-pack manifest is nearly identical to a BP manifests except that the `type` is `resources`, which marks the pack as a _Resource Pack_.
Copy the following code into your newly created `RP/manifest.json` and insert your own UUIDs.
<CodeHeader>RP/manifest.json</CodeHeader>
```json
{
"format_version": 2,
"header": {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
"version": [1, 0, 0],
"min_engine_version": [1, 16, 0]
},
"modules": [
{
"type": "resources",
"uuid": "...",
"version": [1, 0, 0]
}
]
}
```
## Pack Icon
The pack icon is an image file which identifies how your addon will look in-game. If you have a low-resolution square image, you can use it. Otherwise, download and use this example icon:
<WikiImage src="/assets/images/guide/project-setup/pack_icon.png" alt="Pack Icon" pixelated/>
<BButton
link="/assets/images/guide/project-setup/pack_icon.png" download
color=default
>Download Image</BButton>
You should place a copy of your desired image into both the RP and the BP. The image needs to be named `pack_icon.png`
## Language Files
The last thing to do is setup language support for your addon. You will need to create a language file for both the RP and the BP. You can learn more about how Minecraft handles localization [here](/concepts/text-and-translations).
<CodeHeader>RP/texts/en_US.lang</CodeHeader>
```json
pack.name=Wiki Resource Pack
pack.description=A Ghostly Guide
```
<CodeHeader>BP/texts/en_US.lang</CodeHeader>
```json
pack.name=Wiki Behavior Pack
pack.description=A Ghostly Guide
```
<CodeHeader>RP/texts/languages.json</CodeHeader>
```json
["en_US"]
```
<CodeHeader>BP/texts/languages.json</CodeHeader>
```json
["en_US"]
```
## Checking your Work
If you have done everything correctly, your packs should show up in Minecraft now! If you don't see your pack, you should follow the [troubleshooting guide.](/troubleshooting)
![](/assets/images/guide/project-setup/active_pack.png)
## Turn on Content Log
:::warning
Content log is the most useful tool you have for debugging your addons. Please do not skip this step.
:::
![](/assets/images/guide/content_log.png)
Content Log is an extremely important debugging tool, which you should always have on.
Turn on both content log settings in `settings > creator`. This will show you any errors in your add-on when you enter a world with it applied. You can open the content log GUI in-game by pressing `ctrl+h` or by pressing `Content Log History` in the creator settings panel. Learn more about the content log [here](/guide/troubleshooting).
## Creating your testing world
Now we create a world to test your new add-on!
1. Click "**Create new world**";
2. Ensure that the following settings are set.
![](/assets/images/guide/project-setup/settings_1.png)
![](/assets/images/guide/project-setup/settings_2.png)
3. Now activate your behavior pack, and your resource pack. You can do this by selecting the packs, and clicking 'apply'.
4. Now click '**Create**'!
---
## Your progress so far
**Here is how your project should look, after completing this page:**
Remember that in future, we will represent `com.mojang/development_behavior_packs/guide_RP/` as `RP`, and `com.mojang/development_behavior_packs/guide_BP/` as `BP`.
<FolderView :paths="[
'com.mojang/development_resource_packs/guide_RP/manifest.json',
'com.mojang/development_resource_packs/guide_RP/pack_icon.png',
'com.mojang/development_resource_packs/guide_RP/texts/en_US.lang',
'com.mojang/development_resource_packs/guide_RP/texts/languages.json',
'com.mojang/development_behavior_packs/guide_BP/manifest.json',
'com.mojang/development_behavior_packs/guide_BP/pack_icon.png',
'com.mojang/development_behavior_packs/guide_BP/texts/en_US.lang',
'com.mojang/development_behavior_packs/guide_BP/texts/languages.json',
]"></FolderView>
## What you have learned
:::tip What you have learned:
- What the com.mojang folder is, where it is and what folders it contains
- How to setup your workspace
- What a `manifest.json` file is
- How to use UUIDs
- How to create an icon for your addon
- What a `.lang` file is
:::
## Your progress so far
<Checklist>
- [x] Setup your pack
- [ ] Create a custom item
- [ ] Create a custom entity
- [ ] Create the entity's loot, spawn rules and a custom recipe
</Checklist>

179
docs/wiki/guide/software-preparation.md Normal file
View File

@@ -0,0 +1,179 @@
---
title: Software and preparation
category: Guide
description: How to setup your developement environment
nav_order: 3
prefix: '3. '
mentions:
- SirLich
- Dreamedc2015
- sermah
- cda94581
- Joelant05
- MedicalJewel105
- TheItsNameless
- TheDoctor15
- ChibiMango
- profeplaysminecraft
- solvedDev
- retr0cube
- SmokeyStack
- ThomasOrs
---
Before you can start creating addons, you first have to install the required tools and applications. While development will be easiest on Windows 10, we have provided mobile alternatives for both Android and iOS, where applicable.
## Download Minecraft Bedrock Edition
- [Windows 10](https://www.microsoft.com/en-us/p/minecraft-for-windows-10/9nblggh2jhxj?activetab=pivot:overviewtab)
- [Android](https://play.google.com/store/apps/details?id=com.mojang.minecraftpe&hl=en)
- [iOS](https://apps.apple.com/us/app/minecraft/id479516143)
- [Run MC on Linux](https://discord.gg/VJTZ3KaTx6)
## Picking an Editor
Addons can be created using any text editor, however it's much more comfortable to work in a dedicated editor. A good editor can give you code-completion, error-detection, and in-editor documentation.
There are strong opinions about the best editor for beginners, but generally speaking you cannot go wrong selecting either VSCode, or bridge. If you are mobile, you will need to use a mobile alternative.
### VSCode
VSCode is a general purpose text-editor and IDE. With VSCode, you will be able to edit your addons in plain-text, guided along by a powerful array of extensions and addons. VSCode is a great option for programmers and advanced users.
[⚙️Install VSCode](https://code.visualstudio.com/)
<Spoiler title="Configuring VSCode">
Many packages exist for VSCode that make editing addons easier:
- [Blockception's Minecraft Bedrock Development](https://marketplace.visualstudio.com/items?itemName=BlockceptionLtd.blockceptionvscodeminecraftbedrockdevelopmentextension)
- [.mcfunction support](https://marketplace.visualstudio.com/items?itemName=arcensoth.language-mcfunction)
- [.lang support](https://marketplace.visualstudio.com/items?itemName=zz5840.minecraft-lang-colorizer)
- [Bedrock Definitions](https://marketplace.visualstudio.com/items?itemName=destruc7i0n.vscode-bedrock-definitions)
- [Prettify-json](https://marketplace.visualstudio.com/items?itemName=mohsen1.prettify-json)
- [Spell Checker (for writing wiki)](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
- [Snowstorm Particle Editor](https://marketplace.visualstudio.com/items?itemName=JannisX11.snowstorm)
- [UUID Generator](https://marketplace.visualstudio.com/items?itemName=netcorext.uuid-generator)
</Spoiler>
### bridge.
[bridge.](https://bridge-core.app/) is a light-weight, dedicated IDE for Minecraft addons. It features [innovative features](https://bridge-core.app/guide/features/) such as [entity and block previews](https://bridge-core.app/guide/features/index.html#file-previews), [rich auto-completions and file validations](https://bridge-core.app/guide/features/index.html#auto-completions-and-validation) and [advanced file creation with presets](https://bridge-core.app/guide/features/index.html#advanced-file-creation).
bridge. includes a regular text editor for experienced addon creators and a tree editor to make it easy for beginners to get started with editing JSON files.
#### Next Steps
- [Read more on why you should use bridge.](https://bridge-core.app/guide/why-bridge)
- [Read our guide on getting started with bridge.](https://bridge-core.app/guide/index)
- [Try out bridge. online](https://editor.bridge-core.app/)
### Mobile Editors
#### Android
- [ACode Editor](https://play.google.com/store/apps/details?id=com.foxdebug.acodefree)
- [bridge. v2](https://bridge-core.app/)
#### iOS
- [Kodex](https://apps.apple.com/us/app/kodex/id1038574481)
- [bridge. v2](https://bridge-core.app/)
## Blockbench
- [Blockbench](https://blockbench.net/) is a 'boxy 3D model editor' typically used to create Minecraft models, textures and animations. Also provides a web-browser version which is compatible with mobile.
## Image Editors
When choosing an image editor, it is important to keep in mind that the traditional Minecraft style is composed of simple 16X16 pixelart. There are plenty of powerful and free art programs available for you to use. However, many of these programs have more tools than you will need for Minecraft graphical design and these tools require time to learn.
:::tip
Choose a program that feels comfortable and easy for you to use. Many Addon creators use different art programs for different tasks. (Example: One might use paint․net for most of the art, and piskel for Minecraft block animations). Choose what works best for you!
:::
### Krita
Krita is a powerful open-source art programed with the goal of giving free powerful digital art tools to artists. Krita has more than enough features to cover your Minecraft needs and works on a MAC or PC.
**+ Pros:** Plenty of features including a pixel brush with an intuitive user interface.
**- Cons:** Requires a little time to become familar with the tools.
[Download Krita](https://krita.org/en/)
### GIMP
Gimp is similar to Krita in that it is a free and open source digital art program that has a vast arrays of tools. Where Krita focuses more on illustration, GIMP focuses more on image manipulation (think Photoshop). Gimp also works on MAC or PC.
**+ Pros:** GIMP has more than enough tools for editing Minecraft art
**- Cons:** The interface is not intuitive. Even though GIMP is powerful, it requires a steep learning curve.
[Download Gimp](https://www.gimp.org/)
### Paint․net
Paint․net is a simple yet powerful image editing and art software. Paint․net may not have a vast array of tools like Krita and GIMP, but it does offer simplicity and ease of use.
**+ Pros:** Easy to use and learn.
**- Cons:** Only works on Windows.
[Download Paint.net](https://www.getpaint.net)
### Pixilart
Pixilart is a web-based pixel art software. It is extremely simple to use since it is focused on pixel art. It also has a powerful resize option that may come in handy, so that you can resize your art without losing the pixelart details.
**+ Pros:** Easy to use and learn. Curated specifically for pixel art.
**- Cons:** Must have internet connection. May be missing tools you want.
[Use Pixilart](https://www.pixilart.com/)
### Piskel
Piskel is a web-based pixel art software with a focus of making pixelated sprites (or video game character animations). This tool, similar to Pixilart, is simple to use. This is also a great tool for making flipbooks (Minecraft block or skin animations).
**+ Pros:** Easy to use and learn. Perfect for flipbook animations
**- Cons:** Must have internet connection. Only offers the most basic tools.
[Download Piskel](https://www.piskelapp.com/)
### Libresprite
LibreSprite is a free and open source program for creating and animating your sprites. Based on the last GPLv2 commit of aseprite.
**+ Pros**: Basic & easy to use, customizable and curated for pixel artists.
**- Cons**: May not work on Mac, maintained only by a small community.
## Additional Materials
:::tip
This guide will walk you through the first stages of addon development, but it is not comprehensive! To learn more about addons, you will have to use and reference other sources of information, which we will link to here.
:::
### Join the Discord
The best place to get help with this guide is to join the [discord server](/discord).
### Vanilla Packs
Minecraft's vanilla files are a good source of reference material. You should download these packs, and store them on a convenient location on your computer. When you need an example of an item, or entity, or animation, you can reference these files for inspiration.
- [Vanilla packs](https://github.com/Mojang/bedrock-samples/releases)
### Documentation
There are many good sources of Addon documentation. Familiarize yourself with all of them, and consider bookmarking them.
- [bedrock.dev](https://bedrock.dev/): Reference documentation.
- [wiki.bedrock.dev](https://wiki.bedrock.dev/): Tutorials and guides.
- [MS Docs](https://docs.microsoft.com/en-us/minecraft/creator/): The official microsoft creator portal for addons.
### Troubleshooting and Additional Help
- If the json format is very tricky for you, consider reading the [understanding-json guide](/guide/understanding-json).
- If you get stuck with an odd error, consider reading the [troubleshooting guide](/guide/troubleshooting).
- If you still haven't found a solution, feel free to join our [Discord server](/discord).
### Additional Links and Tools
- You can explore additional tools [here](/meta/useful-links).
## Your progress so far
<Checklist>
- [x] Installed the necessary software
- [x] Downloaded the Vanilla Example files
- [ ] Locate your `com.mojang` folder and create your addon's workspace.
- [ ] Create the manifest and pack icon for your first addon
</Checklist>

81
docs/wiki/guide/troubleshooting.md Normal file
View File

@@ -0,0 +1,81 @@
---
title: Troubleshooting
category: Extra
description: A simple troubleshooting guide
prefix: 'c. '
nav_order: 3
tags:
- help
mentions:
- SirLich
- Joelant05
- destruc7ion
- Dreamedc2015
- MedicalJewel105
- Luthorius
- SmokeyStack
---
Creating Addons for Bedrock Minecraft is a relatively straightforward process _once you get the hang of it_. The first time is usually a frustrating, bug-prone process. This document contains some tips and tricks for fixing those dastardly bugs, as well as best practice information.
Please read the whole page, before jumping into troubleshooting tips for a specific domain.
## Reload
First, you should always reload Minecraft. That means fully closing the game and then reopening it. This can catch many errors, especially those related to assets that are accessed via a filepath, such as textures or loot tables.
## The Environment
The best way to prevent nasty bugs is by working in the right environment. You should review the [software preparation document](/guide/software-preparation) for editor recommendations. The most important part is getting a JSON-linter, ([or using an online json-linter](https://jsonlint.com/)), and storing your packs in `development_behavior_packs` and `development_resource_packs`.
If you have your addons in the normal folders, you can run into "pack caching" issues, where you edit the files in one location, but the game is still using the old files.
## Content Log
:::warning Use the Content Log!
Content log is the best tool you have for debugging your addons. Please don't skip this step!
:::
::: tip
Errors are not cleared between runs, so the errors you see in the content log may be _old_ errors from prior runs.
:::
The 'Content Log' is a list of issues found in your pack. Minecraft will generate this list every time your load your world. It can catch issues such as:
- Wrong texture path
- Wrong spelled component
- Incorrect json structure
Content log can be turned on in in `Settings > Creator`. The content log will show in-game on load up, and if more errors occur during gameplay.
![](/assets/images/guide/content_log.png)
### Content Log File
The content log is saved in `.txt` format inside your files:
- *Windows*: `C:\Users\USERNAME\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\logs`
- *Android:* `/storage/emulated/0/Android/data/com.mojang.minecraftpe/files/games/com.mojang/logs`
## Using Vanilla Resources
You should download the vanilla resource and behavior pack. You can find the vanilla resource and behavior pack [here](https://www.minecraft.net/en-us/addons/). You can compare against the vanilla files if you have any issues!
## JSON-Schemas
JSON-Schemas are a valuable tool for file validation. You can learn more about JSON-Schemas [here](/meta/using-schemas).
# Troubleshooting your addon!
## Entities
<BButton link="/entities/troubleshooting-entities"> Troubleshoot your entities.</BButton>
## Items
<BButton link="/items/troubleshooting-items"> Troubleshoot your items.</BButton>
## Blocks
<BButton link="/blocks/troubleshooting-blocks"> Troubleshoot your blocks.</BButton>

151
docs/wiki/guide/understanding-json.md Normal file
View File

@@ -0,0 +1,151 @@
---
title: Understanding JSON
category: Extra
description: A first peek into JSON
nav_order: 1
prefix: 'a. '
mentions:
- SirLich
- solvedDev
- Joelant05
- Dreamedc2015
- sermah
- cda94581
---
::: tip
This is an appendix page. You can start the guide from the beginning [here](/guide/index).
:::
JSON is a simple format for writing text files, in a way that is understandable to both Humans and Computers. Bedrock uses .json files as the "language" of Add-Ons, so you will need a solid understand of how to read and write json! If you have never heard of JSON before, you are encouraged to read through [this tutorial](https://www.digitalocean.com/community/tutorials/an-introduction-to-json). It will teach you everything you need to know about writing valid JSON files.
## Valid JSON
The important thing to remember when writing JSON is that it must be _completely error free_, or it won't work at all. Even one wrong character, or one extra comma will cause the entire file to fail. For this reason, it's super important you write valid JSON.
We can use an online tool called [json lint](https://jsonlint.com/) to tell us whether our JSON is valid. Simply paste your code into the website, and press `Validate JSON`. You will get a response indicating whether your code is correct or not, as well as the location and type of any errors.
## Data Structures
In JSON, data can be written in a number of formats. Each format is specialized for the kind of data it wants to represent. Here are the structures we have available:
| Name | Example | Explanation |
| ------ | -------- | -------------------------------------- |
| String | "hello!" | Words, or characters. Requires quotes. |
| Int | 15 | A number. No quotes. |
| Float | 1.2 | A fractional number. No quotes. |
| Bool | true | Either true or false. No quotes. |
And now, in .json format:
```json
{
"my_string": "hello!",
"my_int": 15,
"my_float": 1.2,
"my_bool": true
}
```
In addition to these simple structures, we also have access to two special structures. Special structures are used to *nest* other data together.
### Arrays
Arrays are written as two square brackets `[]`. They represent a _list_. We can put _other data structures_ inside of the list. Each _element_ of the list should be separated by a comma.
Some examples:
| Structure | Comment |
| --------------- | ------------------------------------- |
| [1, 2, 3] | A list of integers. |
| ["Red", "blue"] | A list of strings. Notice the quotes! |
And now, in .json format:
```json
{
"my_ints": [1, 2, 3],
"my_strings": ["Red", "blue"]
}
```
### Objects
Objects are written as two curly-brackets `{}`. Objects are a special syntax which contains _named_ data structures. The name is called a `key`, and the structure is called a `value`. The examples earlier in this page was a *dictionary* containing examples of the other data types.
This key-value syntax looks like this: `"<key>": <any structure>`. Notice the quotes around the key, and the colon.
Here is an example of an object, which contains a few _key-value-pairs_.
<CodeHeader></CodeHeader>
```json
{
"a_list_of_integers": [1, 2, 3],
"is_json_cool": true
}
```
We need to separate each key-value pair with a comma.
We call the key-value pairs of an object as its _child_ or as being _inside_ the object.
## JSON Structure
In Minecraft, JSON files always begin with an _object_, which you can remember is two curly brackets:`{}`. We call this the _top level object_. We write our code _inside_ of this object, in the form of key-value pairs.
Here is an example of a simple json file, used for Minecraft addons:
<CodeHeader></CodeHeader>
```json
{
"format_version": "1.12.0",
"animations": {
"animation.car.wheel_spin": {
"loop": true,
"animation_length": 1.0,
"bones": {
"front_wheels": {
"rotation": ["q.modified_distance_moved * -30", 0, 0]
},
"back_wheels": {
"rotation": ["q.modified_distance_moved * -30", 0, 0]
}
}
}
}
}
```
Take a careful look at the format. You will see that the entire structure is built out the data-structures that we have already learned. If you want to practice your json skills, try to answer these questions:
- How many keys are there in the _top level object_. Can you name them?
- What is the value of `format_version`?
- What kind of data is stored in the `"loop"` key? (string, boolean, etc)
## Troubleshooting Examples
Here are a few examples, to help you understand feedback you might recieve on the discord or online. We tend to use technical jargon when talking about errors in JSON, so hopefully this section helps familizrize you with the terms:
---
You wrote: `"format_version": 1.12`
They said: "_The value for format_version is the wrong type. It should be a string._
Remember that `type` means one of the structures: `String`, `Int`, `Float`, `Array` or `Object`. If we examine our code, we will see that we put `format_version` to a `Float`, instead of a `String`. We can fix this problem by adding quotes around the `"1.12"`.
---
You wrote: `[1 2 5 6]`
They said: "_Your array is missing commas._"
Remember that array elements need to be separated by commas. Your array should look like this: `[1, 2, 5, 6]`
---
They said: _"You accidentally put the format version inside your description. It should go outside at the top level_".
This means that the key-value pair for `"format_version"` as a _child_ of the description. You should copy/paste the key-value pair out from the description object, and place it at the top level.