.mcstructure
本页面镜像自 BedrockWiki
根据原始项目协议授权。本文经过AI翻译处理，如有内容遗漏，可以提交PR进行补充。
保存与加载
导出按钮会在结构方块中创建.mcstructure文件。这些文件必须放置在行为包中，才能通过加载结构方块在游戏中载入。文件路径决定了结构标识符，该标识符需要输入到结构方块中以加载结构。
示例：BP/structures/house.mcstructure → mystructure:houseBP/structures/dungeon/entrance.mcstructure → dungeon:entranceBP/structures/stuff/towers/diamond.mcstructure → stuff:towers/diamond
第一个子文件夹定义命名空间，后续文件夹定义路径，最后以结构文件名结尾。
注意：直接放置在structures文件夹中的文件会被分配mystructure命名空间。如果structures文件夹中的结构与显式mystructure文件夹中的结构同名，游戏会产生以下内容日志警告：
[structure][warning]-在默认命名空间中加载结构时发生冲突。发现名称<name>的结构同时存在于根目录和mystructure目录。这种情况下，mystructure文件夹中的文件会"胜出"，导致直接存放在structures文件夹中的文件被忽略。
文件格式
mcstructure文件是未压缩的NBT文件。与所有基岩版NBT文件一样，它们以小端格式存储。标签结构如下：
nbt
> ![整数][int] `format_version`: 当前固定为`1`。
>
> ![列表][list] `size`: 包含三个整数的列表，描述结构边界尺寸。
>
> > ![整数][int] X轴方向尺寸
> >
> > ![整数][int] Y轴方向尺寸
> >
> > ![整数][int] Z轴方向尺寸
>
> ![复合标签][compound] `structure`: 实际数据结构
>
> > ![列表][list] `block_indices`: 包含两个子列表（分别对应两个层级）。这些列表包含结构中的方块索引，每个索引指向调色板（见下文）。按ZYX顺序从最低角到最高角排列。例如，结构尺寸为`[2,3,4]`时，每个层级列表中的24个值（各维度乘积）代表位于`[(0,0,0), (0,0,1)...(1,2,3)]`的相对坐标。`-1`表示无方块，加载时保留原有方块（结构空位保存时会生成此值，第二层级大部分方块为此情况）。两个层级共享同一调色板。
> >
> > > ![列表][list] of ![整数][int] 主层级方块索引
> > >
> > > ![列表][list] of ![整数][int] 次层级方块索引（通常为空，仅在含水方块时存在）
> >
> > ![列表][list] of ![复合标签][compound] `entities`: 实体NBT数据，存储方式与存档文件中的实体完全相同。`Pos`、`UniqueID`等标签会被保存，但加载时会被替换。
> >
> > ![复合标签][compound] `palette`: 包含多个命名调色板（理论上支持同一结构的多个变体）。目前仅`default`会被保存和加载。
> >
> > > ![复合标签][compound] 单个调色板（当前仅`default`）
> > >
> > > > ![列表][list] `block_palette`: 方块状态列表。该列表包含方块索引引用的有序条目。
> > > >
> > > > > ![复合标签][compound] 单个方块状态
> > > > >
> > > > > > ![字符串][string] `name`: 方块ID（如`minecraft:planks`）
> > > > > > ![复合标签][compound] `states`: 方块状态键值对（例如`wood_type:"acacia"`, `bite_counter:3`, `open_bit:1b`）。值类型与状态匹配：枚举值用字符串，数值用整数，布尔值用字节。
> > > > > > ![整数][int] `version`: 方块兼容版本号（当前版本为`17959425`，对应1.19）
> > > >
> > > > ![复合标签][compound] `block_position_data`: 包含结构中单个方块的附加数据。键为`block_indices`展开列表中的整数索引（层级无关）。
> > > >
> > > > > ![复合标签][compound] `<index>`: 应用于指定索引方块的附加数据
> > > > >
> > > > > > ![复合标签][compound] `block_entity_data`: 方块实体NBT数据，存储方式与存档文件中的方块实体相同。位置标签会被保存，但加载时替换。目前未发现其他相关对象。
>
> ![列表][list] `structure_world_origin`: 包含三个整数的列表，描述结构在存档中的原始保存位置。等于保存结构方块的位置加上偏移设置。用于确定加载时实体的放置位置。实体新绝对位置等于旧位置减去该值，再加上结构加载位置的原点。
>
> > ![整数][int] 结构原点X坐标
> > ![整数][int] 结构原点Y坐标
> > ![整数][int] 结构原点Z坐标特殊情况测试
修改结构文件后的加载测试结果：
- 当
size中的维度超过原版保存限制64*256*64时，结构仍能正常加载 - 当方块层级列表中的值不是整数标签时，所有值会被视为
0 - 当方块层级列表中的值等于或大于调色板尺寸，或小于
-1时，会放置空气方块 - 当
default调色板不存在时，加载结构不会放置任何方块 - 当任何固定名称的标签缺失或类型错误时，结构加载失败并产生以下日志错误：
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | 结构中缺少必要字段"<tag>"- 当
block_indices不包含正好两个值时，结构加载失败：
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | "block_indices"字段应为包含2个数组的数组，当前检测到<count>个数组- 当
block_indices中的值不是列表标签时：
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | "block_indices"字段的第一个数组缺失或不是列表- 当
block_indices两个列表长度不相等时：
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | "block_indices"字段的两个数组必须长度相同- 当
block_indices列表长度与结构尺寸乘积不符时：
[Structure][error]-从行为包加载结构'<identifier>`: '<path>' | "block_indices"字段元素数量应与"size"字段定义的数量一致NBT编辑器
NBT编辑器下载链接请访问此处。