技能文件结构

上一页：核心概念　·　下一页：技能定义全字段

这一页讲文件长在哪、目录怎么分、自带示例都教什么——给"准备动手配技能、但还没下笔"的你。读完你会知道：一个技能由几个文件组成、放在哪个文件夹、改完怎么让它生效。

不需要任何编程基础，照着目录结构对号入座即可。

🖼️ [图片占位] 一张 plugins/QinhSkills/ 展开的目录树截图，标出 skills/ 与 graphs/ 两套目录　·　建议 assets/file-layout-tree.png

---

📁 一个技能 = 两个文件

QS 里一个完整技能由两份 YAML 组成，分放在两个目录：

文件	放哪	管什么
技能定义	plugins/QinhSkills/skills/<分类>/xxx.yml	技能"是什么"：触发键、冷却、目标、消耗、等级…
graph（执行图）	plugins/QinhSkills/graphs/<分类>/xxx.graph.yml	技能"怎么走"：哪个键走哪个节点、放哪个 MM 技能、连招

💡 为什么拆两份？ 简单技能其实只用到 graph 里的一个"入口节点"，你几乎不用碰它。但一旦做连招，graph 就是承载多段逻辑的地方——把"按键路由"独立出来，技能定义文件才能保持干净。详见 graph 与连招。

两份文件通过一个名字挂钩，而且是四处必须全部相同：技能定义里的 graph.entry == graph 文件的 graph_id == graph 文件的 entry == 入口节点名。

# skills/combat/fire_wave.yml
graph:
  entry: fire_wave        # ← 指向下面那张图

# graphs/combat/fire_wave.graph.yml
graph_id: fire_wave       # ← ① 必须对上
entry: fire_wave          # ← ② 入口节点名也要对上
nodes:
  fire_wave:              # ← ③ 入口节点 node_id 还要对上
    ...

---

🗂️ 固定五大分类

skills/ 和 graphs/ 下都是同样的五个固定分类文件夹。技能放哪个文件夹，由它的 meta.category 决定，二者要一致：

分类	用途	典型技能
combat	战斗 / 输出 / 近战远程	火焰波、刃斩、反击
movement	位移 / 闪避	疾冲 dash
utility	增益 / 护盾 / 工具	护盾 shield
boss	Boss 专用技能	（按需自建）
combo	连招组合技	炎爆连舞

plugins/QinhSkills/
├── skills/
│   ├── combat/      fire_wave.yml  blade_slash.yml  retaliate.yml  …
│   ├── movement/    dash.yml
│   ├── utility/     shield.yml
│   ├── boss/
│   └── combo/       fire_combo_finisher.yml
└── graphs/
    ├── combat/      fire_wave.graph.yml  blade_slash.graph.yml  …
    ├── movement/    dash.graph.yml
    ├── utility/     shield.graph.yml
    ├── boss/
    └── combo/       fire_combo_finisher.graph.yml

⚠️ 技能文件和它的 graph 放在同名分类下。 combat 技能的 graph 就放 graphs/combat/。分类只影响归档与展示，不影响功能，但 meta.category 写错会在 /qs reload 时报 schema 警告。

💡 五个分类都合法（combat / movement / utility / combo / boss，源码枚举确有 BOSS），但自带示例里没有 boss 技能——上表中的 boss/ 目录需要你自己建，放进去的 boss 技能 meta.category 写 boss 即可。

---

🎓 自带示例：照着改最快

💡 上手最快的方式：直接看自带示例。 首次启动后，QS 会在 skills/ 下释放一组带详细注释的教学示例，每个都能开箱即用，照着改即可。

示例文件	它教你什么	难度
combat/fire_wave	最基础模板，先读它 —— 一个能放的主动技能长什么样	⭐
combat/blade_slash	自动索敌 + 血祭代价 + GCD + 释放条件 + 就绪提示 + 互斥组	⭐⭐⭐
combat/demo_slash	由 QinhItems 物品按键触发	⭐⭐
combat/demo_slash_charged	吟唱读条（蓄力条）	⭐⭐⭐
combat/retaliate	被动反击（受伤自动触发）	⭐⭐
movement/dash	充能层数 + 不吃 GCD	⭐⭐⭐
utility/shield	开关式技能（toggle）	⭐⭐
combo/fire_combo_finisher	连招：右 → 右 → 左	⭐⭐⭐⭐

建议的阅读顺序：先 fire_wave（看懂"一个技能的骨架"）→ 再 blade_slash（学进阶门控）→ 想做连招才看 fire_combo_finisher。

🔒 默认技能文件仅在缺失时释放，不会覆盖你的修改。 你改了 fire_wave.yml，下次重启 QS 也不会把它还原。想恢复出厂示例，把文件删掉再 /qs reload 即可。

💬 每个示例默认只发一条 [QinhSkills] 技能名 确认消息。想要真实火焰 / 伤害 / 粒子，去 plugins/MythicMobs/skills/ 写一个同名 MM 技能即可——QS 发现你已有同名技能就不再覆盖。详见 对接 MythicMobs。

---

📑 技能的"两套字段"

打开任意技能 yml，字段分成上下两半。这是 QS 的刻意设计，搞懂它能少踩大坑。

这套字段	作用	谁来读
上半：meta / trigger / state / graph / execution	生态信息 —— 分类归档、/qs reload 一致性校验、连招编排参照	schema 校验器
下半：type / cooldown / resource / cast_mode / levels…	运行期真正读取 —— 决定技能实际行为	运行时 loader

以 fire_wave 为例，上下两半指向同一个技能，必须保持一致：

# ===== 上半：生态信息（reload 时校验）=====
meta:
  category: combat            # 分类，要和文件所在文件夹一致
trigger:
  primary: RIGHT_CLICK        # 主触发键，要在 graph 入口节点 triggers 内
state:
  required: IDLE              # 所需状态，要和入口节点 require_state 一致
graph:
  entry: fire_wave            # 用哪张 graph
execution:
  mythic_skill: fire_wave     # 执行哪个 MM 技能，要和入口节点 mythic_skill 一致

# ===== 下半：运行期真正读取 =====
type: active                  # ← 真正决定主动/被动的是这一行
cooldown:
  base: 3000                  # ← 运行期实际用的冷却

⚠️ 两套必须一致。 /qs reload 会逐项校验，对不上报 schema 警告（不会让服务器崩，但技能行为可能不符预期）。常见对应关系：

• state.required ↔ 入口节点 require_state
• execution.mythic_skill ↔ 入口节点 mythic_skill
• trigger.primary ⊂ 入口节点 triggers（主触发键要被节点 triggers 包含）

为什么分两套？ 上半套让校验器、连招编排、未来的编辑器在"不跑技能"的情况下读懂技能长什么样；下半套是引擎运行时真正吃的配置。一个供"理解"，一个供"执行"。详细字段见 技能定义全字段。

---

🏷️ 命名规则

规则	说明
技能 id 全小写	id 缺省取文件名（去掉 .yml），建议直接用文件名当 id
四处同名	技能 graph.entry = graph graph_id = graph entry = 入口节点名，四者必须全部一致
graph 文件后缀	graph 文件必须以 .graph.yml 结尾，否则不被识别为图
别处引用都用 id	物品、连招、命令引用技能时，用的都是技能 id（不是显示名）
MM 技能同名	execution.mythic_skill 指向的 MM 技能名，建议和技能 id 同名，省得记两套

举例：一个 id 为 fire_wave 的战斗技能，标准三件套是——

skills/combat/fire_wave.yml         # id: fire_wave
graphs/combat/fire_wave.graph.yml   # graph_id: fire_wave, entry: fire_wave
MythicMobs/skills/...（技能名 fire_wave）   # 你自己写的真实效果

---

🔄 改完怎么生效（reload 循环）

改了文件不会自动生效，得手动重载。记住这三条对应关系：

你改了什么	执行什么命令
技能定义 skills/**.yml	/qs reload
graph 文件 graphs/**.graph.yml	/qs reload
MythicMobs 技能文件	/mm reload

# 改完技能或 graph
/qs reload

# 改完 MM 那侧的真实效果
/mm reload

💡 /qs reload 做三件事：重载技能定义 + graph + 路由，并同步 MM 桥。它还会跑上面说的"两套字段一致性校验"——重载后留意控制台有没有 schema 警告。

⚠️ MM 技能（粒子 / 伤害 / 位移）的修改归 /mm reload 管，/qs reload 不会帮你重载 MythicMobs。两边各管各的。

---

✅ 小结

• 一个技能 = skills/<分类>/xxx.yml（定义）+ graphs/<分类>/xxx.graph.yml（执行图），靠 graph.entry = graph_id = graph entry = 入口节点名（四处同名）挂钩。
• 五大固定分类：combat / movement / utility / boss / combo。
• 自带示例只在缺失时释放、不覆盖你的修改，从 fire_wave 读起。
• 技能 yml 上下两套字段（生态校验 vs 运行期读取）须保持一致，reload 时校验。
• 改技能 / graph → /qs reload；改 MM → /mm reload。

---

继续阅读

• 逐字段把技能配满 → 技能定义全字段
• 做连招 / 多段技 → graph 与连招
• 没搞懂"两套字段"的来龙去脉 → 核心概念
• 把技能接到物品上 → 对接总览