对接总览：把技能接到物品 / NPC / MythicMobs
上一页：首页 · 下一页：对接 QinhItems
QS 自己不监听任何按键，也不画一个粒子。它是夹在中间的「技能大脑」。所以「对接」这一章，本质就回答两个问题：
- 怎么触发它 —— 玩家按键 / 用物品 / 点 NPC，怎样变成「放某个 QS 技能」？（对接物品插件）
- 怎么让它有表现 —— 技能放出来怎样才有粒子、位移、伤害？（对接 MythicMobs）
读完本页你会知道：四方分工的铁律、首次启动 QS 给你释放了哪几个对接示例文件、三种把技能接到物品上的接法、以及「我用的是 X 物品插件该看哪一页」。
🖼️ [图片占位] 四方分工流程图（物品按键 → QS 门控 → MM 表现 → 属性插件结算伤害） · 建议
assets/integration-overview.png
🧱 一、先记住这条铁律：四方分工
整个秦淮技能体系，把「放一个技能」这件事拆给了四个插件，各管一段、互不抢权。这是理解后面所有页的前提，请务必先记牢：
| 角色 | 谁来做 | 管什么 | 绝不管什么 |
|---|---|---|---|
| 🎮 触发 | QinhItems / NeigeItems / MMOItems / NPC… | 把「按键 / 用物品 / 点击」变成「放某个技能 id」 | 技能逻辑、冷却、伤害 |
| 🧠 门控 | QinhSkills（QS） | 解锁 / 冷却 / 冷却组 / 充能 / GCD / 资源 / 血祭 / 目标索敌 / 连招状态 / 吟唱进度 / 被动条件 / 门控 | 粒子、位移、音效、表现、伤害数值 |
| 🎆 表现 | MythicMobs（MM） | 粒子 / 位移 / 音效 / 触发伤害事件 / 一切「放出来啥样」 | 冷却、解锁、连招、触发解析 |
| ⚔️ 数值 | AttributePlus（AP） 等属性插件 | 按攻击者物品属性结算最终伤害数值 | 技能怎么放、何时放 |
一句话记住：物品负责「按下」，QS 负责「能不能放」，MythicMobs 负责「放出来啥样」，属性插件负责「打多少伤害」。
为什么要这样拆？（WHY 先讲）
最直觉的做法是「物品直接调 MythicMobs 放技能」，为什么秦淮偏偏在中间插一层 QS？因为如果物品直接调 MM，会出现三个无解的问题：
- 冷却没人统一管 —— 物品配一份冷却、MM 配一份冷却，玩家会遇到「双重冷却」或者「绕过冷却」。
- 资源会被双扣 —— 物品扣一次蓝、技能再扣一次蓝。
- 逻辑散落三处 —— 解锁判定在物品、连招在物品、伤害在 MM…… 改一个技能要翻三个插件。
QS 插在中间，就是把「状态 / 逻辑」和「表现」彻底分离：QS 是唯一的数据真实源（冷却、资源、解锁都在它这），MM 是可替换的执行后端。这条「为何不直接调 MM」的完整论证，是 对接 MythicMobs 的开篇重点，强烈建议读。
📂 二、首次启动释放的 4 个对接示例文件
QS 第一次启动时，会把 4 份对接示例释放到 plugins/QinhSkills/integrations/ 目录。它们是「可直接抄」的范本，每一份都对应本章某一页：
| 释放出来的文件 | 作用 | 对应文档页 |
|---|---|---|
integrations/qinhitems_action_example.yml | QinhItems 物品 → 触发 QS 技能（原生 handler） | 对接 QinhItems |
integrations/neigeitems_skill_example.yml | NeigeItems / 任意插件 → 触发 QS 技能（命令桥） | 对接其他物品插件 |
integrations/mythic/QinhSkillsEcosystem.yml | MythicMobs 技能 ← QS 调用执行（表现层） | 对接 MythicMobs |
integrations/QinhClass_MMOCore.md | 与职业插件（QinhClass / MMOCore）协同的说明 | （职业体系文档） |
📌 这些文件只是示例，不会被 QS 自动加载执行。
qinhitems_action_example.yml要你复制到plugins/QinhItems/items/、QinhSkillsEcosystem.yml要你复制到plugins/MythicMobs/skills/，才会生效。每份文件头部都写清了「复制到哪里、改完跑什么命令」。
🔌 三、三种把技能接到物品上的接法
「让玩家按键放技能」有三条路。它们最终都汇入同一套 QS 运行时（同样过解锁 / 冷却 / 消耗 / 目标 / 连招门控），只是「入口」不同：
| 接法 | 入口 | 适用 | 能力 | 详见 |
|---|---|---|---|---|
| ① QI 原生 handler | 物品动作里写 handler: qinhskills:cast | 你用 QinhItems | 最「原生」，能带 JSON payload、能拿到 item / itemId 上下文 | 对接 QinhItems |
| ② 命令桥 | 物品 / NPC「使用时」跑命令 qs cast <技能id> | 你用 NeigeItems / MMOItems / 任意能跑命令的插件 | 通用稳定，payload 仅纯字符串 | 对接其他物品插件 |
| ③ MM 执行后端 | 不是触发入口，是「表现」那一头 | 所有人都要配 | 给技能配粒子 / 伤害 / 位移 | 对接 MythicMobs |
⚠️ ① 和 ② 是二选一的触发方式，③ 是所有人都要的表现层。也就是说：无论你用 QI 还是 NI 触发，最后都得在 MythicMobs 里写一个同名技能，技能才有真实表现。否则技能「放出来」只是一条占位消息
[QinhSkills] 技能名。
怎么选 ① 还是 ②？
- 用 QinhItems → 永远优先 ① 原生 handler（功能最全）。
- 物品插件没有原生对接 QS → 用 ② 命令桥（只要它能在使用时跑命令就行）。
- 优先用插件的原生方式，没有再用命令桥。
🧭 四、决策表：我用的是 X 物品插件 → 该看哪一页
| 你的物品 / 触发来自… | 用哪种接法 | 主看 | 还要配 |
|---|---|---|---|
| QinhItems | ① 原生 handler | 对接 QinhItems | 对接 MythicMobs |
| NeigeItems | ② 命令桥 | 对接其他物品插件 | 对接 MythicMobs |
| MMOItems | ② 命令桥（ability/命令跑 qs cast） | 对接其他物品插件 | 对接 MythicMobs |
| Citizens / 任意 NPC 插件 | ② 命令桥（点击 NPC 跑命令） | 对接其他物品插件 | 对接 MythicMobs |
| 菜单 / GUI 插件（DeluxeMenus 等） | ② 命令桥（点格子跑命令） | 对接其他物品插件 | 对接 MythicMobs |
| 想自己写插件触发 | API / 监听 QISkillUseEvent | 执行链路与事件 | 对接 MythicMobs |
💡 不管哪一行，「对接 MythicMobs」那一列都跑不掉——它是表现层，人人都要。
🪜 五、依赖降级表：缺了某个插件会怎样
QS 的依赖关系（写在 plugin.yml）：
depend: [QinhCoreLib] # 硬依赖，缺则 QS 不启用
softdepend: [QinhItems, MythicMobs, AttributePlus, PlaceholderAPI] # 软依赖，可缺| 缺谁 | 后果 | 还能用吗 |
|---|---|---|
| QinhCoreLib | ❌ QS 直接不启用（这是硬依赖） | 不能 |
| QinhItems | qinhskills:cast handler 不注册 | ✅ 命令桥 /qs cast 仍可用；QI 晚加载会自动补注册 |
| MythicMobs | 技能执行（EXEC）失败 | ✅ 门控仍跑，技能「放出来」只有占位消息或失败 |
| AttributePlus | 不影响 QS 运行；只是伤害没有属性插件结算 | ✅ 技能照放，伤害走 MM 自身 / 原版 |
| PlaceholderAPI | %qinhskills_*% 占位符不注册 | ✅ 其余功能正常 |
📌 重点：只有 QinhCoreLib 是「缺了就废」。其余三个缺了都还能跑，只是某块能力退化。这让你可以「先把 QS + QI 跑起来看占位消息」，再慢慢补 MM 表现。
🎯 上手顺序建议
如果你完全是新手，按这个顺序读最顺：
- 先理解 为什么要插一层 QS → 对接 MythicMobs 的开篇「为何不直接调 MM」。
- 再按你的物品插件挑触发接法 → 对接 QinhItems 或 对接其他物品插件。
- 想搞懂「从按键到放出技能」中间到底发生了什么、出问题怎么诊断 → 执行链路与事件。
继续阅读
- 用 QinhItems？ → 对接 QinhItems
- 想搞懂「为何不直接调 MM」+ 配 MM 表现 → 对接 MythicMobs
- 用 NeigeItems / MMOItems / NPC？ → 对接其他物品插件
- 想看完整链路 / 自己写插件触发 → 执行链路与事件