结构文件（.nbt / .schem / 标记块 / 地形融合）

上一页：遗迹模板（template.yml 全字段）　·　下一页：选区与保存（pos1 / pos2 / save / stage）

遗迹模板的 structure 段决定「用哪个结构、怎么放」。这一章把结构本体相关的全部细节讲透：文件格式、导入转换、掩码融地形、标记块、地基填充、旋转、分帧防卡。

1. .nbt vs .schem：QR 用哪个？

格式	谁产出	QR 能否直接用
`.nbt`（Bukkit 原生结构）	原版结构方块 / `/qr save` / `/qr import`	✅ 直接用，`structure.file` 指它
`.schem`（WorldEdit / FAWE / 各种建筑站）	WorldEdit `//copy` `//schem save`、BetterStructures 等	❌ 要先 `/qr import` 转成 `.nbt`

结论：QR 的运行格式永远是 .nbt。 拿到 .schem 就先转。

提示

为什么用原生 .nbt：QR 直接调 Bukkit 的 StructureManager，不依赖 WorldEdit / FAWE。服务器不装那些插件也能放结构。

2. `/qr import`：把 .schem 转成 .nbt

把 .schem 文件丢进 plugins/QinhRuins/schematics/ 目录，然后在游戏里：

text

/qr import <文件名.schem> <遗迹id>

QR 会：

在你站立位置临时铺出 .schem 的方块（分帧放置，约 40000 块/tick，不卡服）；
反扫标记块和牌子标记，生成 blueprint.yml；
用原生 API 把这片区域重新 capture 成 structure.nbt，写进 templates/<遗迹id>/；
把临时铺出的方块还原（导入前已自动备份原地形），现场恢复原状；
写一份最小 template.yml（只有 id / display / structure.file，其余字段你再补，见遗迹模板）。

要点：

文件名 Tab 补全：<文件名> 会从 schematics/ 目录里列出可选的 .schem。
导入会临时改世界：找一片空地导入，导完会自动还原；别在重要建筑上导。
体积上限：单次导入最大约 800 万方块，超了会拒绝。
方块实体保真：导入会尽量保留牌子文字、刷怪笼实体类型等 BlockEntity 数据。
权限：qinhruins.admin。

🖼️ [图片占位] /qr import 在空地上分帧铺出 schem、扫标记、再 capture 的过程截图　·　建议 assets/import-flow.png

离线转换（服主电脑上）

不想在服上铺方块，也可以离线把 .schem 转 .nbt：用服主电脑上的 schem2struct.py 脚本（无需 FAWE），转完直接把 structure.nbt 放进遗迹文件夹即可。适合批量处理 BetterStructures 那种成包景观。

3. 旋转 rotation

structure.rotation 控制结构放置时的朝向：

yaml

structure:
  rotation: none                 # none / random / fixed:90

取值	含义
`none`（默认）	固定朝向，原样放置。
`random`	每次生成从四向（0° / 90° / 180° / 270°）随机选一个。
`fixed:90` / `fixed:180` / `fixed:270`	固定旋转该角度。

注意

两个限制：

带标记块或带牌子标记的结构不要用 random——旋转后标记的相对坐标会错位，刷怪点 / 核心会跑偏。无标记的纯景观结构才适合随机朝向。
启用目标掩码 target-mask 时强制 NONE 朝向（逐方块放置不支持旋转）。

4. 掩码粘贴：融进地形不推土

默认放置是「整块覆盖」——结构占的每个格子，世界原来的方块全被推平。掩码（mask）让结构只在符合条件的位置落子，从而和地形咬合而不是硬推。

三种掩码，写在 structure 段：

yaml

structure:
  file: structure.nbt
  target-mask: [REPLACEABLE]       # 目标掩码：只在世界这些方块处放置
  source-skip: [AIR]               # 源黑名单：结构里这些类型不放
  source-mask: [STONE, DEEPSLATE]  # 源白名单：结构里只放这些类型

4.1 `target-mask` 目标掩码（最常用）

只在世界里命中这些方块的位置放置——结构融进地形、不破坏已有方块。

写法	含义
`[REPLACEABLE]` 或 `[*]`	只在「可替换方块」处放置：空气 + 水 + 非实心植被 + 雪 + 树叶 + 藤蔓。最常用的「融地形」配方。
`[AIR]`	只在空气（含洞穴空气 / 虚空空气）处放置。
`[STONE, DIRT]`	只在列出的具体材质处放置。
`!材质`（排除写法）	「除了它都放」。如 `[REPLACEABLE, "!BEDROCK"]` = 可替换处放，但绝不覆盖基岩。

「可替换」的判定：空气 / 水 / 所有非实心方块（除岩浆）/ *_LEAVES / SNOW / VINE。

4.2 `source-skip` 源方块黑名单

结构里的这些类型直接不放（黑名单）。

典型用途：[AIR] = 不放空气盒，这样结构里的空气格不会清空世界原有方块（做「半透」效果，或过滤建筑站导出的占位空气）。
支持 !材质 排除语法。

4.3 `source-mask` 源方块白名单

结构里只放这些类型，其余全跳过（白名单），与黑名单互补。

典型用途：[STONE, DEEPSLATE] = 只把石质骨架贴进世界，装饰 / 家具全不放。
支持 !材质 排除（如 ["!OAK_LEAVES"] = 除树叶外都放）。

4.4 掩码的代价

注意

启用任意掩码（target / source）后：

强制 NONE 朝向（不支持旋转）；
逐方块放置，超大结构会比原生整体放置略慢（但仍一次性完成，非分帧）；
多部件方块（门 / 床等 Bisected）会被特殊处理，确保两半都放下去。

5. 标记块：屏障 / 基岩

标记块让你在建结构时用两种特殊方块当「记号」，放置时 QR 自动把它们换成想要的效果。受全局开关 config.generation.marker-blocks（默认开） 控制。

在结构里摆	放置时变成	用途
屏障 `BARRIER`	清成空气	划出镂空 / 门洞 / 中空房间。
基岩 `BEDROCK`	保留原地形不覆盖（让世界原方块从结构里「透」出来）	做半埋遗迹 / 让山体穿过结构。

举例：你想让塔基「埋进」山坡——把要被地形吃掉的位置摆基岩，放置时那些格子保留山体；想让塔门是真正的洞——把门洞位置摆屏障，放置时清成空气。

yaml

# config.yml
generation:
  marker-blocks: true   # 默认开：自动处理屏障/基岩标记

注意

想在遗迹里用「真正的屏障 / 真正的基岩」（比如真要不可破坏的边界）→ 把 config.generation.marker-blocks 关掉，此时屏障 / 基岩原样放置。

标记块处理是分帧后台执行（约 4096 块/tick），不卡服。

6. 粘贴后批量换块：replace-blocks

放置完成后，把指定类型的方块批量换成另一种（分帧执行，不卡服）。

yaml

structure:
  replace-blocks:
    STONE: AIR                   # 石头→空气 = 掏空内部
    OAK_PLANKS: DARK_OAK_PLANKS  # 换材质 = 做主题皮肤变体
    COBBLESTONE: "mossy_cobblestone"  # 值支持完整方块状态字符串

键是源材质名，值是目标方块（可写材质名，也可写完整方块状态如 "oak_log[axis=y]"）。
典型用途：一座结构做多个主题变体——同一个 structure.nbt，配不同 replace-blocks 换皮（橡木版 / 深色橡木版 / 苔石版）。
匹配不到的类型自动跳过，不报错。

7. 地基填充 foundation

让遗迹底部向下长出地基并边缘渐变融地形，避免悬空或断崖。字段在 template.yml 顶层 foundation 段（不在 structure 段内）：

yaml

foundation:
  enabled: true
  max-depth: 16                  # 向下最多填多少格
  ignore-water: true
  blend-radius: 4                # 边缘向外渐变 N 格
  materials:
    default: STONE
    "DESERT,BADLANDS": SANDSTONE

字段	默认	说明
`enabled`	`false`	总开关。
`max-depth`	`16`	单列向下最多填几格（1~256），遇到实心地面停。
`ignore-water`	`true`	水也当可填位，地基穿水。
`blend-radius`	`0`	边缘向外渐变 N 格：在结构占地范围外 N 格内，每远一格地基低一格，做出斜坡裙边融进地形（0=只填正下方，可能断崖）。
`materials.default`	无	兜底地基材质。
`materials."群系,群系"`	—	按群系换材质，键可逗号分隔多个群系共用（如 `"DESERT,BADLANDS": SANDSTONE`）。

工作原理：

结构占地范围内的每一列，从底面向下填，直到碰到实心地面或填满 max-depth。
「可填」的格子 = 空气 / 树叶 / 树干 / 草木等非实心植被 /（开 ignore-water 时的）水。碰到实心地面就停，不会把已有地基挖穿。
blend-radius 让边缘逐格降低，斜插进周围地形。
群系材质按每列所在群系实时匹配，一座跨群系的遗迹边缘能自然换材质。
全程分帧后台执行（约 16 列/tick），不卡服。

提示

和掩码配合：target-mask: [REPLACEABLE]（结构融地形）+ foundation（底部补地基）是「半埋自然遗迹」的黄金组合——结构嵌进地形，底下又有踏实地基不悬空。

8. 分帧放置：超大结构防卡服

yaml

# config.yml
generation:
  spread-place-threshold: 30000  # 结构方块数超此值且 NONE 朝向 → 分帧放置

当结构方块数 超过 spread-place-threshold（默认 30000）且朝向为 NONE 时，QR 自动切到分帧放置：约 8192 块/tick 在后台铺，不冻结主线程。
小结构仍走原生一次性放置（更快）。
旋转的结构（非 NONE）走原生整体放置，不分帧。

注意

想让超大结构走分帧，别给它配旋转（保持 rotation: none），否则不触发分帧路径。

9. /qr markers：反扫标记

text

/qr markers <锚点id>

对一座已生成的锚点，重新扫描它范围内的牌子标记和标记块，把发现的刷怪点 / 奖励箱 / 核心数量报给你。

用途：检查一座遗迹里到底埋了哪些标记、确认标记是否被正确识别（调试蓝图用）。
<锚点id> 有 Tab 补全（列当前世界里的活锚点）。
找锚点 ID：/qr tp <锚点id> 也能列出，或开 director.notify-admins 让生成时私聊报坐标。

牌子标记的完整语法（[mob] / [chest] / [core] / [command] 四行格式）见蓝图与目标和选区与保存。

10. 常见配方速查

想要的效果	怎么配
结构原样硬放（地标 / 浮空塔）	啥掩码都不写（默认整块覆盖）
融进地形不推土（自然遗迹）	`target-mask: [REPLACEABLE]`
融地形但绝不毁基岩	`target-mask: [REPLACEABLE, "!BEDROCK"]`
半埋 / 山体穿透	结构里摆基岩当「透出」标记（默认开 marker-blocks）+ `foundation` 补地基
中空房间 / 门洞	结构里摆屏障当「清空」标记
只贴石质骨架	`source-mask: [STONE, DEEPSLATE, COBBLESTONE]`
不清空世界（半透叠加）	`source-skip: [AIR]`
一结构多主题皮肤	同 `structure.nbt` + 不同 `replace-blocks`
超大遗迹不卡服	`rotation: none` + 默认分帧（超 30000 块自动）

下一步

在世界里框选建筑、存模板、幽灵预览 → 选区与保存
给结构叠刷怪点 / 目标 / 奖励箱 / 核心 → 蓝图与目标
回到模板 structure 段字段表 → 遗迹模板

结构文件（.nbt / .schem / 标记块 / 地形融合） ​

1. .nbt vs .schem：QR 用哪个？ ​

2. /qr import：把 .schem 转成 .nbt ​

离线转换（服主电脑上） ​

3. 旋转 rotation ​

4. 掩码粘贴：融进地形不推土 ​

4.1 target-mask 目标掩码（最常用） ​

4.2 source-skip 源方块黑名单 ​

4.3 source-mask 源方块白名单 ​

4.4 掩码的代价 ​

5. 标记块：屏障 / 基岩 ​

6. 粘贴后批量换块：replace-blocks ​

7. 地基填充 foundation ​

8. 分帧放置：超大结构防卡服 ​

9. /qr markers：反扫标记 ​

10. 常见配方速查 ​

下一步 ​

结构文件（.nbt / .schem / 标记块 / 地形融合）

1. .nbt vs .schem：QR 用哪个？

2. `/qr import`：把 .schem 转成 .nbt

离线转换（服主电脑上）

3. 旋转 rotation

4. 掩码粘贴：融进地形不推土

4.1 `target-mask` 目标掩码（最常用）

4.2 `source-skip` 源方块黑名单

4.3 `source-mask` 源方块白名单

4.4 掩码的代价

5. 标记块：屏障 / 基岩

6. 粘贴后批量换块：replace-blocks

7. 地基填充 foundation

8. 分帧放置：超大结构防卡服

9. /qr markers：反扫标记

10. 常见配方速查

下一步