动作处理器大全

所属：动作系统　·　相关：触发器 · 动作处理器开发

处理器（Handler）是触发后真正执行的「效果」。在 refs 列表里用 handler + payload 引用。本页列出全部内置处理器及其 payload 格式。

🔎 想要每个处理器的字段详解 + 多种写法变体 + 易错点？看 动作处理器详解。

写法回顾：

refs:
  - handler: qi:message
    payload: "你好 {player}"
  - handler: qi:sound
    payload: "minecraft:entity.player.levelup;1;1.0"

多个 ref 按顺序执行。

---

QI 核心处理器（内置 10 个）

处理器 ID	payload 格式	行为
qi:message	纯文本（MiniMessage / & 颜色码）	给玩家发聊天消息
qi:action_bar	纯文本（MiniMessage）	物品栏上方动作栏文字，如 <gold>◎ 就绪!</gold>
qi:title	主标题||副标题||淡入||停留||淡出（首个之后可省略）	屏幕标题；时间单位 × 50ms
qi:subtitle	纯文本（MiniMessage）	仅副标题（空主标题）
qi:sound	命名空间:音效键;音量;音调	播放音效，如 minecraft:entity.player.attack.strong;1;0.8
qi:bossbar	文本;进度(0-1);颜色;样式;持续tick	Boss 血条；颜色 PINK/BLUE/RED/GREEN/YELLOW/PURPLE/WHITE；样式 PROGRESS/6/10/12/20
qi:command	命令文本（不带 /，支持 {player}）	以玩家身份执行命令
qi:console_command	命令文本（不带 /，支持 {player}）	以控制台执行命令
qi:give_item	物品源引用（如 my_sword_id 或 ce-wooden_axe）	给玩家发物品
qi:close_inventory	（空）	关闭玩家打开的容器

详细 payload 示例

qi:title —— 用 || 分隔字段：

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

qi:sound —— 用 ; 分隔：

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

qi:bossbar：

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

qi:command / qi:console_command —— {player} 会替换成玩家名：

- handler: qi:command
  payload: "effect give {player} minecraft:strength 10 1"
- handler: qi:console_command
  payload: "say {player} 触发了技能"

---

演示处理器

处理器 ID	payload	行为
qi:echo	纯文本	回显到聊天（仅演示）
demo:noop	JSON（可选 note）	什么都不做（仅演示）

---

生态处理器（其它插件注册）

处理器 ID	来源	payload 格式
qinhskills:cast	QinhSkills 桥	JSON：{"skill":"技能ID","level":1} —— 释放 QS 技能
combat:swing	战斗模块	light 或 heavy —— 执行攻击动作
ap:trigger	AttributePlus	不透明，AP 内部处理

qinhskills:cast —— 把技能释放交给 QinhSkills：

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

combat:swing —— 配合 属性系统 的挥击：

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

---

payload 序列化模式

处理器的 payload 有两种模式（由其载荷 schema 决定）：

• PLAIN：单字段，payload 就是裸字符串（如 qi:message 的 你好）。
• JSON：多字段，payload 是 JSON 对象（如 qinhskills:cast 的 {"skill":"...","level":1}）。

GUI 编辑器会根据 schema 自动生成表单（动作编辑器）。

---

开发自定义处理器

需要内置处理器之外的效果？实现 QinhActionHandler 接口并注册。这是把复杂逻辑（if/switch/状态）引入动作系统的唯一正道（YAML 里不能写逻辑）。详见 动作处理器开发。

QinhItemsAPI.actions().registerHandler(object : QinhActionHandler {
    override val handlerId = "myplugin:my_handler"
    override fun dispatch(ctx: QinhActionContext): ActionDispatchResult {
        ctx.player.sendMessage("执行：${ctx.payload}")
        return ActionDispatchResult.HANDLED
    }
})

---

下一步

• 冷却 / 消耗 / 条件 / 连招
• 动作处理器开发：自定义处理器 + payload schema