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

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)