冷却 / 消耗 / 条件 / 连招
本页讲触发器的四个「闸门」：冷却（cooldown）、消耗（consume）、条件（conditions）、连招（sequence）。它们共同决定一个动作能不能 / 要付什么代价触发。
1. 冷却 cooldown
yaml
left_click:
trigger: { atom: left_click }
cooldown: 2s时长语法
| 写法 | 毫秒 |
|---|---|
2s | 2000 |
500ms | 500 |
1.5s | 1500 |
2m | 120000 |
20t | 1000（20 tick × 50） |
裸数字 3000 | 当作秒（= 3000 秒，注意！） |
- 冷却是按 玩家 × 物品 × 触发器 计的，键
playerId|itemId|trigger。 - 可用
group:让多个触发器共享冷却组。 - 冷却存在内存（重启丢失）。
- 在冷却中触发：默认会给玩家提示（
config.yml的actions.notify-cooldown: true）。
2. 消耗 consume
触发时扣资源，放在 consume 列表：
yaml
consume:
- "item:diamond:1" # 扣 1 颗钻石
- "item:minecraft-redstone:2" # 带命名空间，扣 2 红石
- "self:1" # 扣 1 个本物品（堆叠 -1）
- "level:5" # 扣 5 级经验| 格式 | 含义 |
|---|---|
item:材质[:数量] | 从背包扣原版材质，默认 1 |
self[:数量] | 扣本物品自身堆叠 |
level:数量 | 扣经验等级 |
机制：触发前检查 canAfford()，资源不足则不触发；动作成功（有处理器 HANDLED）后才真正扣除。
3. 条件 conditions
全部条件为真才触发，放在 conditions 列表：
yaml
conditions:
- "player_level:>=10"
- "player_in_world:world_name"
- "item_material:diamond_sword"格式 前缀:操作数，操作数可带比较符 >= / <= / == / != / > / <。
内置条件表
| 条件 | 操作数 | 例 |
|---|---|---|
player_has_permission | 权限名 | player_has_permission:admin.ban |
player_in_world | 世界名 | player_in_world:world |
player_level | 符 数 | player_level:>=10 |
player_health | 符 数 | player_health:>50 |
player_food | 符 数 | player_food:>=5 |
player_gamemode | 模式 | player_gamemode:SURVIVAL |
player_flying | true/false | player_flying:true |
player_sneaking | true/false | player_sneaking:false |
player_sprinting | true/false | player_sprinting:true |
player_gliding | true/false | player_gliding:false |
player_has_item | 材质 | player_has_item:diamond |
item_durability | 符 数 | item_durability:>=10 |
item_count | 符 数 | item_count:>1 |
item_material | 材质 | item_material:diamond_sword |
item_name | 子串（忽略大小写） | item_name:special |
item_enchanted | 附魔键 | item_enchanted:sharpness |
item_unbreakable | true/false | item_unbreakable:true |
item_damage | 符 数 | item_damage:<5 |
variable | 变量 符 值 | variable:my_var>=100 |
cooldown_ready | 冷却组名（可空） | cooldown_ready:my_group |
cooldown_remaining | 组:阈值ms | cooldown_remaining:my_group:2000 |
tag | 标签名 | tag:my_tag |
⚠️ 条件只能做这些预设判断，不能写任意逻辑表达式。需要复杂判断请开发处理器在代码里判。
4. 序列连招与双击
序列连招 sequence
yaml
whirlwind:
trigger:
sequence:
- sneak_down
- left_click
- left_click
window: 500 # 步间最大间隔（毫秒），默认 450
cooldown: 5s
refs:
- handler: qi:message
payload: "旋风斩！"玩家须在窗口内按顺序完成各步。状态由 TriggerSequenceTracker 跟踪。
双击潜行 double_shift_toggle
yaml
dash:
trigger:
atom: double_shift_toggle # 别名 double_sneak / double_sneak_toggle
cooldown: 3s
refs:
- handler: qi:message
payload: "冲刺！"固定 450ms 窗口（SneakDoubleTapTracker）。
防抖
ActionTriggerDedup 有 120ms 去重窗口，避免一次操作触发多次。
5. tick 周期触发
yaml
regen_aura:
trigger:
atom: tick
tick: 40 # 每 40 tick（2 秒）触发一次
refs:
- handler: qi:command
payload: "effect give {player} minecraft:regeneration 2 0"由 TickHandTicker（每 20 tick 调度）驱动，作用于手持 / 装备的物品。
6. 通知配置
config.yml：
yaml
actions:
notify-cooldown: true # 冷却中触发时提示玩家
notify-handler-unavailable: true # 处理器不可用时提示