动作处理器详解

所属：动作系统　·　相关：处理器大全 · 触发器实战

处理器大全 是速查表，本页对每个内置处理器逐个展开：payload 各字段含义、多种写法变体、易错点。

写法回顾：refs: - handler: <ID> / payload: <载荷>，多个 ref 按顺序执行。

---

qi:message —— 聊天消息

payload：一行文本，支持 MiniMessage 与传统 & 颜色码。

- handler: qi:message
  payload: "<gold>你触发了技能！</gold>"
- handler: qi:message
  payload: "&e传统颜色也行"
- handler: qi:message
  payload: "欢迎 {player}"          # {player} 替换为玩家名

• 多行：用多个 qi:message ref，或在文本里嵌入换行由客户端处理。
• 易错：MiniMessage 标签要闭合（<gold>...</gold>）。

---

qi:action_bar —— 动作栏（物品栏上方）

payload：一行文本（MiniMessage）。短促提示首选，不刷屏。

- handler: qi:action_bar
  payload: "<aqua>◎ 蓄力中…</aqua>"

• 适合冷却 / 状态提示，比 qi:message 不打断聊天。

---

qi:title —— 屏幕标题

payload：主标题||副标题||淡入||停留||淡出，用 || 分隔，时间单位 × 50ms。

# 全字段
- handler: qi:title
  payload: "<gold>⚡ 雷霆 ⚡</gold>||<gray>轰鸣回荡</gray>||3||30||10"
#           主标题                 副标题            淡入 停留 淡出

# 只要主标题（后面省略）
- handler: qi:title
  payload: "<red>强力一击</red>"

# 主标题 + 副标题，用默认时间
- handler: qi:title
  payload: "<gold>胜利</gold>||<gray>击败了 Boss</gray>"

# 空主标题 + 只显示副标题
- handler: qi:title
  payload: "||<gray>仅副标题</gray>||5||20||5"

• 时间是 tick（1 tick = 50ms）：3||30||10 = 淡入 0.15s、停留 1.5s、淡出 0.5s。
• 易错：分隔符是双竖线 ||，不是单竖线。

---

qi:subtitle —— 仅副标题

payload：一行文本。等价于 qi:title 空主标题。

- handler: qi:subtitle
  payload: "<gray>能量正在汇聚…</gray>"

---

qi:sound —— 音效

payload：音效键;音量;音调，用 ; 分隔。

- handler: qi:sound
  payload: "minecraft:entity.lightning_bolt.thunder;1;1.2"
#           音效命名空间键                            音量 音调

- handler: qi:sound
  payload: "minecraft:block.amethyst_block.chime;1;1.4"
- handler: qi:sound
  payload: "minecraft:entity.enderman.teleport;1;1"

• 音量：1 = 正常，>1 增大听觉范围；音调：0.5–2.0，高=尖、低=沉。
• 易错：分隔符是 ;；音效键用原版 sound 资源名。

---

qi:bossbar —— Boss 血条

payload：文本;进度;颜色;样式;持续tick。

- handler: qi:bossbar
  payload: "<red>充能中</red>;0.5;RED;PROGRESS;40"
#           文本           进度  颜色 样式      持续(tick)

• 进度：0.0–1.0。
• 颜色：PINK / BLUE / RED / GREEN / YELLOW / PURPLE / WHITE。
• 样式：PROGRESS（实心）/ 6 / 10 / 12 / 20（分段）。
• 持续：tick，到时自动消失。

---

qi:command —— 以玩家身份执行命令

payload：命令文本，不带 /，支持 {player}。

- handler: qi:command
  payload: "spawn"                                       # 回出生点
- handler: qi:command
  payload: "effect give {player} minecraft:strength 20 1"
- handler: qi:command
  payload: "warp pvp"

• 以玩家权限执行，玩家没权限的命令不会成功。
• 易错：不要写 /；{player} 是当前触发玩家名。

---

qi:console_command —— 以控制台执行命令

payload：命令文本，不带 /，支持 {player}。

- handler: qi:console_command
  payload: "give {player} diamond 1"
- handler: qi:console_command
  payload: "lp user {player} permission settemp vip.fly true 1h"

• 以控制台权限执行，适合需要高权限的操作（给权限、跨玩家）。
• ⚠️ 安全：payload 来自物品配置，别让玩家可控的内容拼进命令。

---

qi:give_item —— 给物品

payload：物品源引用（QI 物品 ID 或外部源引用）。

- handler: qi:give_item
  payload: "demo_heal_potion"        # 给一个 QI 物品
- handler: qi:give_item
  payload: "ce-wooden_axe"           # 外部物品源引用

• 背包满时按 give-overflow-drop 配置处理。

---

qi:close_inventory —— 关闭容器

payload：空。

- handler: qi:close_inventory
  payload: ""

• 常配合打开 GUI 的流程，或动作结束时收尾。

---

combat:swing —— 挥击攻击

payload：light 或 heavy（默认 light）。

- handler: combat:swing
  payload: "light"
- handler: combat:swing
  payload: "heavy"

• 在 5 格内取目标，触发 QinhCombatSwingEvent；启用 vanilla-hit 时调 player.attack(target)，否则 swingMainHand()。
• 需 combat.enabled: true。见 属性与数值。

---

qinhskills:cast —— 释放 QinhSkills 技能

payload：JSON {"skill":"技能ID","level":等级}。

- handler: qinhskills:cast
  payload: '{"skill":"fireball","level":1}'

• 需安装 QinhSkills；QI 把请求透传给 QS，真正施法在 QS / MythicMobs。
• 在套装 abilities 里 handler 必须用 map 形式（含冒号），见 套装。
• 见 集成。

---

组合范例：一个动作里串多个处理器

refs:
  - handler: qi:title
    payload: "<gold>觉醒</gold>||<gray>力量觉醒</gray>||5||30||10"
  - handler: qi:sound
    payload: "minecraft:block.beacon.activate;1;1"
  - handler: qi:command
    payload: "effect give {player} minecraft:strength 30 2"
  - handler: qi:action_bar
    payload: "<red>力量 +2，持续 30 秒</red>"

按顺序执行：标题 → 音效 → 给 buff → 动作栏提示。

---

想要清单之外的效果？

开发一个自定义处理器：实现 QinhActionHandler，逻辑写在代码里，YAML 引用它即可。这是把 if/switch/状态判断引入动作的唯一正道（YAML 不能写逻辑）。

---

下一步

• 处理器大全：速查表
• 触发器实战：触发 + 处理器组合
• 动作处理器开发