安装

上一页：概览　·　下一页：快速上手

本页带你把 QS 装起来、确认它真的在跑，并搞清楚每个软依赖各解锁什么、缺了会怎样。

---

🧱 装之前：先认清依赖

QS 有一个硬依赖和一串软依赖。区别很关键：

依赖	类型	缺了会怎样
QinhCoreLib（QCL）	硬依赖	QS 直接不启用（控制台会提示缺 QCL）
QinhItems（QI）	软依赖	QS 照常启动，只是少了"物品按键触发"这条最顺手的输入；改用 /qs cast 命令桥
MythicMobs（MM）	软依赖	QS 照常启动并做全部门控，但技能"放出来"退化成占位聊天消息，没有真实特效
AttributePlus（AP）	软依赖	影响的是 MM 那侧的伤害结算；QS 本身不读 AP
PlaceholderAPI	软依赖	占位符（冷却 / 充能 / 解锁 / 等级…）不可用，其余正常

⚠️ 顺序铁律：先装 QCL。 QCL 是整个秦淮生态的底座（物品源、属性管道、动作契约、脚本引擎都在它里面）。QCL 没就位，QS 不会启用。

---

📦 安装步骤

第 1 步：确认运行环境

项	要求
服务端	Paper / Purpur / Spigot 1.21.11+
Java	25+

Java 版本不够是最常见的"插件不加载"原因。先 java -version 看一眼。

第 2 步：放 jar

把以下 jar 丢进 plugins/：

1. QinhCoreLib-x.x.x.jar（必须，先放）
2. QinhSkills-1.0.22.jar（本插件）
3. 按需：QinhItems、MythicMobs、AttributePlus、PlaceholderAPI

第 3 步：启动服务器

第一次启动时，QS 会在 plugins/QinhSkills/ 下生成一整套目录与示例文件（见下文）。启动完成后控制台没有红色报错、/qs 命令有响应，就算装成功了。

---

🔌 软依赖逐个讲：各解锁什么

QinhItems —— 物品按键触发（最常用的输入）

装了 QI，你就能在物品上写 qinhskills:cast 动作，让"右键这把剑"直接触发 QS 技能。这是最顺手、手感最好的接法。

没装 QI 怎么办？ 用命令桥：任何能执行命令的插件（NeigeItems、MMOItems，甚至命令方块）跑 /qs cast <技能> 就能触发 QS。功能不打折，只是不如原生 handler 跟手。详见 对接总览。

MythicMobs —— 技能的"表现执行后端"

这是最需要理解的一个。QS 不画粒子、不算伤害，技能真正"放出来什么样"全靠 MM。

没装 MM 怎么办？ QS 照样能启动、能做全部门控判定。它会为每个技能自动造一个占位（stub）MM 技能，你触发时聊天栏冒出一行：

[QinhSkills] fire_wave

看到这行就证明 QS 这侧完全通了——输入、状态、门控、计划、桥接全部正常，只差 MM 把它演出来。补一个同名 MM 技能即可获得真实效果（见 快速上手）。

🔑 QS 永不覆盖你已有的同名 MM 技能。 占位技能只在"你没写过同名技能"时才存在；一旦你在 plugins/MythicMobs/skills/ 里写了同名真技能，QS 就乖乖用你的。

AttributePlus —— 伤害数值（在 MM 那侧）

QS 和 QI 都不内置伤害。当 MM 技能要造成伤害时，由 AttributePlus 这类属性插件结算具体数值。QS 本身不直接读 AP——它只把技能放出去，伤害是 MM + AP 的事。

PlaceholderAPI —— 占位符

装了 PAPI，就能在 HUD / 计分板 / 聊天里读 %qinhskills_<技能>_cooldown%、_charges、_unlocked、_level、_ready 等占位符。缺了不影响技能本身。

---

📁 首次启动生成了什么

启动后 plugins/QinhSkills/ 大致长这样：

plugins/QinhSkills/
├── config.yml              # 主配置（运行时开关、桥模式、解锁、资源、槽位、actionbar、路由）
├── skills/                 # 技能定义，按五类分文件夹
│   ├── combat/             #   fire_wave / blade_slash / demo_slash / demo_slash_charged / retaliate
│   ├── movement/           #   dash
│   ├── utility/            #   shield
│   ├── combo/              #   fire_combo_finisher
│   └── boss/
├── graphs/                 # 每个技能对应的执行图
│   └── combat/ movement/ utility/ combo/ boss/
├── integrations/           # 对接示例（QI / 命令桥 / MM 真表现 / 职业层）
└── players/                # 玩家技能档案（解锁/等级/槽位/冷却持久化）

💡 上手最快的方式：直接看自带示例。 这些示例都带详细中文注释，照着改即可： combat/fire_wave（最基础模板，先读它）· combat/blade_slash（索敌+血祭+GCD+条件+就绪提示+互斥）· combat/demo_slash（QI 物品触发）· combat/demo_slash_charged（吟唱读条）· combat/retaliate（被动反击）· movement/dash（充能+不吃 GCD）· utility/shield（开关 toggle）· combo/fire_combo_finisher（连招 右→右→左）。

integrations/ 里另有对接示例（QinhItems 物品按键、命令桥、MM 真实表现、可选职业层），同样照抄即可。

---

✅ 验证安装

两条诊断命令，看一眼就知道装没装好：

/qs protocol     # 看运行时协议/桥接状态（协议版本、桥是否就绪、MM 是否可用）
/qs bridge       # 看 MythicMobs 桥状态（桥模式、MM 是否在场、注册是否成功）

• /qs protocol 正常 → QS 运行时（输入→状态→图→计划→门控→执行→后处理）就位。
• /qs bridge 正常 →
  • 装了 MM：显示桥已连接、技能可注册到 MM。
  • 没装 MM：显示桥处于占位模式——这也是正常的，触发技能会走占位消息。

再来一发实际触发，确认链路通：

/qs unlock fire_wave     # 先解锁（默认不是全解锁）
/qs cast fire_wave       # 命令施放

聊天栏出现 [QinhSkills] fire_wave —— 恭喜，QS 整条链路通了。下一页教你把它换成真实特效。

📌 当前可用命令只有 11 条（见 快速上手 末尾的命令表）。文档里若看到 /qs test、/qs gen 等，当前未对外开放，请勿当成可用命令。

---

🔧 排错速查

现象	多半是因为	怎么办
/qs 无响应 / 控制台说 QS 未启用	QCL 没装或加载失败	先装 QinhCoreLib，再重启
插件根本没加载	Java / 服务端版本不够	确认 Java 25+、1.21.11+
技能放出来只有 [QinhSkills] xxx 聊天提示	MM 没写同名技能（这是正常占位）	在 plugins/MythicMobs/skills/ 写同名真技能 + /mm reload
物品按了没反应	技能没解锁，或物品的 handler 没注册	/qs unlock <技能>；确认 QI 装了且 /qi reload 过
改了技能 yml 不生效	没重载	/qs reload
占位符不显示	PlaceholderAPI 没装	装 PAPI，其余无影响

---

继续阅读

• 5 分钟造出第一个能放真特效的技能 → 快速上手
• 先理解架构再配置 → 核心概念
• 把技能接到物品上 → 对接总览