Cooldown / Cost / Conditions / Combos

Belongs to: Action System　·　Related: Triggers · Handlers

This page covers the four "gates" of a trigger: cooldown, consume (cost), conditions, and sequence (combo). Together they decide whether an action can fire and what price it costs.

---

1. Cooldown

left_click:
  trigger: { atom: left_click }
  cooldown: 2s

Duration syntax

Syntax	Milliseconds
2s	2000
500ms	500
1.5s	1500
2m	120000
20t	1000 (20 ticks × 50)
Bare number 3000	Treated as seconds (= 3000 seconds, beware!)

• Cooldown is tracked per player × item × trigger, keyed by playerId|itemId|trigger.
• Use group: to make multiple triggers share a cooldown group.
• Cooldown lives in memory (lost on restart).
• Triggering while on cooldown: by default the player is notified (actions.notify-cooldown: true in config.yml).

---

2. Cost (consume)

Deducts resources on trigger, listed under consume:

consume:
  - "item:diamond:1"            # Deduct 1 diamond
  - "item:minecraft-redstone:2" # With namespace, deduct 2 redstone
  - "self:1"                    # Deduct 1 of this item (stack -1)
  - "level:5"                   # Deduct 5 experience levels

Format	Meaning
item:material[:amount]	Deduct a vanilla material from the inventory, defaults to 1
self[:amount]	Deduct from this item's own stack
level:amount	Deduct experience levels

Mechanism: before triggering, canAfford() is checked; if resources are insufficient, the action does not fire. The actual deduction only happens after the action succeeds (a handler returns HANDLED).

---

3. Conditions

The action fires only when all conditions are true, listed under conditions:

conditions:
  - "player_level:>=10"
  - "player_in_world:world_name"
  - "item_material:diamond_sword"

Format is prefix:operand, where the operand may include a comparison operator >= / <= / == / != / > / <.

Built-in condition table

Condition	Operand	Example
player_has_permission	Permission name	player_has_permission:admin.ban
player_in_world	World name	player_in_world:world
player_level	op number	player_level:>=10
player_health	op number	player_health:>50
player_food	op number	player_food:>=5
player_gamemode	Mode	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	Material	player_has_item:diamond
item_durability	op number	item_durability:>=10
item_count	op number	item_count:>1
item_material	Material	item_material:diamond_sword
item_name	Substring (case-insensitive)	item_name:special
item_enchanted	Enchantment key	item_enchanted:sharpness
item_unbreakable	true/false	item_unbreakable:true
item_damage	op number	item_damage:<5
variable	variable op value	variable:my_var>=100
cooldown_ready	Cooldown group name (may be empty)	cooldown_ready:my_group
cooldown_remaining	group:thresholdMs	cooldown_remaining:my_group:2000
tag	Tag name	tag:my_tag

⚠️ Conditions can only do these preset checks; you cannot write arbitrary logic expressions. For complex checks, develop a handler and decide in code.

---

4. Sequence Combos and Double-Tap

Sequence combo

whirlwind:
  trigger:
    sequence:
      - sneak_down
      - left_click
      - left_click
    window: 500            # Max interval between steps (ms), defaults to 450
  cooldown: 5s
  refs:
    - handler: qi:message
      payload: "Whirlwind Slash!"

The player must complete each step in order within the window. State is tracked by TriggerSequenceTracker.

Double-tap sneak (double_shift_toggle)

dash:
  trigger:
    atom: double_shift_toggle    # Aliases double_sneak / double_sneak_toggle
  cooldown: 3s
  refs:
    - handler: qi:message
      payload: "Dash!"

Fixed 450ms window (SneakDoubleTapTracker).

Debounce

ActionTriggerDedup has a 120ms dedup window to prevent a single action from triggering multiple times.

---

5. Tick periodic trigger

regen_aura:
  trigger:
    atom: tick
  tick: 40                 # Triggers once every 40 ticks (2 seconds)
  refs:
    - handler: qi:command
      payload: "effect give {player} minecraft:regeneration 2 0"

Driven by TickHandTicker (scheduled every 20 ticks), applied to held / equipped items.

---

6. Notification config

config.yml:

actions:
  notify-cooldown: true              # Notify the player when triggering on cooldown
  notify-handler-unavailable: true   # Notify when a handler is unavailable

---

Next step

• Triggers: all trigger atoms
• Handlers: all action handlers
• Action Handler Development: custom logic