Action Handlers In Depth
Belongs to: Action System · Related: Handler Reference · Triggers in Practice
The Handler Reference is a quick lookup table; this page expands each built-in handler one by one: the meaning of each payload field, the various ways to write it, and common pitfalls.
Syntax recap:
refs: - handler: <ID> / payload: <payload>, multiple refs execute in order.
qi:message —— Chat Message
payload: a single line of text, supporting MiniMessage and legacy & color codes.
- handler: qi:message
payload: "<gold>You triggered the skill!</gold>"
- handler: qi:message
payload: "&eLegacy colors work too"
- handler: qi:message
payload: "Welcome {player}" # {player} is replaced with the player name- Multiple lines: use multiple
qi:messagerefs, or embed a line break in the text and let the client handle it. - Pitfall: MiniMessage tags must be closed (
<gold>...</gold>).
qi:action_bar —— Action Bar (above the hotbar)
payload: a single line of text (MiniMessage). The first choice for brief prompts that won't spam the screen.
- handler: qi:action_bar
payload: "<aqua>◎ Charging…</aqua>"- Good for cooldown / status prompts; unlike
qi:messageit doesn't interrupt chat.
qi:title —— Screen Title
payload: title||subtitle||fadeIn||stay||fadeOut, separated by ||, time units × 50ms.
# All fields
- handler: qi:title
payload: "<gold>⚡ Thunder ⚡</gold>||<gray>The roar echoes</gray>||3||30||10"
# title subtitle fadeIn stay fadeOut
# Title only (the rest omitted)
- handler: qi:title
payload: "<red>Power Strike</red>"
# Title + subtitle, with default timing
- handler: qi:title
payload: "<gold>Victory</gold>||<gray>Defeated the Boss</gray>"
# Empty title + subtitle only
- handler: qi:title
payload: "||<gray>Subtitle only</gray>||5||20||5"- Time is in ticks (1 tick = 50ms):
3||30||10= fade in 0.15s, stay 1.5s, fade out 0.5s. - Pitfall: the separator is the double pipe
||, not a single pipe.
qi:subtitle —— Subtitle Only
payload: a single line of text. Equivalent to qi:title with an empty title.
- handler: qi:subtitle
payload: "<gray>Energy is gathering…</gray>"qi:sound —— Sound
payload: soundKey;volume;pitch, separated by ;.
- handler: qi:sound
payload: "minecraft:entity.lightning_bolt.thunder;1;1.2"
# sound namespaced key volume pitch
- handler: qi:sound
payload: "minecraft:block.amethyst_block.chime;1;1.4"
- handler: qi:sound
payload: "minecraft:entity.enderman.teleport;1;1"- Volume: 1 = normal, >1 increases the audible range; pitch: 0.5–2.0, high = sharp, low = deep.
- Pitfall: the separator is
;; the sound key uses the vanilla sound resource name.
qi:bossbar —— Boss Bar
payload: text;progress;color;style;durationTick.
- handler: qi:bossbar
payload: "<red>Charging</red>;0.5;RED;PROGRESS;40"
# text progress color style duration(tick)- Progress: 0.0–1.0.
- Color:
PINK/BLUE/RED/GREEN/YELLOW/PURPLE/WHITE. - Style:
PROGRESS(solid) /6/10/12/20(segmented). - Duration: ticks, disappears automatically when it expires.
qi:command —— Run a Command as the Player
payload: command text, without /, supports {player}.
- handler: qi:command
payload: "spawn" # back to spawn
- handler: qi:command
payload: "effect give {player} minecraft:strength 20 1"
- handler: qi:command
payload: "warp pvp"- Runs with player permissions; commands the player lacks permission for will not succeed.
- Pitfall: don't write
/;{player}is the name of the currently triggering player.
qi:console_command —— Run a Command as Console
payload: command text, without /, supports {player}.
- handler: qi:console_command
payload: "give {player} diamond 1"
- handler: qi:console_command
payload: "lp user {player} permission settemp vip.fly true 1h"- Runs with console permissions, suitable for operations that require high privileges (granting permissions, cross-player actions).
- ⚠️ Security: the payload comes from item configuration; never let player-controllable content get spliced into the command.
qi:give_item —— Give an Item
payload: an item source reference (a QI item ID or an external source reference).
- handler: qi:give_item
payload: "demo_heal_potion" # give a QI item
- handler: qi:give_item
payload: "ce-wooden_axe" # external item source reference- When the inventory is full, handled per the
give-overflow-dropconfig.
qi:close_inventory —— Close Container
payload: empty.
- handler: qi:close_inventory
payload: ""- Often paired with a GUI-opening flow, or as a wrap-up when an action ends.
combat:swing —— Swing Attack
payload: light or heavy (default light).
- handler: combat:swing
payload: "light"
- handler: combat:swing
payload: "heavy"- Acquires a target within 5 blocks and fires
QinhCombatSwingEvent; when vanilla-hit is enabled it callsplayer.attack(target), otherwiseswingMainHand(). - Requires
combat.enabled: true. See Attributes and Stats.
qinhskills:cast —— Cast a QinhSkills Skill
payload: JSON {"skill":"skillID","level":level}.
- handler: qinhskills:cast
payload: '{"skill":"fireball","level":1}'- Requires QinhSkills installed; QI passes the request through to QS, and the actual casting happens in QS / MythicMobs.
- In a set's
abilities, the handler must use the map form (with a colon), see Sets. - See Integration.
Combined Example: Chaining Multiple Handlers in One Action
refs:
- handler: qi:title
payload: "<gold>Awaken</gold>||<gray>Power Awakening</gray>||5||30||10"
- handler: qi:sound
payload: "minecraft:block.beacon.activate;1;1"
- handler: qi:command
payload: "effect give {player} minecraft:strength 30 2"
- handler: qi:action_bar
payload: "<red>Strength +2, lasts 30 seconds</red>"Executes in order: title → sound → give buff → action bar prompt.
Want an Effect Outside the List?
Develop a custom handler: implement QinhActionHandler, write the logic in code, and reference it from YAML. This is the only proper way to bring if/switch/state checks into an action (YAML cannot express logic).
Next Steps
- Handler Reference: quick lookup table
- Triggers in Practice: triggers + handler combinations
- Action Handler Development