被动技能（passive）

上一页：触发器　·　下一页：目标与索敌

被动技能 = 玩家不用按键，满足条件就自动触发的技能。受伤时反弹荆棘、击杀回血、低血时狂暴、每秒掉一层 buff…… 全靠被动。

💡 一句话分工：QS 判定「什么时候触发」，MythicMobs 决定「触发了放出来啥」。 被动也必须在 MM 侧写一个同名技能才有真实表现，否则只会发一条占位消息。

🖼️ [图片占位] 一张「玩家挨打 → ON_DAMAGED 事件 → QS 触发 retaliate → MM 反弹伤害给攻击者」的示意图　·　建议 assets/passive-retaliate.png

一、被动技能怎么写（总览）

被动只比主动多三件事，少一件事：

多：顶层 type: passive、meta.type: passive（两处都要写）。
多：passive_triggers 列表，列出「什么事件触发它」。
多：高频事件要配 cooldown_ms 限流。
少：trigger.primary 可以不写——1.0.16 起 schema 会自动按 PASSIVE 处理（写了也行，不写更省事）。

yaml

type: passive                    # ★ 真正决定它是被动的就是这一行
meta:
  type: passive                  # meta 里也要写 passive
passive_triggers:                # 被动触发清单（可多条，命中任意一条就触发）
  - type: ON_ATTACK              # 攻击命中时
    id: retaliate
    cooldown_ms: 0               # 限流：0=不限流；高频事件务必给非 0 值
  - type: ON_LOW_HEALTH          # 血量跌破阈值时
    id: last_stand
    threshold_pct: 30            # 血量百分比阈值（0-100），默认 30，每技能独立

每条 passive_triggers 由三部分构成：

字段	必填	含义
`type`	✅	触发类型（下表 11 种之一）
`id`	✅	这条触发的标识（用于区分多条触发）
`cooldown_ms`	可选	限流：该触发在此毫秒内最多放一次（默认 0=不限流）
`threshold_pct`	可选	仅 `ON_LOW_HEALTH` 用：血量百分比阈值，默认 30

⚙ 被动默认不自动解锁。测试前先 /qs unlock <技能>，再去触发条件试效果。

二、11 种被动触发类型

由 PassiveTriggerListener 驱动。按用途分三组：

战斗类

type	驱动事件	含义	传入 MM 的目标	需限流
`ON_DAMAGED`	EntityDamageEvent	受到伤害时	—	⚠️ 强烈建议
`ON_ATTACK`	玩家作为 damager	攻击命中时	被击者作 `@Target` / `@Trigger` 传入	视频率而定
`ON_KILL`	EntityDeathEvent	击杀生物时	死亡实体作目标	一般不需要
`ON_LOW_HEALTH`	血量边沿	血量跌破阈值时触发一次	—	边沿自带防刷

行为类

type	触发时机	含义	需限流
`ON_SNEAK`	开始潜行	潜行时	⚠️ 强烈建议
`ON_JUMP`	跳跃	跳跃时（高频）	⚠️ 必须
`ON_SPRINT`	开始疾跑	疾跑时	建议
`ON_BLOCK_BREAK`	挖掘方块	挖掘时（高频）	⚠️ 必须
`ON_RESPAWN`	重生	死亡重生后	不需要
`ON_FALL`	FALL 伤害	坠落受到摔伤时	视情况

周期类

type	驱动	含义	需限流
`TICK`	`passive.tick_interval_ticks`（config.yml，默认 20 tick = 1 秒）	每隔固定时间触发一次	⚠️ 极易刷屏，必须靠技能 cooldown 或 cooldown_ms 限流

💡 TICK 不开销空转：当没有任何技能用到 TICK 被动时，周期任务会自动空转，不产生额外性能开销。只有真有 TICK 被动时它才工作。

三、ON_LOW_HEALTH 的边沿语义（重点讲清）

很多人以为「低血触发」= 只要血量低就一直触发——不是。ON_LOW_HEALTH 是边沿触发，用 lowHealthLatch 追踪状态：

规则：当 血量百分比 ≤ threshold_pct（源码用 <=，正好等于阈值也算）且该技能尚未闩锁时，触发一次并记入闩锁；之后哪怕继续受伤掉血也不再触发；直到血量回到 > threshold（严格高于阈值）才解除闩锁，下次再跌破才会再触发。

⚙ 边沿/闩锁(latch)细节：玩家受伤和回血时都会安排一次低血检查——不是只在受伤时查。受伤把血压到 ≤ threshold 会触发并上锁；回血把血拉回 > threshold 会解锁（但回血本身不触发）。靠这把闩锁，一条命里跌破一次只放一次，不会每次受伤都刷。

一句话：血量 ≤ 阈值%（含正好等于）触发一次，回血严格超过阈值才重置。

yaml

passive_triggers:
  - type: ON_LOW_HEALTH
    id: last_stand
    threshold_pct: 30            # 血量 ≤ 30% 时触发（每技能独立设置，0-100）

举个例子（阈值 30%）：

时刻	血量变化	是否触发	说明
①	100% → 35%	❌	还没跌破 30%
②	35% → 25%	✅ 触发一次	跨过阈值的那一刻
③	25% → 10%	❌	已经在阈值下，不重复触发
④	10% → 50%	❌	回血超过阈值，闩锁重置（但回血本身不触发）
⑤	50% → 20%	✅ 再触发一次	重置后再次跌破

这正是「濒死狂暴 / 保命大招」想要的语义——一条命里跌破一次只放一次，不会在挨连击时疯狂刷。

四、高频被动 = 必须限流（务必读）

下面这几种触发频率极高，不限流会在短时间内连发刷爆（消息刷屏、MM 技能连放）：

⚠️ ON_DAMAGED / ON_JUMP / ON_BLOCK_BREAK / ON_SNEAK 务必配 cooldown_ms 限流。 TICK 同理，靠技能 cooldown 或 cooldown_ms 压住频率。

yaml

passive_triggers:
  - type: ON_BLOCK_BREAK
    id: mining_buff
    cooldown_ms: 3000            # ★ 3 秒内最多触发一次，否则连挖一片石头会刷爆

两种限流手段（可叠加）：

每条触发的 cooldown_ms：精确到「这一条触发」，推荐。
技能级 cooldown.base：整个技能的冷却，对所有触发生效。

⚙ 结算时机：高频被动事件（ON_DAMAGED / ON_ATTACK / ON_KILL / ON_BLOCK_BREAK 等）QS 已统一安排在 MONITOR 时机之后才结算（避开被其它插件取消的事件），这部分服主无需操心。你唯一要做的就是给这些高频被动配 cooldown_ms 限流。

五、TICK 周期配置

TICK 的间隔由 config.yml 统一控制，所有 TICK 被动共用这个节拍：

yaml

# config.yml
passive:
  tick_interval_ticks: 20        # TICK 被动的触发间隔（tick，20 = 1 秒）
                                 # 无 TICK 被动技能时任务自动空转，不开销

yaml

# 技能里：每秒（随上面节拍）触发一次的周期被动
type: passive
meta: { type: passive }
passive_triggers:
  - type: TICK
    id: regen_aura
    cooldown_ms: 1000            # 即便节拍 1 秒，也建议再加 cooldown_ms 双保险

六、复现：retaliate.yml（被动技能的标准范例）

这是 QS 自带的被动示例 skills/combat/retaliate.yml，照抄即可：

yaml

#==============================================================================
#  荆棘反击 retaliate  ——  被动技能：受到攻击时自动反击
#==============================================================================

id: retaliate
display: "&c荆棘反击"

meta:
  category: combat
  type: passive                 # 被动：两处 type 都要写 passive
state:
  required: IDLE
graph:
  entry: retaliate
execution:
  mythic_skill: retaliate
# 被动技能可以不写 trigger.primary —— schema 会自动按 PASSIVE 处理

type: passive                   # ★ 真正决定它是被动的就是这一行
max_level: 1

cooldown:
  base: 0                       # 技能级冷却；被动限流更推荐用每条触发各自的 cooldown_ms

# 被动触发清单：可写多条，命中任意一条就触发本技能
passive_triggers:
  - type: ON_DAMAGED            # 受到伤害时
    id: thorns
    cooldown_ms: 1500           # ★ 限流：1.5 秒内最多触发一次，避免被连击时反击刷屏

注意：该示例用 ON_DAMAGED。若想让「攻击者」作为目标被反击，可改用 ON_ATTACK，把攻击者作 @Trigger 传给 MM（见下节）。

七、MM 侧如何接被动（@Trigger / @Target）

被动只是「触发器」，真实表现要去 MythicMobs 写同名技能。关键在怎么拿到「触发对象」：

ON_ATTACK：被击者作为 @Target / @Trigger 传入。
ON_KILL：死亡实体作为目标传入。
想让攻击者挨反击：用 ON_ATTACK，在 MM 里对 @Trigger 结算伤害。

yaml

# plugins/MythicMobs/skills/ 下的同名技能 retaliate
retaliate:
  Skills:
    - damage{amount=4} @Trigger          # 对触发对象（攻击者）造成伤害
    - particles{p=crit;amount=20} @Trigger

一条铁律贯穿生态：QS 不内置伤害数值。damage{} 的数值最终由 AttributePlus 等属性插件在 MM 那侧结算。

八、被动常见坑

现象	原因	解法
被动完全不触发	没解锁	`/qs unlock <技能>`
被动只发占位消息没特效	MM 没写同名技能	在 MM 侧补 `retaliate` 技能
跳跃 / 挖掘时疯狂刷屏	高频触发没限流	给该触发加 `cooldown_ms`
低血技能每次受伤都放	误以为是阈值触发	它是边沿触发，符合预期；想改频率调 `threshold_pct`
`type` 只写了一处	meta 与顶层须都写 passive	两处都补 `type: passive`
MM 里 `@Trigger` 拿不到攻击者	用了 `ON_DAMAGED`	改用 `ON_ATTACK`

继续阅读

下一页：目标与索敌 —— 主动技能怎么锁目标（被动的目标由触发事件给定）。
触发器 —— PASSIVE 与其它 TriggerType 的关系。
冷却充能GCD与冲突 —— cooldown 各字段细节。
对接 MythicMobs —— MM 侧同名技能与变量接收。

被动技能（passive） ​

一、被动技能怎么写（总览） ​

二、11 种被动触发类型 ​

战斗类 ​

行为类 ​

周期类 ​

三、ON_LOW_HEALTH 的边沿语义（重点讲清） ​

四、高频被动 = 必须限流（务必读） ​

五、TICK 周期配置 ​

六、复现：retaliate.yml（被动技能的标准范例） ​

七、MM 侧如何接被动（@Trigger / @Target） ​

八、被动常见坑 ​

继续阅读 ​

被动技能（passive）

一、被动技能怎么写（总览）

二、11 种被动触发类型

战斗类

行为类

周期类

三、ON_LOW_HEALTH 的边沿语义（重点讲清）

四、高频被动 = 必须限流（务必读）

五、TICK 周期配置

六、复现：retaliate.yml（被动技能的标准范例）

七、MM 侧如何接被动（@Trigger / @Target）

八、被动常见坑

继续阅读