蓝图与目标（blueprint.yml 全字段）

所属：服主指南总览　·　上一篇：结构文件　·　下一篇：刷怪与通关
相关：核心概念与架构 · 机关系统 · 程序化生成 · 战利品系统

结构文件（.nbt）只决定遗迹的方块本体。叠在它上面的玩法层——在哪刷什么怪、几阶段通关、哪些箱子解锁、钥石点在哪、机关怎么触发——全写在 templates/<模板id>/blueprint.yml。

这一页把 blueprint.yml 的每个顶层字段讲清楚，配上可直接照抄的完整示例。机关（mechanisms）与子结构变体（variants）只在这里指路，详解在各自专页。

🖼️ [图片占位] 一座遗迹结构 + 叠在上面的刷怪点 / 宝箱 / 核心 / 机关的标注俯视图　·　建议 assets/blueprint-overlay.png

一、最重要的前提：坐标都是「相对结构原点」

blueprint.yml 里所有的 x / y / z，都是相对结构原点的方块坐标，不是世界坐标。

结构原点 = 结构的最小角 = (0, 0, 0)。
也就是结构 .nbt 在它自己包围盒里、X/Y/Z 三轴都最小的那个角。
一个写 { x: 5, y: 2, z: 5 } 的刷怪点，意思是「从结构最小角往 +X 走 5 格、往上 2 格、往 +Z 走 5 格」。

这样设计的好处：同一个蓝图能跟着结构在世界任意位置、任意旋转生成，坐标永远对得上。你不用关心遗迹最终生成到世界哪个坐标，只管对着结构本身量相对偏移即可。

提示

💡 不想手算坐标？用 /qr editor start <模板id> 进入可视化编辑器，对着方块点一点就能落点，编辑器会把相对坐标写进 blueprint.yml。

注意

⚠️ 旋转的影响：遗迹生成时可能被旋转（NONE / 90 / 180 / 270）。相对坐标会随结构一起旋转，所以你写的点位永远贴着结构本体，不必为旋转额外补偿。

二、blueprint.yml 顶层字段总览

字段	作用	详见
`spawn-points`	刷怪点：在哪刷什么怪、几只、几级、属于哪个阶段	下文 §三
`loot-chests`	解锁式奖励箱：通关到某阶段才开	下文 §四
`cores`	遗迹核心：钥石右键此点激活秘境	下文 §五
`objectives`	分阶段击杀目标（通关条件）	下文 §六
`mechanisms`	可编程机关（触发器 → 动作）	机关系统
`variants`	子结构随机变体（在槽位贴加权随机模板）	程序化生成

所有字段都是可选的：只想做个纯刷怪点的遗迹，就只写 spawn-points；想做个有阶段、有奖励、有机关的完整副本式玩法，就全配上。

注意

⚠️ 架构红线：蓝图只负责「刷什么、在哪、第几阶段」。怪要变多强是 MythicMobs 的事——你给 level，由 MM 自己缩放属性。QR 不算属性 / 伤害。详见核心概念。

三、spawn-points（刷怪点）

声明遗迹被激活后，在哪些点位刷哪些怪。每个刷怪点是列表里的一项：

yaml

spawn-points:
  - { id: s1, x: 5, y: 2, z: 5, mob: ZOMBIE,          count: 3, level: 1, stage: 1 }
  - { id: s2, x: 8, y: 2, z: 5, mob: SKELETON,        count: 2, level: 1, stage: 1 }
  - { id: b1, x: 6, y: 2, z: 9, mob: mm-FireSkeleton, count: 1, level: 5, stage: 2 }

字段	含义	默认	说明
`id`	刷怪点唯一标识	必填	同一蓝图内不要重名，编辑器列表与日志靠它定位
`x` / `y` / `z`	相对结构原点坐标	0	怪从此点 +0.5 居中、`y+1` 出生（落在该格上方，避免卡地里）
`mob`	怪物标识	必填	见下方「mob 怎么写」
`count`	一次刷几只	1	上限 64，超出自动截断
`level`	怪物等级	1	仅对 MythicMobs 怪生效（交给 MM 缩放）；原版怪无等级概念
`stage`	属于哪个阶段	1	与 `objectives.stages` 的 `stage` 对应；激活先刷第 1 阶段，推进后才刷后续阶段的点

mob 怎么写

原版实体：直接写 Bukkit 实体名（大写），如 ZOMBIE、SKELETON、WITHER_SKELETON、BLAZE。写错名字或不可生成的类型会被静默跳过。
MythicMobs 怪：写 mm-<MythicMobs内部名>，如 mm-FireSkeleton。前缀 mm- 大小写不敏感，但后面的 MM 名要和你 MM 配置里的名字完全一致。装了 MythicMobs 才生效；没装则该点不刷。

提示

💡 level 只对 mm- 怪有意义。想要「同一座遗迹里的怪随秘境层数变强」，把怪做成 MythicMobs 怪并给 level，秘境会通过提 level 让 MM 自己缩放。

阶段与刷怪的关系

遗迹被玩家激活时，只刷 stage: 1 的点（前提是配了 objectives；没配目标则一次性刷全部点）。
玩家清掉第 1 阶段的击杀目标 → 推进到第 2 阶段 → 这时才刷 stage: 2 的点。
详细的推进 / 重刷规则见刷怪与通关。

四、loot-chests（奖励箱）

蓝图级的解锁式奖励箱：通关到指定阶段才允许打开。它与模板 template.yml 里的 loot.container-table（结构里摆的普通容器）可以并存，用途不同：

loot.container-table：结构里随手摆的箱子 / 木桶，进遗迹就能开（详见战利品系统）。
loot-chests：蓝图指定坐标的「关底宝箱」，要打到某阶段才解锁。

yaml

loot-chests:
  - { id: c1, x: 3, y: 2, z: 4, loot-table: vault, unlock-stage: 1, per-player-once: true, growth-scaled: true }

字段	含义	默认	说明
`id`	奖励箱唯一标识	必填	同蓝图内不重名
`x` / `y` / `z`	相对结构原点坐标	0	指向放奖励箱的那格
`loot-table`	战利品表名	必填	对应 `loottables/<名>.yml`，如 `vault`
`unlock-stage`	解锁所需阶段	1	通关进度达到此阶段才允许打开；填 0 = 一进遗迹即可开
`per-player-once`	每人是否仅一次	true	true=每位玩家各滚一份、各开一次；false=全服共享真实容器、先到先得
`growth-scaled`	是否按成长度缩放	true	true=战利品数量随玩家成长度增减；false=固定份量

提示

💡 per-player-once: true 是「保留神秘感、人人有份」的推荐玩法——每位玩家看到自己独立的一份，互不抢。false 适合做「全队抢一个真宝箱」的紧张感。

五、cores（遗迹核心）

遗迹的钥石激活点。玩家手持钥石右键这些坐标对应的方块 → 这座遗迹升为对应层数的秘境。

yaml

cores:
  - { x: 6, y: 1, z: 6 }
  # 可以配多个核心点，右键任意一个都算
  # - { x: 6, y: 1, z: 10 }

字段	含义	默认
`x` / `y` / `z`	相对结构原点坐标，指向核心方块	0

核心只有坐标，没有 id——它就是「能被钥石激活的交互点」。
把核心摆在结构里一个醒目的方块（祭坛、信标、下界传送门框等）上，玩家才知道往哪右键。
钥石、秘境层数、词缀的完整玩法见秘境与钥石。

六、objectives（分阶段目标）

遗迹的通关条件，按阶段（stage）组织。每个阶段声明「要击杀哪些怪、各几只」，全部满足就推进到下一阶段；打通最后一阶段 = 通关。

yaml

objectives:
  stages:
    - { stage: 1, name: "清剿前哨", kills: { ZOMBIE: 3, SKELETON: 2 } }
    - { stage: 2, name: "击败首领", kills: { mm-FireSkeleton: 1 } }

字段	含义	说明
`stage`	阶段编号	从 1 开始递增；与 `spawn-points` 的 `stage` 对应
`name`	阶段名称	推进 / 通关时的飘字与 bossbar 用它（如「清剿前哨」）
`kills`	击杀映射	`{ 怪key: 数量 }`，可列多种怪

kills 的怪 key 怎么对得上

kills 里的怪 key 必须和 spawn-points 里那只怪的 mob 写法一致：

原版怪：键就是实体名，如 ZOMBIE: 3。
MythicMobs 怪：键带 mm- 前缀，如 mm-FireSkeleton: 1。

击杀计数靠刷出来的怪身上打的标记追踪，所以只统计这座遗迹自己刷的怪——玩家在遗迹里顺手打死的野生僵尸不算数。

没配 objectives 会怎样

不写 objectives：遗迹没有「阶段」概念，激活时一次性刷出全部 spawn-points（忽略 stage），也不会进入 CLEARED 状态、不解锁需要阶段的奖励箱、保护也不会因「通关」而解除。
适合做纯探索 / 纯刷怪的轻量遗迹。
想要完整的「打怪 → 推进 → 通关 → 开箱 → 出钥石」体验，就配上 objectives。

阶段推进、重刷、保护解除的运行时细节见刷怪与通关。

六·B、boss-gate（最终BOSS门）

objectives 的阶段制要求你精确列出每个阶段杀哪些怪、各几只。如果你想要的是更直白的一种玩法——「不停清剿小怪，累计击杀到一定数量后，最终BOSS登场，击败它即通关」——用 boss-gate 更省事。它是 objectives 之外另一种通关方式，按累计击杀数解锁一个最终BOSS。

yaml

boss-gate:
  enabled: true
  required-kills: 30          # 累计击杀多少只「指定怪物」才解锁BOSS
  count-mobs: [ZOMBIE, SKELETON, mm-FireSkeleton]  # 哪些怪计入累计；留空=本遗迹任何刷怪都算
  announce: true             # 解锁瞬间向附近玩家播报「最终BOSS降临」
  boss:                      # 解锁后生成的最终BOSS（坐标相对结构原点）
    id: final_boss
    x: 6
    y: 2
    z: 9
    mob: mm-AncientGuardian   # 原版实体名 或 mm-<MythicMobs名>
    count: 1
    level: 10

字段	默认	含义
`enabled`	`true`	是否启用本遗迹的最终BOSS门（设 `false` 或不写整个 `boss-gate` 段 = 不启用）
`required-kills`	`10`	累计击杀阈值：玩家在本遗迹累计杀够这么多只「指定怪物」就解锁BOSS
`count-mobs`	（空）	计入累计的怪：原版实体名（`ZOMBIE`）或 `mm-<MM怪名>`，大小写不敏感。留空 = 本遗迹刷出的任何怪都算
`announce`	`true`	解锁瞬间是否向附近玩家弹「最终BOSS降临」标题 + 音效
`boss`	必填	解锁后生成的最终BOSS，字段同 `spawn-points`（`id`/`x`/`y`/`z`/`mob`/`count`/`level`，坐标相对结构原点；`mob` 支持原版名或 `mm-`）

它怎么跑：

遗迹激活后，玩家清剿 spawn-points 里的小怪（只统计这座遗迹自己刷的怪，野生怪不算）。
每杀一只「指定怪物」累计 +1；杀够 required-kills → 自动在 boss 坐标生成最终BOSS，并（若 announce）向附近播报。
击败最终BOSS = 遗迹通关（进入 CLEARED、解锁奖励箱、发放通关战利品 / 钥石），与阶段制通关等效。

注意

⚠️ boss-gate 与 objectives 二选一：两者都能定义「通关」。用了 boss-gate 就不要再用 objectives 去定义最终boss阶段，以免一座遗迹出现两套通关判定。小怪仍用 spawn-points 配置。

💡 让玩家刷得够数：boss-gate 不靠阶段推进刷怪，小怪靠模板的 respawn 重刷。如果 required-kills 比一次刷出的小怪还多，记得把模板 respawn 设为 >0（如 30s），否则小怪杀光就再也凑不够数。

📊 进度可上 HUD（需 PlaceholderAPI）：%qinhruins_boss_kills%（已杀）/ %qinhruins_boss_required%（需求）/ %qinhruins_boss_remaining%（还差）/ %qinhruins_boss_unlocked%（是否已解锁）。详见占位符。

🖼️ [图片占位] 累计击杀进度条 HUD + 最终BOSS降临的瞬间　·　建议 assets/boss-gate.png

七、mechanisms（机关）—— 指路

mechanisms 是蓝图里的可编程机关：「触发器 → 动作」的世界交互（开门、踩板刷伏兵、阶段达成传送给奖等），纯世界互动、不碰属性 / 伤害。

它字段较多（6 种触发器 × 12 种动作），单独成页：

➡️ 完整说明、参数、YAML 示例见 机关系统。

这里给个最小预览（红石充能把门填成空气）：

yaml

mechanisms:
  - id: open_door
    trigger: { type: REDSTONE, x: 4, y: 1, z: 0 }
    actions:
      - { type: FILL, from: { x: 3, y: 1, z: 0 }, to: { x: 5, y: 3, z: 0 }, material: AIR }
    once: false
    cooldown: 0
    require-stage: 0

八、variants（子结构变体）—— 指路

variants 让你在主结构的某个槽位上，按权重随机贴一个子结构模板，做出「同一主体、不同房间 / 不同塔尖」的程序化变化（对标 BetterStructures / CS 的子结构系统）。可嵌套、可贴地表。

它属于「程序化生成」范畴，单独成页：

➡️ 完整说明、surface / y-min / y-max / options 字段、嵌套规则见 程序化生成。

最小预览：

yaml

variants:
  - id: top
    x: 8
    y: 20
    z: 8
    options:
      - { template: spire_a, weight: 30 }
      - { template: spire_b, weight: 20 }

九、一份完整的 blueprint.yml 示例

把上面所有部分拼起来，就是一座「两阶段、有关底宝箱、有钥石核心、红石开门」的完整遗迹：

yaml

# 所有坐标都相对结构原点（结构最小角 = 0,0,0）

# —— 刷怪点（mob: 原版实体名，或 mm-<MythicMobs名>）——
spawn-points:
  - { id: s1, x: 5, y: 2, z: 5, mob: ZOMBIE,          count: 3, level: 1, stage: 1 }
  - { id: s2, x: 8, y: 2, z: 5, mob: SKELETON,        count: 2, level: 1, stage: 1 }
  - { id: b1, x: 6, y: 2, z: 9, mob: mm-FireSkeleton, count: 1, level: 5, stage: 2 }

# —— 解锁式奖励箱 ——
loot-chests:
  - { id: c1, x: 3, y: 2, z: 4, loot-table: vault, unlock-stage: 1, per-player-once: true, growth-scaled: true }

# —— 钥石激活点 ——
cores:
  - { x: 6, y: 1, z: 6 }

# —— 分阶段击杀目标 ——
objectives:
  stages:
    - { stage: 1, name: "清剿前哨", kills: { ZOMBIE: 3, SKELETON: 2 } }
    - { stage: 2, name: "击败首领", kills: { mm-FireSkeleton: 1 } }

# —— 机关（详见 机关系统.md）——
mechanisms:
  - id: open_door
    trigger: { type: REDSTONE, x: 4, y: 1, z: 0 }
    actions:
      - { type: FILL, from: { x: 3, y: 1, z: 0 }, to: { x: 5, y: 3, z: 0 }, material: AIR }
    once: false
    cooldown: 0
    require-stage: 0

提示

💡 这份示例可在 templates/_example/blueprint.yml 找到原型（_ 开头的模板不会被当真遗迹加载，专供照抄）。

下一步

遗迹激活、阶段推进、保护、进入门槛怎么跑 → 刷怪与通关
给遗迹加机关 → 机关系统
给遗迹加随机变体 → 程序化生成
配战利品表 → 战利品系统
模板本体（结构 / 生成 / 进入门槛 entry）全字段 → 遗迹模板

蓝图与目标（blueprint.yml 全字段） ​

一、最重要的前提：坐标都是「相对结构原点」 ​

二、blueprint.yml 顶层字段总览 ​

三、spawn-points（刷怪点） ​

mob 怎么写 ​

阶段与刷怪的关系 ​

四、loot-chests（奖励箱） ​

五、cores（遗迹核心） ​

六、objectives（分阶段目标） ​

kills 的怪 key 怎么对得上 ​

没配 objectives 会怎样 ​

六·B、boss-gate（最终BOSS门） ​

七、mechanisms（机关）—— 指路 ​

八、variants（子结构变体）—— 指路 ​

九、一份完整的 blueprint.yml 示例 ​

下一步 ​

蓝图与目标（blueprint.yml 全字段）

一、最重要的前提：坐标都是「相对结构原点」

二、blueprint.yml 顶层字段总览

三、spawn-points（刷怪点）

mob 怎么写

阶段与刷怪的关系

四、loot-chests（奖励箱）

五、cores（遗迹核心）

六、objectives（分阶段目标）

kills 的怪 key 怎么对得上

没配 objectives 会怎样

六·B、boss-gate（最终BOSS门）

七、mechanisms（机关）—— 指路

八、variants（子结构变体）—— 指路

九、一份完整的 blueprint.yml 示例

下一步