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

完整版BedrockWiki镜像！

Browse Source
This commit is contained in:
boybook
2025-03-20 11:52:46 +08:00
parent 1994c41f01
commit bf9aa4b056
214 changed files with 9042 additions and 8867 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
docs/wiki/nbt/experimental-education-edition.md
View File

@@ -1,14 +1,18 @@
---
title: Experiments in Education Edition
category: Tutorials
title: 教育版中的实验性功能
category: 巧思案例
mentions:
- Fabrimat
- TheItsNameless
tags:
- easy
- Last updated for Version 1.18.32 (MEE)
- 简单
- 最后更新于版本1.18.32（教育版）
---
# 教育版中的实验性功能
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
[structure]: /assets/images/nbt/structure.png
[int]: /assets/images/nbt/int.png
[list]: /assets/images/nbt/list.png
@@ -16,22 +20,22 @@ tags:
[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
## 编辑NBT数据
::: warning
Always make a backup of your data before editing NBT files!
在编辑NBT文件前请务必备份存档！
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:
1. 从.mcworld、.mctemplate或com.mojang世界文件夹中提取level.dat文件
2. 使用NBT编辑器（例如NBT Studio）打开该文件
3. 选中根节点（显示为![][structure] level.dat）
4. 新建一个名为![][compound] experiments的复合标签
5. 选中该节点并新建一个![][byte]字节类型值，名称填写需要启用的功能名称，数值设为1。在1.18.32版本中可用的功能包括：
- data_driven_biomes
- data_driven_items
- experimental_molang_features
@@ -45,8 +49,19 @@ Experimental features may not be compatible with every device and can cause your
![](/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.
## 使用建议
教育版通常会比标准基岩版落后一到两个版本，这意味着您可以提前知晓哪些实验性功能将被加入正式版，哪些可能被修改或移除。
如果需要在教学环境中使用这些世界，建议仅启用那些长期稳定的功能。
::: code-group
```json [示例配置]
{
"experiments": {
"data_driven_biomes": 1b,
"vanilla_experiments": 1b
}
}
```
:::

6
docs/wiki/nbt/index.md
View File

@@ -1,10 +1,10 @@
---
title: NBT
categories:
- title: General
- title: 基础
color: blue
- title: Tutorials
- title: 巧思案例
color: green
- title: NBT in Depth
- title: NBT深度解析
color: red
---

123
docs/wiki/nbt/mcstructure.md
View File

@@ -1,6 +1,6 @@
---
title: .mcstructure
category: General
category: 基础
mentions:
- SirLich
- MedicalJewel105
@@ -13,115 +13,122 @@ mentions:
[compound]: /assets/images/nbt/compound.png
[string]: /assets/images/nbt/string.png
### Saving and Loading
# .mcstructure
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.
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
**Examples:**
### 保存与加载
**导出**按钮会在结构方块中创建`.mcstructure`文件。这些文件必须放置在行为包中，才能通过加载结构方块在游戏中载入。文件路径决定了结构标识符，该标识符需要输入到结构方块中以加载结构。
**示例：**
`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:
注意：直接放置在`structures`文件夹中的文件会被分配`mystructure`命名空间。如果`structures`文件夹中的结构与显式`mystructure`文件夹中的结构同名，游戏会产生以下内容日志警告：
```
[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.
[structure][warning]-在默认命名空间中加载结构时发生冲突。发现名称<name>的结构同时存在于根目录和mystructure目录。
```
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.
这种情况下，`mystructure`文件夹中的文件会"胜出"，导致直接存放在`structures`文件夹中的文件被忽略。
### 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:
`mcstructure`文件是未压缩的[NBT文件](https://wiki.vg/NBT#Specification)。与所有基岩版NBT文件一样，它们以小端格式存储。标签结构如下：
> ![Integer][int] `format_version`: Currently always set to `1`.
::: code-group
```nbt [结构文件]
> ![整数][int] `format_version`: 当前固定为`1`。
>
> ![List][list] `size`: List of three integers describing the size of the structure's bounds.
> ![列表][list] `size`: 包含三个整数的列表，描述结构边界尺寸。
>
> > ![Integer][int] Size of the structure in the X direction.
> > ![整数][int] X轴方向尺寸
> >
> > ![Integer][int] Size of the structure in the Y direction.
> > ![整数][int] Y轴方向尺寸
> >
> > ![Integer][int] Size of the structure in the Z direction.
> > ![整数][int] Z轴方向尺寸
>
> ![Compound][compound] `structure`: Actual data compound.
> ![复合标签][compound] `structure`: 实际数据结构
>
> > ![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] `block_indices`: 包含两个子列表（分别对应两个层级）。这些列表包含结构中的方块索引，每个索引指向调色板（见下文）。按ZYX顺序从最低角到最高角排列。例如，结构尺寸为`[2,3,4]`时，每个层级列表中的24个值（各维度乘积）代表位于`[(0,0,0), (0,0,1)...(1,2,3)]`的相对坐标。`-1`表示无方块，加载时保留原有方块（结构空位保存时会生成此值，第二层级大部分方块为此情况）。两个层级共享同一调色板。
> >
> > > ![List][list] of ![Integer][int] Indices for blocks in the primary layer.
> > > ![列表][list] of ![整数][int] 主层级方块索引
> > >
> > > ![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] of ![整数][int] 次层级方块索引（通常为空，仅在含水方块时存在）
> >
> > ![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.
> > ![列表][list] of ![复合标签][compound] `entities`: 实体NBT数据，存储方式与存档文件中的实体完全相同。`Pos`、`UniqueID`等标签会被保存，但加载时会被替换。
> >
> > ![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] `palette`: 包含多个命名调色板（理论上支持同一结构的多个变体）。目前仅`default`会被保存和加载。
> >
> > > ![Compound][compound] A single palette (currently only named `default`).
> > > ![复合标签][compound] 单个调色板（当前仅`default`）
> > >
> > > > ![List][list] `block_palette`: List of block states. This list contains the ordered entries that the block indices are referring to.
> > > > ![列表][list] `block_palette`: 方块状态列表。该列表包含方块索引引用的有序条目。
> > > >
> > > > > ![Compound][compound] A single block state.
> > > > > ![复合标签][compound] 单个方块状态
> > > > >
> > > > > > ![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).
> > > > > > ![字符串][string] `name`: 方块ID（如`minecraft:planks`）
> > > > > > ![复合标签][compound] `states`: 方块状态键值对（例如`wood_type:"acacia"`, `bite_counter:3`, `open_bit:1b`）。值类型与状态匹配：枚举值用字符串，数值用整数，布尔值用字节。
> > > > > > ![整数][int] `version`: 方块兼容版本号（当前版本为`17959425`，对应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] `block_position_data`: 包含结构中单个方块的附加数据。键为`block_indices`展开列表中的整数索引（层级无关）。
> > > >
> > > > > ![Compound][compound] `<index>`: A single piece of additional block data, applied to the block at its index position.
> > > > > ![复合标签][compound] `<index>`: 应用于指定索引方块的附加数据
> > > > >
> > > > > > ![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.
> > > > > > ![复合标签][compound] `block_entity_data`: 方块实体NBT数据，存储方式与存档文件中的方块实体相同。位置标签会被保存，但加载时替换。目前未发现其他相关对象。
>
> ![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.
> ![列表][list] `structure_world_origin`: 包含三个整数的列表，描述结构在存档中的原始保存位置。等于保存结构方块的位置加上偏移设置。用于确定加载时实体的放置位置。实体新绝对位置等于旧位置减去该值，再加上结构加载位置的原点。
>
> > ![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.
> > ![整数][int] 结构原点X坐标
> > ![整数][int] 结构原点Y坐标
> > ![整数][int] 结构原点Z坐标
```
- If `block_indices` does not contain exactly two values, the structure fails to load with the following content log error:
### 特殊情况测试
修改结构文件后的加载测试结果：
- 当`size`中的维度超过原版保存限制`64*256*64`时，结构仍能正常加载
- 当方块层级列表中的值不是整数标签时，所有值会被视为`0`
- 当方块层级列表中的值等于或大于调色板尺寸，或小于`-1`时，会放置空气方块
- 当`default`调色板不存在时，加载结构不会放置任何方块
- 当任何固定名称的标签缺失或类型错误时，结构加载失败并产生以下日志错误：
```
[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.
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | 结构中缺少必要字段"<tag>"
```
- If the values inside of `block_indices` do not list tags, the structure fails to load with the following content log error:
- 当`block_indices`不包含正好两个值时，结构加载失败：
```
[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field's first array is either missing or not a list.
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | "block_indices"字段应为包含2个数组的数组，当前检测到<count>个数组
```
- If the length of the two lists in `block_indices` are not equal, the structure fails to load with the following content log error:
- 当`block_indices`中的值不是列表标签时：
```
[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field's arrays need to both be the same size.
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | "block_indices"字段的第一个数组缺失或不是列表
```
- 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:
- 当`block_indices`两个列表长度不相等时：
```
[Structure][error]-Loading structure '<identifier>` from behavior pack: '<path>' | The "block_indices" field should have as many elements as defined by the "size" field.
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | "block_indices"字段的两个数组必须长度相同
```
## NBT Editors
- 当`block_indices`列表长度与结构尺寸乘积不符时：
You can find download links for some NBT editors [here](/meta/useful-links#software-installed).
```
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | "block_indices"字段元素数量应与"size"字段定义的数量一致
```
## NBT编辑器
NBT编辑器下载链接请访问[此处](/wiki/meta/useful-links#software-installed)。
---
[Original Credit](https://gist.github.com/tryashtar/87ad9654305e5df686acab05cc4b6205)
[原始文档来源](https://gist.github.com/tryashtar/87ad9654305e5df686acab05cc4b6205)

132
docs/wiki/nbt/nbt-in-depth.md
View File

@@ -1,64 +1,74 @@
---
title: About NBT (Named Binary Tag)
category: NBT in Depth
title: NBT深度解析
category: NBT深度解析
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深度解析
## 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.
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
| 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 |
NBT（命名二进制标签）是一种二进制层级的编码格式，正如你熟悉的基于文本层级的JSON格式。因此我们可以用JSON格式举例说明，你可能也注意到Minecraft本身在命令中使用JSON来表示NBT（如Java版命令或简化的基岩版命令`/give`、`/replaceitem`）。详见[NBT命令](/wiki/commands/nbt-commands)。本文将深入解析NBT的运作原理、读取方式以及`Minecraft BE`如何应用它，其详细程度远超你在命令中接触的NBT表象。
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.
## NBT标签与数据类型
与JSON类似，NBT具备类型识别系统。例如JSON通过`{}`符号识别复合对象，通过`"`识别字符串。要理解NBT，需要掌握复合对象的起始标记和各类型的读取方式。
## 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.
NBT基于二进制操作，最小单位为8位字节。各类型占用固定字节数，不存在半字节情况。注意类型名称可能有不同叫法，但二进制标识符（ID）始终由1字节表示。
### Reading Types
Type is always one byte in size, so we read the type and find out what to read next for the tag.
| 名称 | 二进制ID | 二进制大小 | 描述 |
| :----------------: | -------: | :--------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| 字节 | 0x01 | 1字节（8位） | 单字节类型 |
| Int16（短整型） | 0x02 | 2字节（16位） | 双字节类型 |
| Int32（整型） | 0x03 | 4字节（32位） | 四字节类型 |
| Int64（长整型） | 0x04 | 8字节（64位） | 八字节类型 |
| 浮点 | 0x05 | 4字节（32位） | 常规精度浮点数 |
| 双精度 | 0x06 | 8字节（64位） | 高精度浮点数 |
| 字符串 | 0x08 | 预定义长度 | UTF-8编码文本，前接2字节长度标识 |
| 列表 | 0x09 | 预定义长度 | 元素类型统一，前接4字节元素数量 |
| 复合标签 | 0x0A (10)| 未定义长度 | 通过遍历键值对读取，直到遇到结束标记 |
| 复合标签结束标记 | 0x00 | 0字节 | 仅作为复合标签结束标识 |
| 字节列表 | 0x07 | 预定义长度 | 基岩版不常用 |
| 整型列表 | 0x0B (11)| 预定义长度 | 基岩版不常用 |
| 长整型列表 | 0x0C (12)| 预定义长度 | 基岩版不常用 |
### 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.
注意NBT没有布尔类型，需用字节类型的1/0表示true/false。
### 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.
## NBT标签读写方法
所有数值类型按字节长度读取，基岩版采用[小端序](#小端序)编码，与Java版的大端序相反。
### 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`!
### 类型读取
始终读取1字节确定后续数据类型。
### 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.
### 数值读取
根据类型确定字节数（如类型3读取4字节）。所有数值使用[小端序](#小端序)处理。
## 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
### 字符串读取
先读取2字节长度标识（Int16），再按对应字节数读取UTF-8编码内容。
### 列表读取
1. 读取列表元素类型（1字节）
2. 读取元素数量（Int32，4字节）
3. 按数量循环读取元素
注意：字节列表/整型列表/长整型列表的读取方式不同
### 复合标签读取
1. 读取类型标记：
- 0x00：结束读取
- 其他类型：继续读取键值对
2. 读取键名字符串
3. 读取对应类型值
## 基岩版NBT文件解析
注意文件开头的[基岩版NBT文件头](#基岩版nbt文件头)，如`.mcstructure`文件无此头而`level.dat`有。根元素需作为匿名属性处理（即使键名为空）。
::: code-group
```json [.mcstructure示例]
"":{
"format_version":1,
"size":[],//...
@@ -66,23 +76,27 @@ Here is how .mcstructure looks like where JSON represents NBT.
"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.
:::warning
此示例表明即使根元素键名通常为空，仍需进行读取操作。
:::
## 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>
## NBT写入规范
写入流程与读取逆向操作，需先掌握读取原理。
## 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.)
## 基岩版NBT文件头
包含两个4字节数值：
1. 固定值8（0x08000000）
2. NBT结构体字节数（不含头部的8字节）
示例：
- `08 00 00 00` - `bf 00 00 00`
- <固定值8> <NBT结构体大小>
## 小端序
数字按字节逆序存储的编码方式：
- Int16 `0x5a72` → 字节数组 `[0x72, 0x5a]`
- Int64 `0x11223344aabbccdd` → 存储为 `dd cc bb aa 44 33 22 11`
读取时反向转换即可还原数值。单字节类型不受影响。

65
docs/wiki/nbt/step-by-step-example.md
View File

@@ -1,84 +1,85 @@
---
title: Reading NBT Example
category: NBT in Depth
title: 读取NBT示例
category: 基础
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:
# 读取NBT示例
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
在进行本示例前，请先系统学习NBT的完整知识体系。参考*[深入理解NBT](/wiki/nbt/nbt-in-depth)*。
现在我们将分步骤演示如何读取NBT数据，示例数据的格式如下：
```json
"":{
"myText":"My NBT text",
"myText":"我的NBT文本",
"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)*.
我们读取到了数字10，表示即将读取复合标签。此时我们处于文件的根元素属性，需要读取根元素属性的名称。名称是字符串类型，因此首先需要读取字符串长度（以Int16形式存储）。
![](/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.
根元素属性名称的长度为0，因此无需继续读取字节。此时需要读取下一个字节来确定后续数据类型。
![](/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.
已知根复合标签中的下一个属性是字符串类型，但在读取属性值之前，需要先读取属性名称。因此需要再读取2个字节来获取属性名称的长度。
![](/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.
属性名称长度为6字节，继续读取接下来的6个字节。
![](/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.
通过UTF-8编码转换后，得到属性名称：`myText`。接下来重复字符串类型的读取流程，读取下一个Int16（2字节）来获取字符串值的长度。
![](/assets/images/nbt/VS_Editor_images/step6.png)
The string length of our property is 0x0B, so 11, so read another 11 bytes.
字符串长度为0x0B（十进制11），继续读取11个字节。
![](/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.
经过UTF-8解码得到属性值：`My NBT text`。此时需要读取下一个字节来确定后续数据类型。
![](/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.
读取到类型3（Int32类型），需要先读取属性名称的长度。读取接下来的2个字节。
![](/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.
名称长度为0x0F（十进制15），继续读取15个字节并进行UTF-8解码。
![](/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.
得到属性名称：`my Int32 Number`。接下来读取Int32类型的4个字节。
![](/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.
读取到的Int32值为`0x01c8`（十进制456）。继续读取下一个字节确认后续数据类型。
![](/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.
读取到0x00空字节，表示根复合标签结束。由于这是***根***复合标签，此时完成整个NBT文件的读取。
### NBT示例文件
本示例所使用的NBT文件：
<BButton
link="/assets/nbt/nbt_example_file.nbt" download
color=green
>Download NBT File</BButton>
>下载NBT文件</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.
:::
:::tip 重要注意事项
- 文件可能包含NBT基岩版文件头，需注意这种情况。参见[深入理解NBT](/wiki/nbt/nbt-in-depth)>[NBT基岩版文件头](/wiki/nbt/nbt-in-depth#bedrock-nbt-file-header)
- 结束空字节并不直接终止NBT读取，仅标记当前复合标签的结束
- 所有数值均需按小端序读取，参见[深入理解NBT](/wiki/nbt/nbt-in-depth)>[小端序](/wiki/nbt/nbt-in-depth#little-endian)
- NBT文件的首个根元素只能是复合标签或列表。根元素的名称虽然通常为空，但仍需读取并妥善处理
:::

100
docs/wiki/nbt/structure-limits.md
View File

@@ -1,47 +1,103 @@
---
title: Extending Structure Limits
category: Tutorials
title: 扩展结构限制
category: 巧思案例
mentions:
- MedicalJewel105
tags:
- easy
- 简单
---
# 扩展结构限制
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
[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.
:::warning 已弃用
该方法在1.20.50版本更新后已失效。
:::
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.
默认情况下，Minecraft不允许保存超过64x255x64大小的结构。本教程将指导你如何扩展结构方块的可保存范围。
## Editing NBT
## 编辑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.
1. 将结构方块放入结构中并导出
2. 使用NBT编辑器（本文使用NBT Studio）打开结构文件，定位到结构方块数据
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
::: code-group
```json [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.
3. 将`xStructureSize`、`yStructureSize`和`zStructureSize`的值修改为所需尺寸
4. 保存结构文件并在游戏中加载
![](/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.
- **快速获取结构方块**：按住Ctrl键时点击鼠标滚轮可获取当前结构方块
- **优化加载性能**：加载大型结构时建议启用"按方块放置"加载动画，可有效减少卡顿
# 扩展结构限制 {#extending-structure-limits}
:::tip 版本提示
本文所述方法适用于基岩版1.20.50之前的版本
:::
通过修改NBT数据，你可以突破以下默认限制：
- X轴最大范围：64 → 384
- Y轴最大范围：256 → 256（不可修改）
- Z轴最大范围：64 → 384
实际测试表明，修改后的结构在加载时可能出现以下现象：
- 超出区块边界的部分会循环加载
- 过大的结构可能导致客户端性能下降
建议遵循以下最佳实践：
1. 使用`/testforblock`命令验证结构完整性
2. 分区块逐步加载大型建筑
3. 配合`/tickingarea`命令保持活动区块
```json
// 示例：修改后的NBT结构片段
"structure": {
"palette": {
"default": {
"block_position_data": {
"0": {
"xStructureSize": 128,
"yStructureSize": 256,
"zStructureSize": 128
}
}
}
}
}
```
:::caution 注意事项
- 修改后的结构文件在不同版本间可能存在兼容性问题
- 使用第三方NBT编辑器时请做好文件备份
- 服务器环境需要同步所有客户端的结构文件
:::
通过合理运用这些技巧，你可以轻松实现以下建筑效果：
- 超大型红石计算机
- 全景式地形景观
- 多维度联动的复杂机关
最后更新：2023年11月（适用于基岩版1.19.80）