对接其他物品插件：命令桥 `qs cast`

上一页：对接 MythicMobs　·　下一页：执行链路与事件

并不是每个物品插件都像 QinhItems 那样原生接 QS。NeigeItems、MMOItems、菜单插件、NPC 插件……怎么触发 QS 技能？

答案是命令桥：让物品（或菜单、NPC）在被使用时，以玩家身份执行一条命令 qs cast <技能id>。只要一个插件「能在使用时跑命令」，它就能触发 QS 技能。

铁律不变：物品只负责「触发」，技能逻辑在 QS、表现在 MM、伤害在属性插件。物品自己的属性 / lore 用它那一套，QS / QI 不参与数值。

🌉 一、命令桥是什么

命令桥模式只有一句话：

让物品 / 菜单 / NPC 以玩家身份执行 qs cast <技能id>。

这条命令进了 QS 之后，和 QinhItems 原生 handler 走的是同一套运行时——同样过解锁、冷却、消耗、目标、连招的完整门控。区别只在「入口是一条命令」而非「原生事件」。

🖼️ [图片占位] 命令桥示意：物品使用 → 执行 qs cast fire_wave → QS 门控 → MM 表现　·　建议 assets/command-bridge.png

📜 二、QS 命令契约（跨插件稳定，背下来）

不管你用哪个物品插件，QS 这一侧的命令契约是确定不变的。这才是命令桥真正可靠的部分：

项	内容
命令格式	`qs cast <技能id>`
别名	`/qskills` `/qskill` 同样可用
权限	`qinhskills.cast`（默认所有玩家都有 → 物品 / NPC 触发无需额外授权）
身份	必须以「玩家」身份执行（命令桥要 as player）。控制台执行会被拒绝（技能要附着到具体玩家身上）
解锁	技能必须是该玩家已解锁的，否则 QS 拦下并提示

测试解锁：/qs unlock fire_wave，或在 QS config.yml 配 unlock.starter_skills、unlock.default_all: true。

⚠️ 「必须玩家身份」是命令桥最常见的坑：很多插件默认用控制台跑命令，那样会被拒。务必让它「以玩家身份」或「as player」执行（各插件叫法不同，见下文）。

📄 三、完整范本：`neigeitems_skill_example.yml`

下面是 QS 首次启动释放到 plugins/QinhSkills/integrations/neigeitems_skill_example.yml 的官方范本，原样照抄。以 NeigeItems 为例。

用法：把这份内容复制到 plugins/NeigeItems/Items/ 下。⚠ NeigeItems 的动作语法以你所用 NI 版本的文档为准；真正稳定不变的是文件末尾的「QS 命令契约」。

yaml

#==============================================================================
#  【对接示例 2/4】NeigeItems(或任意物品插件) → 触发 QS 技能（命令桥）
#
#  并非每个物品插件都像 QinhItems 那样原生接 QS。通用做法是【命令桥】：
#  让物品在被使用时，以玩家身份执行   qs cast <技能id>   这条命令即可。
#  这套办法适用于 NeigeItems、以及任何"能在使用时跑命令"的物品/菜单/NPC 插件。
#
#  本文件以 NeigeItems 为例(放到 plugins/NeigeItems/Items/ 下)。
#  ⚠ NeigeItems 的动作语法以你所用 NI 版本的文档为准；下面的写法是常见形式，
#    真正可靠、不变的是 QS 这一侧的命令契约(见文件末尾"QS 命令契约")。
#
#  分工同示例1：物品只负责"触发"，技能逻辑在 QS、表现在 MM、伤害在属性插件。
#  NI 物品自己的属性/lore 用 NI 那套；QS/QI 不参与数值。
#==============================================================================

# ---- NeigeItems 物品示例（语法以 NI 文档为准）----
炎符:
  material: PAPER
  name: '&b炎符'
  lore:
    - '&7右键:火焰波'
    - '&7潜行+右键:疾冲'
    - '&8技能由 QinhSkills 执行，伤害由属性插件结算'
  # NI 动作:触发器 right / left / shift_right / shift_left / all
  action:
    # 右键 → 以玩家身份执行  qs cast fire_wave
    right:
      - 'command: qs cast fire_wave'
    # 潜行+右键 → 疾冲
    shift_right:
      - 'command: qs cast dash'

#------------------------------------------------------------------------------
# ★ QS 命令契约（这部分是确定的、跨插件通用）：
#   命令格式： qs cast <技能id>          (别名 /qskills /qskill 同样可用)
#   权限：     qinhskills.cast           (默认所有玩家都有 → 物品/NPC 触发无需额外授权)
#   身份：     必须以"玩家"身份执行(命令桥要 as player)，控制台执行会被拒(技能要附着到人)。
#   解锁：     技能必须是该玩家【已解锁】的，否则 QS 拦下并提示。
#             测试: /qs unlock fire_wave，或 QS config.yml 的 unlock.starter_skills / unlock.default_all: true。
#
# 与 QinhItems 路径的区别：
#   · QinhItems 走 handler qinhskills:cast → 事件主链(见示例1)，更"原生"、能带 payload/JSON。
#   · 命令桥走 /qs cast → 同样进完整门控(冷却/消耗/目标/连招都照常)，只是入口是命令。
#   两条路最终都汇入同一套 QS 运行时，效果一致。优先用插件的原生方式，没有就用命令桥。
#==============================================================================

范本要点

段落	在干什么
`炎符:` / `material` / `name` / `lore`	NI 物品本体，用 NI 自己那套语法
`action.right` → `'command: qs cast fire_wave'`	右键 → 以玩家身份跑命令放「火焰波」
`action.shift_right` → `'command: qs cast dash'`	潜行+右键 → 放「疾冲」

NI 的动作触发器：right / left / shift_right / shift_left / all。这些对应玩家操作，但语法以你的 NI 版本文档为准——QS 不关心物品插件怎么触发，只关心最后那条 qs cast 命令。

🆚 四、命令桥 vs QinhItems 原生 handler 对比

两条路最终汇入同一套运行时，门控完整、效果一致。区别只在入口能力：

维度	QI 原生 handler（`qinhskills:cast`）	命令桥（`qs cast`）
入口	物品动作里的 handler	玩家执行 `/qs cast`
payload 能力	支持纯 id / `id:模式` / JSON	仅纯技能 id 字符串
物品上下文	有（`item` / `itemId` 等）	无（命令不带物品信息）
门控（解锁/冷却/消耗/目标/连招）	✅ 完整	✅ 完整
最终运行时 / 效果	同一套，一致	同一套，一致

怎么选？优先用插件的原生方式（QI 用 handler）；没有原生对接就用命令桥。 命令桥牺牲的只是「JSON payload」和「物品上下文」，门控和表现一分不少。

🔧 五、其他常见插件的接法

命令桥适用于任何能在使用时跑命令的插件。只要把那条命令写成 qs cast <技能id>、并确保「以玩家身份」执行即可。

MMOItems

MMOItems 的 Ability 或命令型 use 都能跑命令。在物品的 ability / command 配置里，让它以玩家身份执行：

text

qs cast fire_wave

MMOItems 各类「Command Ability」通常自带「以玩家身份」的开关——确认它是 player 身份而非 console 即可。

菜单 / GUI 插件（DeluxeMenus 等）

菜单格子点击时跑命令。把点击命令设为「玩家命令」类型：

text

[player] qs cast fire_wave

不同菜单插件标记玩家命令的写法不同（[player]、as player 等），查对应插件文档。

NPC 插件（Citizens 等）

NPC 点击 / 交互时跑命令，同样选「以玩家身份」：

text

qs cast fire_wave

🧩 通用配方（万能模板）

任何插件，只要回答得了「使用时执行什么命令、以谁身份执行」，就照填：

你要填	填什么
执行的命令	`qs cast <技能id>`
执行身份	玩家（不是控制台）
技能前提	该玩家已解锁这个技能

🔁 六、命令桥的流程（一图流）

text

玩家使用物品 / 点菜单 / 点 NPC
  → 该插件以玩家身份执行  qs cast fire_wave
  → QS 命令处理器接住（校验：玩家身份？已解锁？）
  → 进入 QS 完整门控（解锁/冷却/冷却组/充能/GCD/资源/血祭/目标/连招）
  → 过关 → 调 MythicMobs 放出表现
  → 伤害由 AttributePlus 按物品属性结算

看，从「进入门控」往后，和 QinhItems 原生路径完全一样。命令桥只是换了个门进同一栋楼。

📌 七、关于「物品本身被引用」的一句话澄清

你可能听说 MMOItems / NeigeItems 的物品本身能经 QinhCoreLib（QCL）统一物品源被引用（写成 mi-类型-id、ni-id 这类引用）。

⚠️ 那是 QCL / QI 的「物品源」话题（让秦淮生态把别家物品当掉落、当合成材料引用），和本页无关。本页只聚焦一件事：怎么让别家物品触发 QS 技能——答案就是命令桥 qs cast。

🩺 八、排错清单

现象	可能原因	解决
命令「无权限 / 控制台不能用」	物品用控制台身份跑命令	改成「以玩家身份 / as player」执行
提示「技能未解锁」	玩家没解锁该技能	`/qs unlock fire_wave`；或配 `unlock.starter_skills` / `unlock.default_all`
命令打了没反应	技能 id 拼错 / 大小写	核对技能 id（QS 会转小写）；`/qs list` 查可用技能
放出来只有占位文字	MM 没同名技能	去对接 MythicMobs 补表现
我想要 JSON / 物品上下文	命令桥不支持	换用 QI 原生 handler（对接 QinhItems）

继续阅读

想搞懂命令进 QS 后的完整链路 + 诊断 → 执行链路与事件
配技能的 MM 表现 → 对接 MythicMobs
用 QinhItems 想要原生 / JSON 能力 → 对接 QinhItems

对接其他物品插件：命令桥 qs cast ​

🌉 一、命令桥是什么 ​

📜 二、QS 命令契约（跨插件稳定，背下来） ​

📄 三、完整范本：neigeitems_skill_example.yml ​

范本要点 ​

🆚 四、命令桥 vs QinhItems 原生 handler 对比 ​

🔧 五、其他常见插件的接法 ​

MMOItems ​

菜单 / GUI 插件（DeluxeMenus 等） ​

NPC 插件（Citizens 等） ​

🧩 通用配方（万能模板） ​

🔁 六、命令桥的流程（一图流） ​

📌 七、关于「物品本身被引用」的一句话澄清 ​

🩺 八、排错清单 ​

继续阅读 ​

对接其他物品插件：命令桥 `qs cast`

🌉 一、命令桥是什么

📜 二、QS 命令契约（跨插件稳定，背下来）

📄 三、完整范本：`neigeitems_skill_example.yml`

范本要点

🆚 四、命令桥 vs QinhItems 原生 handler 对比

🔧 五、其他常见插件的接法

MMOItems

菜单 / GUI 插件（DeluxeMenus 等）

NPC 插件（Citizens 等）

🧩 通用配方（万能模板）

🔁 六、命令桥的流程（一图流）

📌 七、关于「物品本身被引用」的一句话澄清

🩺 八、排错清单

继续阅读