机关系统（触发器 × 动作）

所属：服主指南总览　·　上一篇：刷怪与通关　·　下一篇：放置档案
相关：蓝图与目标 · 机关编辑 · config.yml 全配置

机关（Mechanism）是蓝图里的可编程世界交互：「触发器 → 一串动作」。玩家踩到板、挖穿墙、走进区域、推进阶段、红石充能……就执行你配的动作：开门、刷伏兵、播标题、给奖励、传送……

🔑 架构红线：机关是纯世界交互，不碰属性 / 伤害。它能 fill 方块、spawn 怪、播音效、发战利品，但不会去改谁的攻击力血量——那是 QinhItems / 属性插件的事。这条和 QR 整体「不算数值」一脉相承（见核心概念）。

机关写在 templates/<模板id>/blueprint.yml 的 mechanisms 段，也可以用 /qr editor 的机关编辑可视化配。

🖼️ [图片占位] 「触发器 → 动作链」流程示意（踩板 → 刷伏兵 + 播标题 + 播音效）　·　建议 assets/mechanism-flow.png

一、一个机关长什么样

每个机关是 mechanisms 列表里的一项：

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   # 需达到的阶段
    radius: 24         # 受众/作用半径（格）

机关顶层字段

字段	含义	默认	说明
`id`	机关唯一标识	必填	同蓝图内不重名
`trigger`	触发器（见 §二）	必填	包含 `type` 及对应的 `pos` / `region` / `interval` / `stage`
`actions`	动作链（见 §三）	必填	列表，按顺序执行；为空的机关会被忽略
`once`	是否只触发一次	false	true=本锚点这辈子只触发一次（持久记录，重载不丢）
`cooldown`	触发冷却（秒）	0	触发后 N 秒内不再响应
`require-stage`	需达到的阶段	0	当前通关阶段 ≥ 此值才触发；0=不限
`radius`	受众 / 作用半径（格）	24	MESSAGE / TITLE / SOUND / EFFECT / TELEPORT(all) 等「找附近玩家」的动作用它

注意

所有坐标都相对结构原点（结构最小角 = 0,0,0），和蓝图其他字段一致。详见蓝图与目标 §一。

触发的前置闸门（fire 前的检查顺序）

机关被触发器命中后，依次通过这些检查才会真正执行动作：

require-stage：当前通关阶段不够 → 跳过。
once：已触发过（持久记录里有）→ 跳过。
cooldown：还在冷却中 → 跳过。
全部通过 → 顺序执行 actions；若 once 则记下、若有 cooldown 则开始计时。

二、6 种触发器（MechTriggerType）

trigger.type 决定「这机关被什么触发」，共 6 种。不同触发器读 trigger 里不同的字段：

触发器 type	触发条件	需要的字段
`INTERACT`	玩家右键点击指定方块	`x/y/z`（触发块坐标）
`BLOCK_BREAK`	玩家挖掉指定方块	`x/y/z`（触发块坐标）
`REDSTONE`	指定方块从无充能变为有充能（上升沿）	`x/y/z`（触发块坐标）
`REGION_ENTER`	玩家走进指定区域（进入瞬间触发一次）	`from` + `to`（区域两角）
`TIMER`	有玩家在附近时，每隔 N 秒触发	`interval`（秒）
`STAGE`	通关推进到指定阶段时触发	`stage`（阶段号）

触发器字段写法

yaml

# 方块类（INTERACT / BLOCK_BREAK / REDSTONE）：给单点坐标
trigger: { type: INTERACT, x: 4, y: 1, z: 0 }

# 区域类（REGION_ENTER）：给 from / to 两个角
trigger:
  type: REGION_ENTER
  from: { x: 2, y: 1, z: 2 }
  to:   { x: 6, y: 3, z: 6 }

# 计时类（TIMER）：给 interval（秒）
trigger: { type: TIMER, interval: 30 }

# 阶段类（STAGE）：给 stage
trigger: { type: STAGE, stage: 2 }

几个关键行为

REDSTONE 只在上升沿触发（从 0 充能变为有充能那一刻），不会因为持续充能反复刷。
BLOCK_BREAK 的触发块允许被挖穿——即使遗迹处于保护锁定中，这块也能破坏（否则触发不了）。见刷怪与通关 §五。
REGION_ENTER 是「进入瞬间触发一次」：玩家在区域里站着不会反复触发，走出去再进来才会再次触发。
TIMER 需要附近有玩家才计时推进（无人时不空转）。
INTERACT 只认主手右键方块。

⚙️ REGION_ENTER 和 TIMER 靠后台定时扫描，受 config.yml 的 mechanisms.scan-radius（默认 48，玩家进此范围才评估）和 mechanisms.period-ticks（默认 10，评估间隔）约束。方块类（INTERACT / BLOCK_BREAK / REDSTONE）走事件即时响应，不占扫描预算。

三、12 种动作（MechActionType）

actions 里每项的 type 决定做什么，共 12 种。动作的参数有两种写法：

结构化坐标：pos / from / to（写成 { x:.., y:.., z:.. }），用于位置类动作；
params：除 type / pos / from / to / x / y / z 外的其余键都当成参数读（值按字符串解析）。

下面逐个讲，列出每种动作读哪些参数。

1. FILL —— 区域填充方块

把一个区域全填成某种方块（开门、塌方、起墙、灌水……）。

参数	含义	默认
`from` / `to`	区域两角（相对坐标）	必填
`material`	填充材质（Bukkit Material 名）	`AIR`

yaml

# 把门洞填成空气 = 开门
- { type: FILL, from: { x: 3, y: 1, z: 0 }, to: { x: 5, y: 3, z: 0 }, material: AIR }
# 起一道石墙封路
- { type: FILL, from: { x: 0, y: 1, z: 5 }, to: { x: 8, y: 4, z: 5 }, material: STONE }

注意

区域体积超过 config.yml 的 mechanisms.max-fill-volume（默认 20000 方块）会直接跳过防卡服。大范围改造请分多个机关或调高上限。材质名写错会静默跳过。

2. SPAWN —— 刷怪

在指定点刷怪（伏兵、增援、阶段 Boss）。

参数	含义	默认
`pos`	刷怪点（相对坐标）	(0,0,0)
`mob`	怪 key：原版名或 `mm-<MM名>`	必填
`level`	等级（仅 MM 怪生效）	1
`count`	刷几只	1

yaml

- { type: SPAWN, pos: { x: 5, y: 2, z: 8 }, mob: ZOMBIE, count: 4, level: 1 }
- { type: SPAWN, pos: { x: 6, y: 2, z: 9 }, mob: mm-FireSkeleton, count: 1, level: 5 }

提示

机关 SPAWN 出来的怪不带通关击杀标记，不计入 objectives 阶段进度。要算进度的怪请用蓝图 spawn-points（见蓝图与目标）。机关 SPAWN 适合做「氛围伏兵」。

3. MESSAGE —— 聊天消息

给半径内玩家发一行聊天消息。

参数	含义
`text`	消息文本（支持颜色码）

yaml

- { type: MESSAGE, text: "&c机关启动！小心脚下！" }

受 radius 约束（给触发者附近的玩家）。

4. TITLE —— 屏幕标题

给半径内玩家显示屏幕标题。

参数	含义
`title`	主标题
`subtitle`	副标题（可选）

yaml

- { type: TITLE, title: "&6封印解除", subtitle: "&7通往深处的门已开启" }

5. SOUND —— 音效

给半径内玩家播放音效。

参数	含义	默认
`sound`	音效名（Bukkit Sound 名）	必填
`volume`	音量	1.0
`pitch`	音调	1.0

yaml

- { type: SOUND, sound: BLOCK_PISTON_EXTEND, volume: 1.0, pitch: 0.8 }

6. EFFECT —— 药水效果

给半径内玩家施加药水效果（缓慢陷阱、失明、夜视加成……）。

参数	含义	默认
`effect`	效果名（PotionEffectType 名）	必填
`level`	等级（从 1 起，1=基础级）	1
`seconds`	持续秒数	5

yaml

- { type: EFFECT, effect: SLOWNESS, level: 2, seconds: 8 }

7. COMMAND —— 执行命令

执行一条命令。{player} 会替换成触发者名字。

参数	含义	默认
`command`	命令（开头 `/` 可省）	必填
`as`	以谁的身份：`console`（控制台）/ `player`（触发玩家）	`console`

yaml

# 控制台给触发者发钱
- { type: COMMAND, command: "eco give {player} 100", as: console }
# 以玩家身份执行
- { type: COMMAND, command: "warp dungeon_exit", as: player }

提示

as: player 时由触发玩家自己执行命令，受其权限限制；as: console 拥有控制台全权限。

8. LOOT —— 发战利品

按战利品表给触发者发战利品（掉落到地上）。

参数	含义	默认
`table`	战利品表名（`loottables/<名>.yml`）	必填
`pos`	掉落点（相对坐标）；不填则掉在触发者脚下	触发者位置
`growth-scaled`	是否按成长度缩放数量	true

yaml

- { type: LOOT, table: vault, pos: { x: 6, y: 1, z: 6 }, growth-scaled: true }

注意

需要有触发者（玩家）才发；REDSTONE / STAGE 等无玩家触发的机关用 LOOT 会因没有收件人而不发。

9. TELEPORT —— 传送

把玩家传送到指定点。

参数	含义	默认
`pos`	目标点（相对坐标）	必填
`yaw`	朝向偏航角（可选）	不改
`pitch`	朝向俯仰角（可选）	不改
`target`	传送谁：`trigger`（仅触发者）/ `all`（半径内所有人）	`trigger`

yaml

# 把触发者传到密室
- { type: TELEPORT, pos: { x: 2, y: 10, z: 2 }, yaw: 90, target: trigger }
# 把全队拉进 Boss 房
- { type: TELEPORT, pos: { x: 10, y: 1, z: 10 }, target: all }

10. PARTICLE —— 粒子

在指定点喷粒子做特效。

参数	含义	默认
`pos`	粒子中心（相对坐标）	(0,0,0)
`particle`	粒子名（Bukkit Particle 名）	`FLAME`
`count`	粒子数量（1~2000）	20
`spread`	扩散半径	0.5

yaml

- { type: PARTICLE, pos: { x: 6, y: 2, z: 6 }, particle: SOUL_FIRE_FLAME, count: 60, spread: 1.0 }

11. GIVE —— 给物品

直接把物品塞进触发者背包（满了则掉落在脚下）。

参数	含义	默认
`item`	物品引用（物品源标识，如 `qi-xxx` 等，由 CoreLib 物品桥解析）	必填
`amount`	数量	1

yaml

- { type: GIVE, item: qi-dungeon_key, amount: 1 }

提示

item 走 CoreLib 的统一物品桥，能引用 QinhItems / MMOItems / 原版等物品源；解析不到则不给。需要有触发玩家。

12. NPC —— 生成 NPC

在指定点生成一个 Citizens NPC（守门人、向导、剧情角色）。

参数	含义	默认
`pos`	生成点（相对坐标）	(0,0,0)
`name`	NPC 名字	`NPC`
`skin`	皮肤（玩家名，可选）	不设
`yaw`	朝向偏航角（可选）	不设

yaml

- { type: NPC, pos: { x: 4, y: 1, z: 4 }, name: "&e守墓人", skin: Notch, yaw: 180 }

注意

NPC 动作需要安装 Citizens，未装则此动作无效。

四、config.yml —— mechanisms 段

机关系统的全局开关与限流在 config.yml：

yaml

# 可编程机关（蓝图内 trigger→action，纯世界交互非属性）
mechanisms:
  enabled: true           # 总开关（关闭则全服机关都不响应）
  scan-radius: 48         # 区域/计时触发器扫描半径（玩家进此范围才评估机关）
  period-ticks: 10        # 区域/计时触发器评估间隔 tick（越大越省，区域进入响应越慢，下限 2）
  max-fill-volume: 20000  # 单次 FILL 动作最大方块数（防超大区域卡服）

配置	含义	默认
`mechanisms.enabled`	机关系统总开关	true
`mechanisms.scan-radius`	REGION_ENTER / TIMER 的扫描半径	48
`mechanisms.period-ticks`	REGION_ENTER / TIMER 的评估间隔 tick	10
`mechanisms.max-fill-volume`	FILL 单次最大方块数（超出跳过）	20000

五、完整示例集

例 1：踩板开门（区域进入 → 开门 + 提示）

玩家走进门前区域，自动把门洞填空、播音效与提示：

yaml

mechanisms:
  - id: auto_door
    trigger:
      type: REGION_ENTER
      from: { x: 3, y: 1, z: 7 }
      to:   { x: 5, y: 2, z: 8 }
    actions:
      - { type: FILL, from: { x: 3, y: 1, z: 9 }, to: { x: 5, y: 3, z: 9 }, material: AIR }
      - { type: SOUND, sound: BLOCK_IRON_DOOR_OPEN, volume: 1.0, pitch: 1.0 }
      - { type: MESSAGE, text: "&7一道暗门在你面前缓缓开启……" }
    cooldown: 3
    radius: 16

例 2：挖穿暗墙刷伏兵（破坏方块 → 刷怪 + 标题）

玩家挖掉藏在墙里的标记块，触发埋伏：

yaml

mechanisms:
  - id: ambush
    trigger: { type: BLOCK_BREAK, x: 6, y: 2, z: 4 }
    actions:
      - { type: TITLE, title: "&c埋伏！", subtitle: "&7你触发了陷阱" }
      - { type: SOUND, sound: ENTITY_ZOMBIE_AMBIENT, volume: 1.0, pitch: 0.7 }
      - { type: SPAWN, pos: { x: 6, y: 2, z: 5 }, mob: ZOMBIE, count: 4, level: 1 }
      - { type: SPAWN, pos: { x: 7, y: 2, z: 5 }, mob: mm-FireSkeleton, count: 1, level: 3 }
    once: true        # 这堵墙只埋伏一次
    require-stage: 1  # 第一阶段后才会触发

例 3：阶段达成传送 + 给奖（阶段推进 → 传全队进 Boss 房 + 发奖）

通关推进到第 2 阶段时，把附近全员拉进密室并发战利品：

yaml

mechanisms:
  - id: stage2_gate
    trigger: { type: STAGE, stage: 2 }
    actions:
      - { type: TITLE, title: "&6前哨已肃清", subtitle: "&7深处的守卫苏醒了" }
      - { type: TELEPORT, pos: { x: 10, y: 1, z: 10 }, yaw: 0, target: all }
      - { type: LOOT, table: vault, pos: { x: 10, y: 1, z: 12 }, growth-scaled: true }
    once: true
    radius: 32

例 4：定时机关（计时器 → 周期粒子 + 缓慢）

有玩家在附近时，每 20 秒喷一次毒雾粒子并施加缓慢，营造危险房间：

yaml

mechanisms:
  - id: poison_room
    trigger: { type: TIMER, interval: 20 }
    actions:
      - { type: PARTICLE, pos: { x: 6, y: 2, z: 6 }, particle: SNEEZE, count: 80, spread: 3.0 }
      - { type: EFFECT, effect: SLOWNESS, level: 1, seconds: 6 }
      - { type: SOUND, sound: ENTITY_GENERIC_DRINK, volume: 0.6, pitch: 0.5 }
    radius: 8

例 5：红石联动开门（红石充能 → 开门）

经典机制：拉杆 / 压力板把某块充能，机关把门填空：

yaml

mechanisms:
  - id: lever_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

例 6：右键祭坛领奖（交互 → 给物品 + 命令奖励 + 特效）

玩家右键祭坛方块，发钥匙、给钱、放特效，且每人只能领一次（用 once 配合……此处用命令限制，机关 once 是全锚点一次）：

yaml

mechanisms:
  - id: altar_reward
    trigger: { type: INTERACT, x: 6, y: 1, z: 6 }
    actions:
      - { type: PARTICLE, pos: { x: 6, y: 2, z: 6 }, particle: HAPPY_VILLAGER, count: 40, spread: 0.8 }
      - { type: SOUND, sound: UI_TOAST_CHALLENGE_COMPLETE, volume: 1.0, pitch: 1.0 }
      - { type: GIVE, item: qi-ancient_relic, amount: 1 }
      - { type: COMMAND, command: "eco give {player} 200", as: console }
      - { type: MESSAGE, text: "&a你获得了祭坛的恩赐！" }
    require-stage: 2   # 通关后才允许领
    cooldown: 1

六、排错速查

现象	可能原因
机关完全没反应	`mechanisms.enabled: false`；或 `actions` 为空被忽略；或 `require-stage` 没达到
REGION_ENTER / TIMER 不触发	玩家不在 `scan-radius` 内；或 `period-ticks` 太大没轮到
FILL 没生效	区域体积超 `max-fill-volume`；或 `material` 名写错
LOOT / GIVE 没发东西	该机关由无玩家的触发器（REDSTONE / STAGE / TIMER）触发，没有收件人；或表名 / 物品引用解析不到
NPC 不出现	没装 Citizens
触发块挖不动	那是 INTERACT / REDSTONE 触发块（受保护）；只有 BLOCK_BREAK 触发块允许挖
机关只触发了一次再也不响应	`once: true`；记录持久化，重载也不会重置（`/qr remove` 该锚点才清）

下一步

用可视化界面配机关 → 机关编辑
机关坐标体系 / 蓝图其他字段 → 蓝图与目标
保护与触发块例外 → 刷怪与通关 §五
战利品表怎么写 → 战利品系统

机关系统（触发器 × 动作） ​

一、一个机关长什么样 ​

机关顶层字段 ​

触发的前置闸门（fire 前的检查顺序） ​

二、6 种触发器（MechTriggerType） ​

触发器字段写法 ​

几个关键行为 ​

三、12 种动作（MechActionType） ​

1. FILL —— 区域填充方块 ​

2. SPAWN —— 刷怪 ​

3. MESSAGE —— 聊天消息 ​

4. TITLE —— 屏幕标题 ​

5. SOUND —— 音效 ​

6. EFFECT —— 药水效果 ​

7. COMMAND —— 执行命令 ​

8. LOOT —— 发战利品 ​

9. TELEPORT —— 传送 ​

10. PARTICLE —— 粒子 ​

11. GIVE —— 给物品 ​

12. NPC —— 生成 NPC ​

四、config.yml —— mechanisms 段 ​

五、完整示例集 ​

例 1：踩板开门（区域进入 → 开门 + 提示） ​

例 2：挖穿暗墙刷伏兵（破坏方块 → 刷怪 + 标题） ​

例 3：阶段达成传送 + 给奖（阶段推进 → 传全队进 Boss 房 + 发奖） ​

例 4：定时机关（计时器 → 周期粒子 + 缓慢） ​

例 5：红石联动开门（红石充能 → 开门） ​

例 6：右键祭坛领奖（交互 → 给物品 + 命令奖励 + 特效） ​

六、排错速查 ​

下一步 ​

机关系统（触发器 × 动作）

一、一个机关长什么样

机关顶层字段

触发的前置闸门（fire 前的检查顺序）

二、6 种触发器（MechTriggerType）

触发器字段写法

几个关键行为

三、12 种动作（MechActionType）

1. FILL —— 区域填充方块

2. SPAWN —— 刷怪

3. MESSAGE —— 聊天消息

4. TITLE —— 屏幕标题

5. SOUND —— 音效

6. EFFECT —— 药水效果

7. COMMAND —— 执行命令

8. LOOT —— 发战利品

9. TELEPORT —— 传送

10. PARTICLE —— 粒子

11. GIVE —— 给物品

12. NPC —— 生成 NPC

四、config.yml —— mechanisms 段

五、完整示例集

例 1：踩板开门（区域进入 → 开门 + 提示）

例 2：挖穿暗墙刷伏兵（破坏方块 → 刷怪 + 标题）

例 3：阶段达成传送 + 给奖（阶段推进 → 传全队进 Boss 房 + 发奖）

例 4：定时机关（计时器 → 周期粒子 + 缓慢）

例 5：红石联动开门（红石充能 → 开门）

例 6：右键祭坛领奖（交互 → 给物品 + 命令奖励 + 特效）

六、排错速查

下一步