遗迹模板（template.yml 全字段）

上一页：服主指南总览　·　下一页：结构文件（.nbt / .schem / 标记块 / 地形融合）

这是 QR 最核心的一章：一座遗迹的身份证 template.yml 怎么写。读完你能看懂、写出任意复杂度的遗迹模板。

📦 想要现成可抄的范本？插件自带 templates/_example/template.yml（带详尽注释，以 _ 开头不会被当真遗迹加载）。复制它改名即可上手。
🩺 遗迹配了不生成？看诊断与排错的 /qr why。

1. 文件布局：一座遗迹 = 一个文件夹

每座遗迹是 plugins/QinhRuins/templates/<id>/ 下的一个文件夹，里面通常三件套：

text

templates/
└── ancient_tower/           ← 文件夹名（不写 id 时就是遗迹 ID）
    ├── template.yml         ← 模板定义本体（本章主角）
    ├── structure.nbt        ← 遗迹的方块本体（结构文件）
    └── blueprint.yml        ← 玩法层（刷怪点 / 目标 / 机关 / 核心）

注意

_ 或 . 开头的文件夹会被忽略（如 _example），不当真遗迹加载。一个文件夹里必须有 template.yml 才会被识别，否则跳过。结构文件本身怎么来、怎么融地形，见结构文件；蓝图怎么配见蓝图与目标。

改完 template.yml → /qr reload 重新加载。

2. 顶层字段总表

下表是 template.yml 的全部顶层段及其作用。加粗为最常用。

YAML 键	类型	默认	含义
`id`	String	文件夹名	遗迹唯一 ID（留空=用文件夹名）
`display`	String	= id	显示名，支持 `&` 和 `§` 颜色码
`icon`	String	`FILLED_MAP`	图鉴里的图标材质名
`respawn`	时长	`0`（不重置）	刷怪重置间隔（`30s`/`10m`/`1h`/`2d`）
`structure`	段	必填	结构文件引用 + 放置方式（见 §4）
`generation`	段	—	在哪生成（引用放置档案 + 局部覆盖，见 §5）
`loot`	段	—	容器战利品（结构里的箱子开出什么，见 §6）
`reward`	段	—	通关奖励表（见 §7）
`entry`	段	—	进入门槛（软门槛，见 §8）
`foundation`	段	关	地基填充 / 地形融合（见 §9）
`titles`	段	内置文案	进入 / 通关的屏幕标题（见 §10）
`guide_item` / `guide-item`	—	自建罗盘	指引物（见 §11）
`session`	段	内置	会话模式 / 限时 / 空场清理（见 §12）

下面逐段详解。每段给「字段说明 + 示例 + 常见用法」。

3. 基础身份（id / display / icon / respawn）

yaml

id: example_ruin                 # 遗迹唯一 ID（留空=用文件夹名）。别处（命令/掉落/指引）都用它引用
display: "§6示例遗迹"            # 显示名，支持 & 和 § 颜色码，会显示在标题/bossbar/图鉴
icon: FILLED_MAP                 # 图鉴里的图标材质（如 OAK_BOAT / ELYTRA / FILLED_MAP）
respawn: 30m                     # 刷怪重置间隔

字段	说明
`id`	全小写、字母数字 + 下划线。留空则取文件夹名。改 ID 等于换一座遗迹，已生成的旧锚点会找不到模板。
`display`	玩家可见名。`§6` = 金色，`&a` = 绿色等，两种颜色码都认。
`icon`	任意原版 `Material` 名，用于图鉴卡和 GUI。
`respawn`	锚点刷怪的重置周期。`0` 或不写 = 通关后不再重置（更像一次性地标）。时长格式：`30s` / `10m` / `1h` / `2d`，纯数字 = 秒。

4. `structure` 结构段（核心）

structure 决定用哪个方块文件、怎么旋转、怎么融进地形。这是模板里和「结构本体」打交道的唯一入口。

yaml

structure:
  file: structure.nbt            # 结构文件名（放在本文件夹内，Bukkit 原生 .nbt）
  rotation: none                 # none / random（无标记点的结构可随机朝向）
  # target-mask: [AIR]           # 掩码粘贴：只在世界这些方块处放置=融进地形不推土
  # source-skip: [AIR]           # 源方块黑名单：跳过这些类型不放置
  # source-mask: [STONE, DEEPSLATE]  # 源方块白名单：只放这些类型
  # replace-blocks:              # 粘贴后批量换块
  #   STONE: AIR
  #   OAK_PLANKS: DARK_OAK_PLANKS
  # palette: my_tile_palette     # 程序化拼接调色板（高级，见 程序化生成）

字段	类型	默认	说明
`file`	String	`structure.nbt`	结构文件名，相对本遗迹文件夹。QR 用 Bukkit 原生 `.nbt`；`.schem` 要先 `/qr import` 转。
`rotation`	String	`none`	`none` = 固定朝向；`random` = 每次生成随机四向之一。也支持 `fixed:90` 等固定角度。
`target-mask`	List	空	目标掩码：只在世界里命中这些方块的位置放置 → 结构融进地形而不是整块推土。
`source-skip`	List	空	源方块黑名单：结构里的这些类型不放（如不放空气盒）。
`source-mask`	List	空	源方块白名单：只放这些类型，其余全跳过。
`replace-blocks`	Map	空	粘贴后批量换块（分帧执行不卡服），做主题皮肤变体。
`palette`	String?	无	程序化拼接调色板 ID（高级用法）。

注意

掩码 / 标记块 / 旋转 / 分帧放置的完整规则非常多，单独成章——请看结构文件。这里只列字段位置；具体怎么融地形、REPLACEABLE 和 !排除 语法、标记块（屏障→镂空 / 基岩→地形透出）都在那一篇。

5. `generation` 生成段（在哪冒出来）

generation 回答「这座遗迹在世界哪里、以多大概率自然生成」。核心写法：引用一个放置档案（profile），再只写要覆盖的字段。

yaml

generation:
  profile: surface_overworld     # 引用放置档案（17 个内置，见 generators/）
  enabled: true                  # 是否参与自然生成
  weight: 20                     # 总控抽签权重（越大越常见）
  # priority: 0                  # 优先级：数字越小越优先；同点竞争只有最高优先级那批参与抽签
  # spawn-chance: 1.0            # 绝对稀有度：被抽中后再独立掷骰，<1.0 才真稀有
  biomes: [PLAINS, FOREST]       # 限定群系；空=不限
  y: surface                     # 生成层
  flatness: { radius: 4, max-variance: 4, max-errors: 0 }
  min-distance-others: 64        # 距任意遗迹最小间距
  min-distance-same: 256         # 距同类遗迹最小间距

5.1 核心三字段

字段	默认	说明
`profile`	无	引用 `generators/<名>.yml` 放置档案，继承它的全部默认。强烈建议用它，下面字段只写要改的。详见放置档案。
`enabled`	—	`true` 才参与自然生成；`false` = 只能 `/qr spawn` / `/qr stage` 手动投放。
`weight`	`0`	生成总控抽签权重，越大越常见。多座遗迹按权重竞争一个名额。详见自然生成与预加载。

5.2 选址范围覆盖（覆盖 profile 同名项）

字段	说明
`environments`	维度 `NORMAL` / `NETHER` / `THE_END`；空=不限。
`worlds`	限定世界名；空=该维度所有世界。
`biomes`	限定群系（如 `[PLAINS, FOREST]`）；空=不限。
`spawn-region`	坐标盒限制：`{ min-x, min-z, max-x, max-z, exclude }`。`exclude:false`=只在盒内；`exclude:true`=只在盒外（如「出生点附近不刷」）。

5.3 生成层与高度

yaml

  y: surface                     # 生成层
  # y-band: { min: 10, max: 35 } # underground/sky 的随机深度/高度
  # y-offset: 0                  # 垂直微调（海面已自动对齐水线，一般留 0）
  # heightmap: world-surface     # surface 层的高度图

`y` 取值	含义
`surface`	地表
`underground`	地下（配 `y-band` 定深度区间）
`sky`	天空（配 `y-band` 定高度区间）
`ocean-surface`	海面（自动对齐水线）
`seabed`	海底
`top`（= `ground`）	地表（`surface` 的别名，效果完全相同）
固定数字（如 `64`）	固定 Y
`+8` / `-5`	相对地表上 8 格 / 下 5 格
`+[3;12]` / `-[2;6]`	相对地表上随机 3~12 格 / 下随机 2~6 格

heightmap 仅 surface 层用，控制「地表」算到哪：world-surface / motion-blocking / motion-blocking-no-leaves / ocean-floor。留空 = 智能跳过树冠落到真地面（推荐）。

5.4 落点检测

字段	默认	说明
`whitelist-ground`	空	仅允许落在这些地面方块上（如 `[GRASS_BLOCK, DIRT]`）。
`blacklist-ground`	空	禁止落在这些地面方块上（如 `[SAND, WATER]`）。
`flatness`	`radius:4` 等	选址平整度检测：`radius`=检测半径（0=不检测）；`max-variance`=允许高差；`max-errors`=允许几个凸起采样点。地越平越严。
`spawn-in-water`	`true`	`false` = 不允许落在水面方块上。
`spawn-in-lava`	`false`	`true` = 允许落在岩浆面（下界岩浆海主题）。
`spawn-in-void`	`true`	`false` = 强制落在实心地面（拒绝脚下悬空）。

5.5 密度与稀有度

字段	默认	说明
`min-distance-others`	—	距任意遗迹最小间距（格）。设了就用它（可低于全局兜底）；不设(0)用全局 `density.min-spacing`。
`min-distance-same`	—	距同类遗迹最小间距（格），防同款扎堆。
`priority`	`0`	优先级：数字越小越优先。同一候选点上，只有最高优先级（最小值）那批参与权重抽签。默认全 0 = 纯按权重。
`spawn-chance`	`1.0`	绝对稀有度：被抽中后再独立掷一次骰子，`<1.0` 才真正变稀有（如 `0.1` = 被选中也只 10% 真生成，做稀有地标）。

提示

常见用法：大多数遗迹只写 profile + enabled + weight + biomes + y 就够。稀有 boss 遗迹再加 spawn-chance: 0.1 和高 min-distance-same。

6. `loot` 容器战利品段

结构里摆原版箱子 / 木桶等容器，玩家打开时按这里指定的战利品表滚奖励。

yaml

loot:
  mode: per-player               # per-player 每人独立一份 / shared 全服共享真容器
  container-table: vault         # loottables/vault.yml（单表，所有容器共用）
  # container-tables:            # 或按容器类型分表（优先于上面单表）：
  #   CHEST: vault
  #   BARREL: default

字段	默认	说明
`mode`	`per-player`	战利品模式（见下表）。
`container-table`	无	所有容器共用的单张战利品表（`loottables/<名>.yml`）。
`container-tables`	空	按容器类型分表，优先于 `container-table`。键是容器材质名。

mode 两种：

模式	行为
`per-player`	每位玩家首次开箱各得一份（保留神秘感），按各自成长度缩放。
`shared`	全服共享真实容器（先到先得，谁拿走就没了）；熔炉 / 酿造按真实槽位填。战利品中性：不吃成长度、不受 `min-growth` 门槛，人人同一份。

注意

结构里有大量装饰容器（如船体木桶）？去对应战利品表的 containers 字段只声明 [CHEST]，避免木桶全变宝箱。容器战利品总开关和界面行数在 config.yml 的 vessel 段。完整战利品表写法见战利品系统。

7. `reward` 通关奖励段

玩家完成所有击杀目标后发放的奖励表。

yaml

reward:
  clear-table: realm             # loottables/realm.yml

字段	说明
`clear-table`	通关奖励战利品表名（`loottables/<名>.yml`）。

这是「打通遗迹一次性发放」的奖励；和秘境净化奖励（钥石 endgame 的独占战利品）是两回事，后者在 config.yml 的 realm.reward 配，见秘境与钥石。

8. `entry` 进入门槛段

QR 不把玩家拉进独立世界，所以这不是「副本门槛」，而是「够不够资格在这座遗迹活动」的软门槛。

yaml

entry:
  min-players: 1
  max-players: 10
  # required-classes: [warrior]  # 需在场的职业（QinhClass）
  min-growth: 0.0                # 最低成长度
  # cost: "100"                  # 进入花费（经济）
  cooldown: 0s

字段	默认	说明
`min-players`	`1`	最少在场玩家数。
`max-players`	`10`	最多在场玩家数。
`required-classes`	空	需在场的职业（对接 QinhClass）。
`min-growth`	`0.0`	最低成长度门槛（防低战力硬闯高级遗迹）。
`cost`	空	进入花费（需经济插件）。
`cooldown`	`0s`	同一玩家再次进入的冷却。时长格式同 `respawn`。

9. `foundation` 地基 / 地形融合段

让遗迹底部向下长出地基，避免悬空或断崖，把结构「种进」地形里。

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`	`true` = 把水也当作可填位（地基穿过水体）。
`blend-radius`	`0`	边缘向外渐变 N 格融进地形（0=只填正下方，可能出现断崖）。越大边缘越自然。
`materials`	空	按群系换地基材质。`default` 是兜底；键可逗号分隔多个群系共用一材质（如 `"DESERT,BADLANDS": SANDSTONE`）。

提示

地基填充和边缘渐变都是分帧后台执行，不卡服。完整原理（按群系材质如何匹配、和掩码的配合）见结构文件的地基一节。

10. `titles` 标题段

玩家进入 / 通关时弹的屏幕大标题。占位符 {ruin} = 显示名。

yaml

titles:
  enter-new: "§6⚔ 你进入了 {ruin}"
  clear: "§a你通过了 {ruin} 的考验"
  enter-explored: "§7来晚一步，只能翻翻箱子了"

字段	触发时机
`enter-new`	首次进入一座未被探索的遗迹。
`clear`	完成击杀目标、通关。
`enter-explored`	进入一座已被别人探索 / 通关的遗迹。

不写则用 lang/<语言>/*.yml 里的内置文案。想统一全服文案就改语言文件，单座遗迹要特别文案就在这写。

11. 指引物（guide_item / guide-item）

玩家手持指引物右键 → 确认 GUI → 开启指引（罗盘指向最近的这座遗迹），到达即永久消耗。

yaml

guide_item: ''                   # 指引物引用：留空=用下面 guide-item 段自建简易罗盘
guide-item:                      # guide_item 留空时的兜底外观（自建简易罗盘）
  material: COMPASS
  name: "§b遗迹罗盘"
  lore: ["§7手持右键开启指引"]
  consumable: false

两种用法：

① 用现成物品当指引物 —— 给 guide_item 填一个物品源引用：

yaml

guide_item: "qi:ruin_compass"    # 也可 mi:类型:id / ia:xxx / ce:xxx / mm:xxx / 原版材质名（如 COMPASS）

② 留空，让 QR 自建简易罗盘 —— 用 guide-item 段定外观：

字段	说明
`material`	物品材质（默认 `COMPASS`）。
`name`	物品名。
`lore`	描述行列表。
`model-data`	自定义模型数据。
`consumable`	`true` = 到达目标后消耗掉。

注意

QR 不内置「发放指引物」的命令。指引物只能由物品源插件 / 掉落 / 商店给出，引用本遗迹的 qinhruins:guide_<本遗迹id>。完整指引玩法、HUD 占位符、确认 GUI 配置见向导与图鉴和 config.yml 全配置的 guide 段。

12. `session` 会话段

控制进入 / 退出会话的行为。一般保持默认即可。

yaml

session:
  mode: shared-anchor            # 会话模式
  time-limit: 30m                # 会话限时
  cleanup-on-empty: 60s          # 全员离开后多久清理会话

字段	默认	说明
`mode`	`shared-anchor`	会话模式（同一锚点共享）。
`time-limit`	`30m`	会话限时。注意 QR 不是副本，这不是倒计时通关，只是会话状态时长。
`cleanup-on-empty`	`60s`	全员离开激活范围后多久清理会话状态。

进出提示、bossbar、组队共享进度详见组队与会话；bossbar 颜色 / 样式在 config.yml 的 session 段。

13. 完整注解示例

把上面所有段拼在一起的一座真实遗迹（地表古塔风格）：

yaml

id: ancient_tower                # 遗迹唯一 ID
display: "§6远古之塔"            # 显示名
icon: STONE_BRICKS               # 图鉴图标
respawn: 1h                      # 刷怪每小时重置

structure:
  file: structure.nbt            # 方块本体
  rotation: random               # 随机朝向（无标记点结构才建议）
  target-mask: [REPLACEABLE]     # 融进地形：只在空气/水/植被/雪/树叶处放置

generation:
  profile: surface_overworld     # 引用地表主世界档案
  enabled: true
  weight: 20                     # 抽签权重
  biomes: [PLAINS, FOREST, TAIGA]
  y: surface
  flatness: { radius: 5, max-variance: 3, max-errors: 1 }
  min-distance-others: 80
  min-distance-same: 320

loot:
  mode: per-player               # 每人独立开箱
  container-tables:
    CHEST: vault                 # 箱子用 vault 表
    BARREL: default              # 木桶用 default 表

reward:
  clear-table: tower_clear       # 通关奖励表

entry:
  min-players: 1
  max-players: 8
  min-growth: 0.0
  cooldown: 0s

foundation:
  enabled: true
  max-depth: 16
  blend-radius: 4                # 边缘渐变 4 格融地形
  materials:
    default: STONE_BRICKS
    "DESERT,BADLANDS": SMOOTH_SANDSTONE

titles:
  enter-new: "§6⚔ 你踏入了远古之塔"
  clear: "§a远古之塔的守卫已被肃清"
  enter-explored: "§7塔内一片狼藉，似乎来晚了"

guide_item: ''                   # 用自建罗盘
guide-item:
  material: COMPASS
  name: "§b远古之塔·指引罗盘"
  lore: ["§7手持右键，指向最近的远古之塔"]
  consumable: false

🖼️ [图片占位] 上述远古之塔自然生成在世界里、配上地基渐变融入草原的截图　·　建议 assets/template-anatomy.png

14. 改完之后

改 template.yml → /qr reload 重新加载所有模板。
引用了不存在的 profile → 自动回退默认档案并在控制台告警。
y 值无法识别 → 回退 surface 并告警。
想确认它能不能在脚下生成 → /qr why <id>；想立即手动投放看效果 → /qr stage start <id>（幽灵预览，见选区与保存）或 /qr spawn <id>。

下一步

结构本体怎么来、怎么融地形、标记块 → 结构文件
框选已有建筑存成模板 → 选区与保存
配刷怪点 / 击杀目标 / 奖励箱 / 核心 → 蓝图与目标
在哪生成的可复用规则包 → 放置档案

遗迹模板（template.yml 全字段） ​

1. 文件布局：一座遗迹 = 一个文件夹 ​

2. 顶层字段总表 ​

3. 基础身份（id / display / icon / respawn） ​

4. structure 结构段（核心） ​

5. generation 生成段（在哪冒出来） ​

5.1 核心三字段 ​

5.2 选址范围覆盖（覆盖 profile 同名项） ​

5.3 生成层与高度 ​

5.4 落点检测 ​

5.5 密度与稀有度 ​

6. loot 容器战利品段 ​

7. reward 通关奖励段 ​

8. entry 进入门槛段 ​

9. foundation 地基 / 地形融合段 ​

10. titles 标题段 ​

11. 指引物（guide_item / guide-item） ​

12. session 会话段 ​

13. 完整注解示例 ​

14. 改完之后 ​

下一步 ​

遗迹模板（template.yml 全字段）

1. 文件布局：一座遗迹 = 一个文件夹

2. 顶层字段总表

3. 基础身份（id / display / icon / respawn）

4. `structure` 结构段（核心）

5. `generation` 生成段（在哪冒出来）

5.1 核心三字段

5.2 选址范围覆盖（覆盖 profile 同名项）

5.3 生成层与高度

5.4 落点检测

5.5 密度与稀有度

6. `loot` 容器战利品段

7. `reward` 通关奖励段

8. `entry` 进入门槛段

9. `foundation` 地基 / 地形融合段

10. `titles` 标题段

11. 指引物（guide_item / guide-item）

12. `session` 会话段

13. 完整注解示例

14. 改完之后

下一步