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

52
docs/wiki/nbt/experimental-education-edition.md Normal file
View File

@@ -0,0 +1,52 @@
---
title: Experiments in Education Edition
category: Tutorials
mentions:
- Fabrimat
- TheItsNameless
tags:
- easy
- Last updated for Version 1.18.32 (MEE)
---
[structure]: /assets/images/nbt/structure.png
[int]: /assets/images/nbt/int.png
[list]: /assets/images/nbt/list.png
[compound]: /assets/images/nbt/compound.png
[string]: /assets/images/nbt/string.png
[byte]: /assets/images/nbt/byte.png
Education Edition is a variant of Bedrock Edition with some different features and limitations.
For security reasons it doesn't allow you to enable Experimental Features from the game.
## Editing NBT
::: warning
Always make a backup of your data before editing NBT files!
Experimental features may not be compatible with every device and can cause your world to behave in unexpected way.
:::
1. Extract the level.dat from your .mcworld, .mctemplate or com.mojang world folder.
2. Open the file with NBT editor (NBT Studio for example).
3. Select on the first node which is ![][structure] level.dat
4. Create a new compound tag called ![][compound] experiments
5. Select the new node and create a new ![][byte] byte with the name of the feature you need with a value of 1, which on 1.18.32 are:
- data_driven_biomes
- data_driven_items
- experimental_molang_features
- gametest
- spectator_mode
- upcoming_creator_features
- vanilla_experiments
- wild_update
![](/assets/images/nbt/experiments-education-edition/byte-add.png)
![](/assets/images/nbt/experiments-education-edition/experiments-file.png)
Finally, save the file and put it back in the world package or directory.
## Tips
Education Edition is usually one or two versions behind the classic Bedrock Edition, so you'll always know in advance which experimental features will be added to the stable gameplay and which will be modified or removed.
Try to add only features that will persist over time if you want to use that world in your classroom.

10
docs/wiki/nbt/index.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: NBT
categories:
- title: General
color: blue
- title: Tutorials
color: green
- title: NBT in Depth
color: red
---

127
docs/wiki/nbt/mcstructure.md Normal file
View File

@@ -0,0 +1,127 @@
---
title: .mcstructure
category: General
mentions:
- SirLich
- MedicalJewel105
- Misledwater79
- SmokeyStack
---
[int]: /assets/images/nbt/int.png
[list]: /assets/images/nbt/list.png
[compound]: /assets/images/nbt/compound.png
[string]: /assets/images/nbt/string.png
### Saving and Loading
The **Export** button creates `.mcstructure` files in a structure block. The files must be placed in a behavior pack to load them in-game with a load structure block. The path determines the structure identifier, which is typed into the structure block to load the structure.
**Examples:**
`BP/structures/house.mcstructure` → `mystructure:house`
`BP/structures/dungeon/entrance.mcstructure` → `dungeon:entrance`
`BP/structures/stuff/towers/diamond.mcstructure` → `stuff:towers/diamond`
The first subfolder defines the namespace, and subsequent folders define the path, ending with the structure file's name.
Note that any files directly in the `structures` folder are given the `mystructure` namespace. If a structure exists in the `structures` folder and shares a name with a structure in an explicit `mystructure` folder, the game produces the following content log warning:
```
[structure][warning]-There was a conflict loading a structure in the default namespace. A structure with the name <name> was found both in the root directory and the mystructure directory.
```
In this case, the file in the `mystructure` folder is the one that "wins," resulting in the file directly in the `structures` folder being ignored.
### File Format
`mcstructure` files are uncompressed [NBT files](https://wiki.vg/NBT#Specification). Like all Bedrock Edition NBT files, they are stored in little-endian format. The tag structure is as follows:
> ![Integer][int] `format_version`: Currently always set to `1`.
>
> ![List][list] `size`: List of three integers describing the size of the structure's bounds.
>
> > ![Integer][int] Size of the structure in the X direction.
> >
> > ![Integer][int] Size of the structure in the Y direction.
> >
> > ![Integer][int] Size of the structure in the Z direction.
>
> ![Compound][compound] `structure`: Actual data compound.
>
> > ![List][list] `block_indices`: List containing two sublists, one for each layer. These contain the blocks in the structure. Each block is stored as an integer index into the palette (see below). Proceeds in ZYX order from the lowest corner to the highest one. For example, if the structure size is `[2,3,4]`, then the 24 (product of the dimensions) values in each layer list represent the blocks located at `[(0,0,0), (0,0,1), (0,0,2), (0,0,3), (0,1,0), (0,1,1), (0,1,2), (0,1,3), (0,2,0), (0,2,1), (0,2,2), (0,2,3), (1,0,0), (1,0,1), (1,0,2), (1,0,3), (1,1,0), (1,1,1), (1,1,2), (1,1,3), (1,2,0), (1,2,1), (1,2,2), (1,2,3)]` relative to the origin. Index values equal to `-1` indicate no block, causing any existing block to remain upon loading. This occurs when structure voids are saved, and is the case for most blocks in the second layer. Both layers share the same palette.
> >
> > > ![List][list] of ![Integer][int] Indices for blocks in the primary layer.
> > >
> > > ![List][list] of ![Integer][int] Indices for blocks in the secondary layer. This layer is usually empty, except for water when the block here is waterlogged.
> >
> > ![List][list] of ![Compound][compound] `entities`: List of entities as NBT, stored exactly the same as entities in the world file itself. Tags like `Pos` and `UniqueID` are saved, but replaced upon loading.
> >
> > ![Compound][compound] `palette`: Contains multiple named palettes, presumably to support multiple variants of the same structure. However, currently, only `default` is saved and loaded.
> >
> > > ![Compound][compound] A single palette (currently only named `default`).
> > >
> > > > ![List][list] `block_palette`: List of block states. This list contains the ordered entries that the block indices are referring to.
> > > >
> > > > > ![Compound][compound] A single block state.
> > > > >
> > > > > > ![String][string] `name`: The block's identifier, such as `minecraft:planks`.
> > > > > > ![Compound][compound] `states`: The block's states as keys and values. Examples: `wood_type:"acacia"`, `bite_counter:3`, `open_bit:1b`. The values are the appropriate NBT type for the state: strings for enum values, integers for scalar numbers, and bytes for boolean values.
> > > > > > ![Integer][int] `version`: Compatibility versioning number for this block (currently `17959425` as of writing, in 1.19).
> > > >
> > > > ![Compound][compound] `block_position_data`: Contains additional data for individual blocks in the structure. Each key is an integer index into the flattened list of blocks inside of `block_indices`. Layer is unspecified as it is irrelevant.
> > > >
> > > > > ![Compound][compound] `<index>`: A single piece of additional block data, applied to the block at its index position.
> > > > >
> > > > > > ![Compound][compound] `block_entity_data`: Block entity data as NBT, stored the same as block entities in the world file itself. Position tags are saved, but replaced upon loading. No other objects seem to exist adjacent to this one at this time.
>
> ![List][list] `structure_world_origin`: List of three integers describing where in the world the structure was initially saved. Equal to the position of the saving structure block, plus its offset settings. This is used to determine where entities should be placed when loading. An entity's new absolute position is equal to its old position, minus these values, plus the origin of the structure's loading position.
>
> > ![Integer][int] Structure origin X position.
> > ![Integer][int] Structure origin Y position.
> > ![Integer][int] Structure origin Z position.
### What Happens If...
Results from testing to see what happens when modified structure files are loaded:
- If the dimensions in `size` exceed the vanilla save the limit of `64*256*64`, the structure can still be loaded just as expected.
- If the values in the block layer lists are not int tags, all values are treated as `0`.
- If a value in the block layer list is equal to or larger than the palette size or less than `-1`, an air block is placed.
- If the `default` palette is not present, loading the structure results in no blocks being placed.
- If any of the tags that have constant names are unspecified or are the wrong tag type, the structure fails to load with the following content log error:
```
[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | "<tag>" field, a required field, is missing from the structure.
```
- If `block_indices` does not contain exactly two values, the structure fails to load with the following content log error:
```
[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field should be an array with 2 arrays and instead we have <count> arrays.
```
- If the values inside of `block_indices` do not list tags, the structure fails to load with the following content log error:
```
[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field's first array is either missing or not a list.
```
- If the length of the two lists in `block_indices` are not equal, the structure fails to load with the following content log error:
```
[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field's arrays need to both be the same size.
```
- If the length of the two lists in `block_indices` does not equal the product of the structure's dimensions, the structure fails to load with the following content log error:
```
[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field should have as many elements as defined by the "size" field.
```
## NBT Editors
You can find download links for some NBT editors [here](/meta/useful-links#software-installed).
---
[Original Credit](https://gist.github.com/tryashtar/87ad9654305e5df686acab05cc4b6205)

88
docs/wiki/nbt/nbt-in-depth.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: About NBT (Named Binary Tag)
category: NBT in Depth
mentions:
- ConsoleTerm
- SmokeyStack
- ThomasOrs
tags:
- expert
---
NBT (Named Binary Tag) is a name for data encoding format at the binary level, you certainly know format JSON which is based on the text level. Therefore, we will be able to use the JSON format for some examples, you may also notice that minecraft itself uses JSON to represent NBT in commands such as java commands or simplified bedrock commands ( `/give`, `/replaceitem`). See [NBT Commands](/commands/nbt-commands) . In this article, we will show NBT in much more detail than you will ever expect, because what you could see in the commands is far from NBT, and we will show you how NBT works and how to read it, also how `Minecraft BE` itself uses it as well.
## NBT Tags and Data Types
NBT, just like JSON, has given types and knows how to read them, for example JSON knows that a compound object starts with the symbol `{` and ends with `}`, it also knows that when it has to read a string, the string always starts with the symbol ", this means that we want to learn to read and understand NBT so you need to know when a composite object starts, and how to read individual types.
Now let's look at the table of NBT tags for NBT types and how they are marked in NBT.
As it was said, NBT works on a binary level, so you need to know that the smallest data type is a byte, which is 8 bits in size. And individual types can contain multiple bytes, but they can never be 1/2 byte extra or less, not possible! : )
We also cannot say how the tags should be named, because everyone can call NBT tags differently, but they must always have the same binary base (`id`), id is represented by one byte.
| Name | Binary ID | Binary Size | Description |
| :----------------: | --------: | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Byte | 0x01 | 1 byte (8-bits) | One byte size type |
| Int16 (short) | 0x02 | 2 bytes (16-bits) | A two-byte type |
| Int32 (intiger) | 0x03 | 4 bytes (32-bits) | A four-byte type |
| Int64 (long) | 0x04 | 8 bytes (64-bits) | An eight-byte type |
| Float | 0x05 | 4 bytes (32-bits) | A four-byte type with regular decimal precision |
| Double | 0x06 | 8 bytes (64-bits) | An eight-byte type with higher decimal precision |
| String | 0x08 | Predefined | A string type that has a predefined size. Text uses UTF-8 encoding |
| List | 0x09 | Predefined | A list type with a predefined size and defining type for the elements in the list |
| Compoud | 0x0A (10) | Undefined | Type compound, the compound does not have a predefined size, so it is necessary to read the keys and values until we do not encounter the tag for ending the compound. |
| End of the Compoud | 0x00 | 0 bytes | This tag is not a type but only a tag and can only be used depending on the compound. It marks the end of a compound |
| Byte List | 0x07 | Predefined | List type of Byte and predefined size, not commonly used by Minecraft BE |
| Int List | 0x0B (11) | Predefined | List type of Int and predefined size, not commonly used by Minecraft BE |
| Long List | 0x0C (12) | Predefined | List type of Long and predefined size, not commonly used by Minecraft BE |
You may notice that there is no boolean value like in JSON and that means we will express true false values as 1 and 0 using Byte.
## How to read/write NBT tags
The same reading method applies to all numbers, read as many bytes as the number tag type is large, such as: Int16 (short) is 2 bytes in size, so I will read 2 bytes, but you need to know that Minecraft BE uses the [little-endian](#little-endian), unlike Java, it uses big-endian. [Little-endian](#little-endian) is a way to write or read bytes of numbers.
### Reading Types
Type is always one byte in size, so we read the type and find out what to read next for the tag.
### Reading Numbers
When reading a number, it is necessary to know what type of number we are reading, we can find out by reading the type *([Reading types](#reading-types))*. Then when we know what type of number we have to read, we read it, for example, if we know that we want type `3`, then we look in the table and we know that type 3 is a number of 4-bytes size, so we read 4 bytes. All numbers ***BE*** reads/writes with [little-endian](#little-endian) method.
### Reading Strings
When reading a string, you need to know its length in bytes, this string length is always written with Int16 (short) `2 bytes` ([how to read numbers](#reading-numbers)) before the string, i.e. first we read the number, then we read the number of bytes of the number we read before, after we know the bytes we can stuff them through UTF-8 encoding and we get text from them.
### Reading Lists
When reading a list, we must first read the list ([type](#reading-types)), whether this list contains numbers or other lists or strings, etc. So first we read the type of this list, then we read the [number](#reading-numbers) of elements which is written as an Int32 (int) number, so we read 4 bytes, now we know the type of our elements and their count, so we read this type as many times as we know from the readed number before. Reading the size of a list is not the same as reading the size of a string! Should read Int32 no Int16! This solution does not apply to `Byte-List, Int-List, Long-List`!
### Reading Compouds
Compound has all properties named so when reading an property it is always necessary to read its name as well. The procedure for reading Compoud is rather simple. First, we read the type, the type can be anything, but if it is equal to an empty byte, then it is the end of the compound and then we jut stop reading, but if the type is not equal to the Compoud Ending tag, then the significant type of the property that we will read. The read property is always followed by the name (key), which needs to be read as a [string](#reading-strings), and after the string is read, then we can read value.
## Minecraft BE NBT files
When reading Minecraft NBT files, it is always important to be careful if there is no Bedrock Header at the beginning of the file, see [Bedrock NBT Header](#bedrock-nbt-file-header), but not all MCBE NBT files contain this header, for example `.mcstructure` also does not contain a Bedrock NBT header, unlike `level.dat`.
You also need to pay attention to the root element in the file, i.e. the list or compoud,
The root element also looks like a property, so you need to read the name of this root property, although Bedrock does not use these names, so these names are empty, but they are there.
Here is how .mcstructure looks like where JSON represents NBT.
```json
"":{
"format_version":1,
"size":[],//...
"structure":{},//...
"structure_world_origin":[]//..
}
```
:::warning
This example shows that it is also necessary to read the name of the basic element, although it is usually unused and empty.
:::
## Writing NBT
There is no certain procedure for writing, because it is the same mothods as when reading, but backwards. That's why we recommend first understanding NBT and learning to read it correctly, then it won't be difficult to write NBT.
## Bedrock NBT File header
The NBT bedrock Header is indicated by two 4-byte numbers, the first is always 8 and the second indicates the size of the nbt structure in bytes. E.g.
- `08 00 00 00` - `bf 00 00 00`
- < always 8 > < always the size of the NBT structure - exclude headers 8 bytes>
## Little-Endian
Little-Endian is the common method of writing numbers in bytes to streams or files.
It's not a science and it's easy to understand. So if Int16 `(short)` of value `0x5a72` then we convert it to bytes [`0x5a`, `0x72`] and then reverse their order that means [`0x72`, `0x5a`] and write d file: `72 5a`. It may seem illogical, but little-endian is almost always used when writing and reading from files. A single `byte` is the same in both methods because it is one byte in size. For example:
- Int64 (long) `0x11223344aabbccdd`
- Split to 8 bytes `0x11 0x22 0x33 0x44 0xAA 0xBB 0xCC 0xDD`
- Reverse `0xDD 0xCC 0xBB 0xAA 0x44 0x33 0x22 0x11`
- Write `dd cc bb aa 44 33 22 11`
- Done (when reading the number just go backwards this example.)

84
docs/wiki/nbt/step-by-step-example.md Normal file
View File

@@ -0,0 +1,84 @@
---
title: Reading NBT Example
category: NBT in Depth
mentions:
- ConsoleTerm
tags:
- expert
---
Before going through this example, it is necessary to first familiarize yourself with NBT in its full beauty. See *[NBT in Depth](/nbt/nbt-in-depth)*.
Now we will show you how to read NBT, step by step, the format of what we will read will look something like this:
```json
"":{
"myText":"My NBT text",
"my Int32 Number":456,
}
```
When we don't know what to read, then we read the next byte.
![](/assets/images/nbt/VS_Editor_images/step1.png)
What did we read? We read number 10 and that means we will read compoud. We also know that we are at the root element property of this file now, so we need to read the name of our root element property. Name is string, so first we have to read the length of the text in bytes, and that is written by Int16 *(Short)*.
![](/assets/images/nbt/VS_Editor_images/step2.png)
The name size of our root element property is zero so we won't read any more bytes. We don't know what to read, so let's read another byte.
![](/assets/images/nbt/VS_Editor_images/step3.png)
We already know that the next property in our root compound is type of string, but before we read our property value, we first read its name written such as string. So we read another 2 bytes to get the length of the string name from of our property.
![](/assets/images/nbt/VS_Editor_images/step4.png)
We see that length of property name, it is 6 bytes long. So let's read the next 6 bytes.
![](/assets/images/nbt/VS_Editor_images/step5.png)
So we have read the Name of our property, which we can get in text form using UTF-8 encoding, that is: `myText`, then remember that the type of our property is string, so we repeat the process.
I'll read the next Int16 (2 bytes) again and we'll find out the length of our string value.
![](/assets/images/nbt/VS_Editor_images/step6.png)
The string length of our property is 0x0B, so 11, so read another 11 bytes.
![](/assets/images/nbt/VS_Editor_images/step7.png)
When we push our read bytes through UTF-8 encoding, it again returns the value: `My NBT text`,
what now? You don't know? So read the next byte to find out what to do next.
![](/assets/images/nbt/VS_Editor_images/step8.png)
So we read type 3, the 3 type is Int16 which contains 4 bytes. But before we read our number We have to find out the name of this property again. So?
Read the next two bytes to get the length of the name for this property.
![](/assets/images/nbt/VS_Editor_images/step9.png)
So we know the length of the name 0x0f (15), Let's read the next 15 bytes and push it through UTF-8 encoding.
![](/assets/images/nbt/VS_Editor_images/step10.png)
Now we have the name of this property: `my Int32 Number`. Next let's read that Int32 => 4 bytes.
![](/assets/images/nbt/VS_Editor_images/step11.png)
We read an Int32 that has the value `0x01c8` (456).
Again You don't know what to do next? Then just read another type of next property, so? 1 byte.
![](/assets/images/nbt/VS_Editor_images/step12.png)
We read 0x00 (an empty byte), and that marks the end of the root compound. Then the reading of the compound ends, and since it is the ***root*** compound, we can finish reading it completely and have the entire NBT file read.
### NBT Example File
This is file what we use here for this example.
<BButton
link="/assets/nbt/nbt_example_file.nbt" download
color=green
>Download NBT File</BButton>
:::tip Important points to keep in mind
- The file may contain an NBT Bedrock Header, so be aware that such a situation may occur. See [NBT in Depth](/nbt/nbt-in-depth)>[NBT Bedrock Headers](/nbt/nbt-in-depth#bedrock-nbt-file-header).
- The closing null byte does not terminate the reading of the NBT as such, but merely marks the end of the current compound.
- All the numbers you read need to be read with little-endian, See [NBT in Depth](/nbt/nbt-in-depth)>[little-endian](/nbt/nbt-in-depth#little-endian).
- The first root NBT element in a file can only be a compound or a list. The root element/property in NBT files also has its own name, even though it is mostly empty, but it still needs to be read and avoid complications.
:::

47
docs/wiki/nbt/structure-limits.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: Extending Structure Limits
category: Tutorials
mentions:
- MedicalJewel105
tags:
- easy
---
[structure]: /assets/images/nbt/structure.png
[int]: /assets/images/nbt/int.png
[list]: /assets/images/nbt/list.png
[compound]: /assets/images/nbt/compound.png
[string]: /assets/images/nbt/string.png
:::warning DEPRECATED
This method no longer works after 1.20.50 update.
:::
By default, Minecraft doesn't allow you to save structures that are more than 64x255x64 in size.
In this guide you will learn how to extend structure box size for structure blocks.
## Editing NBT
1. Put a structure block into structure and export it.
2. Open your structure with NBT editor (NBT Studio in our case) and find your structure block.
If the only block you have in your structure is structure block, you will find its data here:
![][structure] extending_structure_block.mcstructure
> ![][compound] structure
> > ![][compound] palette
> > > ![][compound] default
> > > > ![][compound] block_position_data
> > > > > ![][compound] 0
![](/assets/images/nbt/structure-limits/nbt-screenshot-1.png)
3. Set `xStructureSize`, `yStructureSize` and `zStructureSize` values to what you want.
4. Save the structure and load it in game.
![](/assets/images/nbt/structure-limits/result.png)
## Tips
You can get this structure block to your inventory by pressing mouse scroll button while holding Ctrl.
It is recommended to use structure loading animations (Place by Block) when loading a huge structure. This will minimize lags.