施法模式与吟唱

上一页：目标与索敌　·　下一页：消耗条件与变量

每个技能都有一个 施法模式（cast_mode），决定「按下触发」之后这个技能怎么放出来：

是按下立刻就放？
还是按一下开、再按一下关？
还是要先「读条」一段时间，读完才放、中途被打断就失败？

这三种行为分别对应三个值。本页一个一个拆，从最简单的瞬发讲到最复杂的吟唱读条。

🖼️ [图片占位] 三种施法模式对比图（瞬发 / 开关 / 吟唱读条）　·　建议 assets/cast-modes.png

🎯 三种施法模式一览

`cast_mode`	中文	行为	适合
`instant`	瞬发（默认）	按下即放，无读条	绝大多数技能：火球、突进、AOE
`toggle`	开关	每次触发在开 / 关之间翻转	持续光环、护盾、姿态、领域
`channel`	吟唱读条	读条满一段时间才生效，中途打断则失败	蓄力大招、传送、引导类

写法就是在技能 yml 顶层加一行：

yaml

cast_mode: instant        # 不写这一行也行，默认就是 instant

⚡ instant 瞬发（默认）

最常见、也是不写 cast_mode 时的默认行为。

按下即放，没有读条、没有延迟。
冷却、资源消耗、血祭、GCD……所有扣费在施放成功的那一刻立即扣。
门控（解锁 / 冷却 / 资源 / 条件…）没过，就直接拦下、什么都不扣。

yaml

id: fire_wave
display: "&c火焰波"
cast_mode: instant         # 可省略
cooldown:
  base: 3000               # 放出成功后立刻进 3 秒冷却
resource:
  mana: 15                 # 放出成功后立刻扣 15 法力

这一类技能不需要本页后面的内容，看到这里就够了。下面两种是进阶模式。

🔁 toggle 开关

「按一下开，再按一下关」的姿态 / 光环类技能。

它是怎么工作的

第一次触发 → QS 把状态翻成 on。
第二次触发 → QS 把状态翻成 off。
如此往复。

关键：QS 只维护「现在是开还是关」这个状态，并不处理开 / 关的实际效果。 QS 把当前状态作为变量 toggle_state（值为 "on" 或 "off"）传给 MythicMobs，由你的 MM 技能自己根据 toggle_state 决定「加护盾」还是「撤护盾」。

⚠️ 开关状态是内存态，存在 ToggleTracker 里。玩家重新登录（relog）会重置为 off，不持久化。

💡 toggle 的「冷却」是每次切换的冷却，不是「护盾持续多久」。每切换一次（无论开还是关）都走一遍冷却 + 消耗。持续效果由 MM 那边自己维持。

对应占位符：%qinhskills_<skill>_toggled%（true / false）。

完整示例：护盾 shield（自带示例，逐字照搬）

yaml

#==============================================================================
#  护盾 shield  ——  开关技能(toggle)：按一下开，再按一下关
#
#  这个示例教你：cast_mode: toggle —— 在"开/关"之间切换，不是放完就结束。
#  QS 会把当前开关状态作为变量 toggle_state(on/off) 传给 MythicMobs，
#  你的 MM 技能据此决定"加护盾"还是"撤护盾"。
#  触发：蹲+左键   ｜   类型：反应(reactive)   ｜   分类：utility
#
#  注意：toggle 的"冷却"是每次切换的冷却，不是护盾持续时间；持续效果由 MM 那边维持。
#==============================================================================

id: shield
display: "&e护盾"

meta:
  category: utility
  type: reactive                # reactive=反应型(防御/反制类)，只是归类标签；运行仍按下面顶层 type 走
trigger:
  primary: SHIFT_LEFT_CLICK
state:
  required: IDLE
graph:
  entry: shield
execution:
  mythic_skill: shield

type: active                    # 顶层是 active（loader 据此跑主动逻辑）；meta.type 的 reactive 只用于归类
max_level: 1
resource:
  mana: 20

cooldown:
  base: 6000                    # 每次"开/关"切换的冷却

cast_mode: toggle               # ★ 关键：开关模式。每次触发翻转 on/off，并把 toggle_state 传给 MM

MM 那侧怎么根据 toggle_state 分支

QS 传过来 toggle_state，MM 技能用 <skill.var.toggle_state> 读它。两种常见写法：

写法一：MM 条件判断（一个技能里分支）

yaml

# plugins/MythicMobs/skills/shield.yml
shield:
  Skills:
  # toggle_state == on → 加护盾
  - skill{s=ShieldOn} @Self ?check{var=toggle_state;value=on}
  # toggle_state == off → 撤护盾
  - skill{s=ShieldOff} @Self ?check{var=toggle_state;value=off}

写法二：拆成两个子技能（更清晰）

yaml

ShieldOn:
  Skills:
  - potion{type=ABSORPTION;duration=999999;level=2} @Self
  - particle{p=enchantmenttable;amount=40} @Self

ShieldOff:
  Skills:
  - removepotion{type=ABSORPTION} @Self

具体 ?check/变量语法以你的 MM 版本为准，这里只演示「按 toggle_state 分流」的思路。MM 接收 QS 变量的完整说明见对接 MythicMobs。

📿 channel 吟唱读条

「按下后要读条一段时间，读完才放、中途被打断就失败」的蓄力 / 引导类技能。

字段全表（`channel.*`）

字段	默认值	说明
`time_ticks`	—	读条时长（tick，20 = 1 秒）。必须 > 0 才进吟唱，否则退化成瞬发
`bar_type`	`bossbar`	读条 UI：`bossbar`（顶部血条，推荐）/ `actionbar`（下方文字）/ `none`（无内置 UI，交 BetterHud 读占位符自绘）
`interrupt_on_move`	`true`	位移打断
`move_threshold`	`0.5`	位移阈值（格），超过即打断；`0` = 任何位移都打断
`interrupt_on_damage`	`true`	受伤打断
`cost_on_start`	`false`	`false` = 完成时才扣资源（被打断不亏）；`true` = 起手即扣（防刷）
`cooldown_on_start`	`false`	`false` = 完成时才进 CD；`true` = 起手即进 CD

这些字段缺省时取 config.yml 里 channel.* 段的全局默认值；技能 yml 里逐项覆盖——你只写想改的几项即可，其余沿用全局默认。config.yml 默认值见配置文件。

吟唱完整流程

按下触发后，QS 按这个顺序走：

1. 门控（解锁/冷却/资源/条件… 含资源够不够的检查）
        ↓ 全过
2. 若 cost_on_start: true → 此刻扣资源
3. 若 cooldown_on_start: true → 此刻进冷却
        ↓
4. 启动 ChannelManager 倒计时（time_ticks）
        ↓ 每 tick 检查中断：
        · 位移 > move_threshold（开启 interrupt_on_move 时）
        · 受伤（开启 interrupt_on_damage 时）
        · 离线 / 死亡 / 换世界
        ↓
   ┌──────────────┬──────────────────────────┐
   │ 读条完成      │ 中途被打断                 │
   ├──────────────┼──────────────────────────┤
   │ 若未起手扣→现 │ 提示"§7[QS] §c吟唱被打断" │
   │ 在扣资源、进  │ 起手未扣→不扣；起手已扣→  │
   │ CD，fire()调 MM│ 已经亏了（这就是防刷代价）│
   └──────────────┴──────────────────────────┘

💡 怎么选 cost_on_start？ 想让玩家「被打断不亏」（更友好）就保持默认 false；想防止玩家反复起手骗资源 / 卡 CD（更硬核）就设 true。cooldown_on_start 同理。

读条期间的 UI 文案

bossbar：顶部血条文字 §e吟唱 §f{显示名} §7{百分比}%，血条随进度涨。
actionbar：屏幕下方带进度条 ▰▰▰▱▱。
none：QS 不画任何东西，只更新占位符，交给 BetterHud 等 HUD 插件自绘。

中断时统一提示：§7[QS] §c吟唱被打断。

对应占位符：

占位符	含义
`%qinhskills_<skill>_channeling%`	当前是否正在吟唱该技能（true/false）
`%qinhskills_<skill>_channel_progress%`	吟唱进度百分比

完整示例：演示蓄力斩 demo_slash_charged（自带示例，逐字照搬）

yaml

#==============================================================================
#  演示蓄力斩 demo_slash_charged  ——  吟唱读条技能(channel)
#
#  这个示例教你：cast_mode: channel —— 按下后要"读条"一段时间才放出，
#  读条期间被打断(移动/受伤)就失败。适合蓄力大招、传送、引导类技能。
#  触发：蹲+右键   ｜   类型：主动   ｜   分类：combat
#
#  读条进度默认走顶部 BossBar；想交给 BetterHud 自绘，把 bar_type 设 none 读占位符。
#  ⚙ 本技能也默认随服自带并自动解锁（config.yml unlock.starter_skills）。
#==============================================================================

id: demo_slash_charged
display: "&b演示蓄力斩"

meta:
  category: combat
  type: active
  rank: basic
trigger:
  primary: SHIFT_RIGHT_CLICK
state:
  required: IDLE
graph:
  entry: demo_slash_charged
execution:
  mythic_skill: demo_slash_charged

type: active
max_level: 1

cooldown:
  base: 3000
resource:
  mana: 10

cast_mode: channel              # ★ 关键：吟唱读条模式
channel:
  time_ticks: 40                # 读条时长：40 tick = 2 秒（20 tick = 1 秒）
  bar_type: bossbar             # 读条显示：bossbar 顶部血条(推荐) / actionbar 屏幕下方文字 / none 交给外部HUD
  interrupt_on_move: true       # 移动打断
  move_threshold: 0.5           # 位移超过 0.5 格才算"动了"（轻微卡动作不打断）
  interrupt_on_damage: true     # 受伤打断
  cost_on_start: false          # false=读条完成才扣资源(被打断不亏)；true=起手就扣(防刷)
  cooldown_on_start: false      # false=完成才进冷却；true=起手就进冷却

读条完成后，QS 才去 fire() 调用同名的 MM 技能 demo_slash_charged——所以 MM 那侧的写法和普通瞬发技能没有区别，吟唱逻辑全在 QS 这边处理完了。

⚠️ 常见坑

现象	原因
设了 `cast_mode: channel` 却秒放	`channel.time_ticks` 没写或写成 0 → 退化为瞬发。必须 > 0
toggle 技能重登后「关不掉」	状态是内存态，relog 重置为 off，再按一下重新进开关循环即可
吟唱一动就断	`move_threshold` 太小或设成 0；想容忍轻微卡动作就保持默认 0.5
玩家反复起手刷资源	设 `channel.cost_on_start: true` 起手即扣
toggle 的开 / 关效果不生效	QS 只传 `toggle_state`，实际效果要在 MM 那侧按它分支（见上文）

📚 继续阅读

消耗条件与变量 — 资源 / 血祭 / 声明式条件 / 变量透传 / 等级成长
冷却充能GCD与冲突 — 冷却、充能、GCD、冲突组怎么配
配置文件 — config.yml 里 channel.* 全局默认值
对接 MythicMobs — MM 怎么接收 toggle_state 等 QS 变量

施法模式与吟唱 ​

🎯 三种施法模式一览 ​

⚡ instant 瞬发（默认） ​

🔁 toggle 开关 ​

它是怎么工作的 ​

完整示例：护盾 shield（自带示例，逐字照搬） ​

MM 那侧怎么根据 toggle_state 分支 ​

📿 channel 吟唱读条 ​

字段全表（channel.*） ​

吟唱完整流程 ​

读条期间的 UI 文案 ​

完整示例：演示蓄力斩 demo_slash_charged（自带示例，逐字照搬） ​

⚠️ 常见坑 ​

📚 继续阅读 ​

施法模式与吟唱

🎯 三种施法模式一览

⚡ instant 瞬发（默认）

🔁 toggle 开关

它是怎么工作的

完整示例：护盾 shield（自带示例，逐字照搬）

MM 那侧怎么根据 toggle_state 分支

📿 channel 吟唱读条

字段全表（`channel.*`）

吟唱完整流程

读条期间的 UI 文案

完整示例：演示蓄力斩 demo_slash_charged（自带示例，逐字照搬）

⚠️ 常见坑

📚 继续阅读