Skip to main content

Actions

Actions are commands executed when a player interacts with a button. zMenu provides 30+ action types for various purposes.

Basic Usage​

items:
  my-button:
    slot: 0
    item:
      material: DIAMOND
    actions:
      - type: message
        messages:
          - "&aHello, %player%!"
      - type: sound
        sound: UI_BUTTON_CLICK

Common Options​

All actions support the following optional parameters:

delay​

Add a delay (in ticks) before the action is executed. 20 ticks = 1 second.

actions:
  - type: refresh
    delay: 10  # Wait 10 ticks before refreshing

chance​

Set a percentage chance for the action to execute. Combined with deny-chance-actions to define fallback actions when the chance fails.

actions:
  - type: console-command
    commands:
      - "give %player% diamond 1"
    chance: 50  # 50% chance to execute
    deny-chance-actions:  # Actions to execute if chance fails
      - type: message
        messages:
          - "&cNo luck this time!"

Options:

OptionTypeDescription
delayIntegerDelay in ticks before execution (20 ticks = 1 second)
chanceIntegerPercentage chance (0-100) for the action to execute
deny-chance-actionsListActions to execute if the chance check fails

Example with both options:

actions:
  - type: refresh
    delay: 20  # Wait 1 second
    chance: 75  # 75% chance
    deny-chance-actions:
      - type: message
        messages:
          - "&cThe refresh failed!"

Message Actions​

- type: message
  messages:
  - "&aLine 1"
  - "&bLine 2"
  minimessage: true  # Optional: Use MiniMessage format default: true

message-to​

Send a message to a specific player.

- type: message-to
  target-player: "Notch"
  messages:
    - "&aHello from %player%!"

broadcast​

Send a message to all online players.

- type: broadcast
  messages:
    - "&6[Announcement] &f%player% purchased a special item!"
  minimessage: true  # Optional: Use MiniMessage format (default: true)

broadcast-message​

Send a list of chat lines to every online player.

- type: broadcast_message
  messages:
    - "&6[Shop] &f%sender% &7just bought a rank!"
  minimessage: true # Optional, default: true

Options:

OptionTypeRequiredDescription
messagesListYesThe lines sent to every online player. Must be written as a YAML list.
minimessageBooleanNoParse each line as MiniMessage. Default true. Set to false to send it as-is. Alias: mini-message.

Placeholders: %sender% is replaced by the name of the player who triggered the action, %receiver% by the name of each player receiving the line.

Difference with broadcast

broadcast_message resolves its placeholders once, for the player who triggered it, then sends that same result to everyone — only %receiver% varies. broadcast resolves them again for each recipient and supports a requirements list to filter who receives the message.

Use broadcast when the text must differ per recipient or be filtered, broadcast_message for a plain announcement about the player who clicked.

warning

Unlike the message action, the singular message key and a single inline string are not accepted: messages must be a YAML list. %player% substitution and \n line splitting are not applied either.

action-bar​

Display an action bar message.

- type: action
  message: "&aWelcome to the shop!"

title​

Display a title and subtitle.

- type: title
  title: "&6&lWelcome!"
  subtitle: "&7Enjoy your stay"
  start: 20      # Ticks
  duration: 60   # Ticks
  end: 20        # Ticks

broadcast-title​

Display a title and a subtitle to every online player at once. It takes the same options as title, which only targets the clicking player.

- type: broadcast_title
  title: "&6&lEVENT"
  subtitle: "&7Started by &f%player%"
  start: 20      # Ticks
  duration: 60   # Ticks
  end: 20        # Ticks

Options:

OptionTypeRequiredDescription
titleStringYesThe title line. See the warning below.
subtitleStringYesThe subtitle line. See the warning below.
startNumberNoFade-in duration, in ticks. Default 0.
durationNumberNoTime the title stays on screen, in ticks. Default 0.
endNumberNoFade-out duration, in ticks. Default 0.

Placeholders are resolved once, for the player who triggered the action, so %player_name% refers to that player and not to each recipient — which is usually what an announcement wants.

Always write both lines, and all three timings

title and subtitle have no default value: omitting one sends the literal text null to every player. The three timings default to 0, which makes the title appear and disappear immediately on most clients. Set them explicitly, as in the examples above.

change-title​

Change the inventory title.

Requires PacketEvents

This action is only available when the PacketEvents plugin is installed on your server. Without it, the action is simply not registered and will silently do nothing.

- type: change-title
  inventory-name: "My New Inventory Title"

Options:

OptionTypeRequiredDescription
inventory-nameStringYesThe new inventory title to display

Available aliases: change-title, change-title-name.

toast​

Display a toast notification (achievement popup).

- type: "toast"
  material: DIAMOND       # Material for the toast icon (default: PAPER)
  message: "&aAchievement Unlocked!"
  toast-type: CHALLENGE   # TASK, GOAL, or CHALLENGE (default: CHALLENGE)
  model-id: "0"          # Optional: custom model data
  glowing: false         # Optional: glowing effect (default: false)

Options:

OptionTypeDefaultDescription
materialStringPAPERMaterial for the toast icon
messageStringDefault messageThe toast notification text
toast-typeStringCHALLENGEToast frame style: TASK, GOAL, or CHALLENGE
model-idString0Custom model data for the icon item
glowingBooleanfalseWhether the icon item has a glowing effect

Sound Actions​

sound​

Play a sound to the player.

- type: sound
  sound: ENTITY_EXPERIENCE_ORB_PICKUP
  pitch: 1.0    # 0.5 to 2.0
  volume: 1.0   # Distance
  sound-category: MASTER  # Optional sound category

Common Sounds:

  • UI_BUTTON_CLICK
  • ENTITY_EXPERIENCE_ORB_PICKUP
  • ENTITY_PLAYER_LEVELUP
  • ENTITY_VILLAGER_YES
  • ENTITY_VILLAGER_NO
  • BLOCK_NOTE_BLOCK_PLING
  • BLOCK_CHEST_OPEN
  • BLOCK_CHEST_CLOSE
Sound Reference

View the complete list of available sounds in the Bukkit Sound JavaDocs.

broadcast-sound​

Play a sound to all online players.

- type: broadcast_sound
  sound: ENTITY_ENDER_DRAGON_DEATH
  pitch: 1.0
  volume: 1.0
  sound-category: MASTER # Optional

Command Actions​

player-command​

Execute a command as the player.

- type: player-command
  commands:
    - "spawn"
    - "kit starter"
  command-in-chat: false  # Optional: execute via chat instead of dispatch (default: false)

player-command-as-op​

Execute a command as the player with OP permissions.

- type: player-command-as-op
  commands:
    - "gamemode creative"
warning

Use with caution! This gives the player temporary OP-level access.

You need to enable it in the configuration file:

enable-player-commands-as-op-action: true

console-command​

Execute a command from the console.

- type: console-command
  commands:
    - "give %player% diamond 64"
    - "eco give %player% 1000"

Stopping a chain that failed

By default every command in the list runs, whatever the previous ones did. With stop-on-failure enabled, the first command that reports a failure stops the ones after it — so a chain such as "take the money" followed by "grant the rank" can no longer grant the rank when the charge failed.

- type: console-command
  stop-on-failure: true
  commands:
    - "eco take %player% 1000"
    - "lp user %player% parent add vip"
Why it is off by default

Bukkit returns a failure both for a command that does not exist and for a command whose executor returned false — which many plugins do simply to print their usage. Enabling this option blindly can therefore stop a chain that was working. Test each chain before turning it on.

chat​

Force the player to send a chat message.

- type: chat
  messages:
    - "Hello everyone!"

Options:

OptionTypeRequiredDescription
messagesListYesThe list of messages for the player to send

random-player-command​

zMenu+

This action requires zMenu+.

Execute a random selection of commands as the player from a list. The commands are selected without replacement (no duplicates in a single execution).

- type: random_player_command
  commands:
    - "say I got option 1!"
    - "say I got option 2!"
    - "say I got option 3!"
    - "say I got option 4!"
  amount: 1               # Number of commands to randomly execute (default: 1)
  command-in-chat: false   # Optional: execute via chat instead of dispatch (default: false)

Options:

OptionTypeDefaultDescription
commandsListRequiredList of commands to randomly select from
amountInteger1Number of random commands to execute
command-in-chatBooleanfalseIf true, sends via player.chat(); if false, dispatches as command

Aliases: random_player_command, random_player_commands, random-player-command, random-player-commands

random-console-command​

zMenu+

This action requires zMenu+.

Execute a random selection of console commands from a list. The commands are selected without replacement (no duplicates in a single execution). Supports the %player% placeholder.

- type: random_console_command
  commands:
    - "give %player% diamond 1"
    - "give %player% emerald 1"
    - "give %player% gold_ingot 1"
    - "give %player% iron_ingot 1"
  amount: 2    # Execute 2 random commands from the list

Options:

OptionTypeDefaultDescription
commandsListRequiredList of console commands to randomly select from
amountInteger1Number of random commands to execute

Aliases: random_console_command, random_console_commands, random-console-command, random-console-commands, random-command, random-commands

Inventory Actions​

inventory​

Open another inventory.

- type: inventory
  inventory: "shop"
  page: 1          # Optional: specific page
  arguments:       # Optional: pass arguments
    - "arg1"

close​

Close the current inventory.

- type: close

back​

Go back to the previous inventory.

- type: back

refresh​

Refresh the current button.

- type: refresh

refresh-inventory​

Refresh the entire inventory (redraw all buttons).

- type: refresh-inventory

Player Actions​

teleport​

Teleport the player to coordinates.

- type: teleport
  world: "world"
  x: 0
  y: 100
  z: 0
  yaw: 0       # Optional
  pitch: 0     # Optional

connect​

Connect the player to another server (BungeeCord/Velocity).

- type: connect
  server: "lobby"

Data Actions​

data​

Modify player data values.

- type: data
  action: SET       # SET, ADD, SUBTRACT, MULTIPLY, DIVIDE, REMOVE
  key: "coins"
  value: "100"
  math: true        # Optional: enable math expressions

Options:

OptionTypeDescription
actionStringThe operation to perform (see table below)
keyStringThe player data key to operate on
valueStringThe value to use (supports placeholders)
mathBooleanEnable math expression evaluation in value (default: false)
secondsLongIf set, store the value for only this many seconds before it expires

Actions:

ActionDescriptionExample
SETSet to specific valuevalue: "100"
ADDAdd to current valuevalue: "50"
SUBTRACTSubtract from currentvalue: "25"
MULTIPLYMultiply current valuevalue: "2"
DIVIDEDivide current valuevalue: "2"
REMOVERemove the key entirely-

Math expressions:

- type: data
  action: ADD
  key: "total"
  value: "%zmenu_player_value_base%*1.5"
  math: true

Temporary data (expires after N seconds):

- type: data
  action: SET
  key: "cooldown"
  value: "1"
  seconds: 86400   # Expires after 24 hours

Economy Actions​

deposit​

Add money to player's balance.

- type: deposit
  currency: "vault"  # Optional: specify currency plugin
  #economy:   # When a economy plugin allows multiple currencies, you can specify which one to use.
  amount: 50
  reason: "Purchase"  # Optional

See the full list of supported currencies here.

withdraw​

Remove money from player's balance.

- type: withdraw
  currency: "vault"  # Optional: specify currency plugin
  #economy:   # When a economy plugin allows multiple currencies, you can specify which one to use.
  amount: 50
  reason: "Purchase"  # Optional

See the full list of supported currencies here.

Book Action​

book​

Open a written book for the player.

- type: book
  author: "Server"
  title: "&6Welcome Book"
  lines:
    1:
      - "&6Welcome!"
      - "&7This is page 1"
      - "of our welcome book."
    2:
      - "&6Page 2"
      - "&7More content here."

Dialog Action​

dialog​

Open a dialog popup. Dialogs provide a modern UI experience with forms, confirmations, and interactive buttons.

Requirements

Dialogs require Paper 1.21.7+ installed on your server.

- type: dialog
  dialog: "confirmation"

With arguments:

- type: dialog
  dialog: "purchase-confirm"
  arguments:
    - "diamond_sword"
    - "500"

From external plugin:

- type: dialog
  dialog: "custom-dialog"
  plugin: "MyPlugin"

Options:

OptionTypeDescription
dialogStringName of the dialog file (without .yml)
pluginStringPlugin name if using external dialog
argumentsListArguments to pass to the dialog

See Dialogues for complete dialog configuration documentation.

Bedrock Action​

bedrock​

Open a native Bedrock form for players connected via Geyser/Floodgate.

Requirements

Bedrock forms require Geyser or Floodgate installed on your server.

- type: bedrock
  bedrock: "simple-form"

With arguments:

- type: bedrock
  bedrock: "feedback-form"
  arguments:
    - "arg1"
    - "arg2"

From external plugin:

- type: bedrock
  bedrock: "custom-form"
  plugin: "MyPlugin"

Options:

OptionTypeDescription
bedrockStringName of the Bedrock form file (without .yml)
pluginStringPlugin name if using external form
argumentsListArguments to pass to the form

See Bedrock Forms for complete Bedrock form configuration documentation.

Discord Actions​

discord​

Send a message to a Discord webhook.

- type: discord
  webhook: "https://discord.com/api/webhooks/..."
  message: "%player% made a purchase!"
  username: "Shop Bot"          # Optional
  avatar: "https://..."         # Optional
  embeds:
    - title: "New Purchase"
      description: "%player% bought an item"
      color: "#00FF00"
      url: "https://example.com/purchase"
      footer:
      text: "Powered by zMenu"
      icon-url: "https://example.com/icon.png"
      thumbnail:
      url: "https://example.com/thumbnail.png"
      image:
      url: "https://example.com/image.png"
      author:
      name: "zMenu Bot"
      url: "https://example.com/bot"
      icon-url: "https://example.com/bot-icon.png"
      fields:
      - name: "Item"
        value: "Diamond Sword"
        inline: true
      - name: "Price"
        value: "$500"
        inline: true

discord_component​

Send a Discord message with buttons/components.

- type: discord_component
  webhook: "https://discord.com/api/webhooks/..."
  component:
    - title: "New Purchase"
      description: "%player% bought an item"
      color: "#00FF00"

Integration Actions​

luckperm-set​

Modify LuckPerms permissions.

- type: permission-set
  permission: "server.vip"
  value: true         # Grant (true) or revoke (false), default: true
  expiration: -1      # Seconds until expiry; -1 = permanent
  time-unit: SECONDS  # Optional: SECONDS, MINUTES, HOURS, DAYS

Options:

OptionTypeDefaultDescription
permissionString—The LuckPerms permission node to grant or revoke
valueBooleantruetrue to grant, false to revoke
expirationLong-1Duration before the permission expires; -1 = permanent
time-unitStringSECONDSUnit for expiration: SECONDS, MINUTES, HOURS, DAYS

Available aliases: permission-set, permission set, set permission, set-permission.

shopkeeper​

Interact with Shopkeepers plugin.

- type: shopkeeper
  name: "shop_name"

Item Actions​

These actions give or take items directly from the menu or the player's inventory. They are perfect for shops, kits or reward systems.

set_item​

Place an item in one or several slots, either in the menu or in the player's inventory.

- type: set_item
  slot: 13              # or slots: [13, 14, 15]
  in-player-inventory: false  # false = menu (default), true = player inventory
  dupe-protection: true       # default: true
  item:
    material: DIAMOND
    name: "&bReward"

Options:

OptionTypeDefaultDescription
slotInteger-The slot to set (use slots for several slots)
slotsList-The list of slots to set
in-player-inventoryBooleanfalsePlace the item in the player's inventory instead of the menu
dupe-protectionBooleantrueProtect the placed item against duplication
itemItem-The item to place (can also be defined inline at the action level)

Available aliases: set_item, set-item.

take_item​

Remove a number of matching items from the player's inventory.

- type: take_item
  amount: 1
  verification: SIMILAR  # SIMILAR (default) or MODELID
  use-cache: false       # default: false
  item:
    material: DIAMOND

Options:

OptionTypeDefaultDescription
amountInteger1Number of items to remove from the player
verificationStringSIMILARHow items are matched: SIMILAR or MODELID (custom model data)
use-cacheBooleanfalseUse the cached item stack when building the target item
itemItem-The item to match and remove (can also be defined inline)

Available aliases: take_item, take-item.

item_give​

Give an item directly to the player's inventory. If the inventory is full, leftover items are dropped at the player's location.

- type: item_give
  item:
    material: DIAMOND
    name: "&bFree Diamond"
    amount: 1

Options:

OptionTypeRequiredDescription
itemItemYesThe item to give (supports all item configuration options)

Available aliases: item_give, item-give.

item_edit​

Replace or modify an item at a specific slot in the player's inventory.

- type: item_edit
  slot: "5"
  item:
    material: DIAMOND_SWORD
    name: "&6Upgraded Sword"

Options:

OptionTypeRequiredDescription
slotStringYesThe inventory slot to edit
itemItemYesThe replacement item

Available aliases: item_edit, item-edit.

reset-pagination​

Reset the pagination state for one or more pagination context IDs, or for all contexts.

# Reset specific context(s)
- type: reset-pagination
  type: context
  context-id: "my_list"        # single context
  # context-ids: ["list1", "list2"]  # or multiple

# Reset all contexts for this player
- type: reset-pagination
  type: all

Options:

OptionTypeDefaultDescription
typeStringcontextReset mode: context (specific IDs) or all (every context)
context-idString—Single pagination context ID to reset (type: context only)
context-idsList—Multiple pagination context IDs to reset

Available aliases: reset-pagination.

refresh_slot​

Refresh only the given slot(s) without redrawing the whole inventory.

- type: refresh_slot
  slots: [13, 14, 15]
  in-player-inventory: false  # default: false

Options:

OptionTypeDefaultDescription
slotsList-The list of slots to refresh
in-player-inventoryBooleanfalseRefresh slots in the player's inventory instead of menu

Available aliases: refresh_slot, refresh-slot.

Complete Examples​

Purchase with Feedback​

items:
  buy-item:
    slot: 13
    item:
      material: DIAMOND_SWORD
      name: "&6&lDiamond Sword"
      lore:
        - "&7Price: &a$500"
    click-requirement:
      purchase:
        requirements:
          - type: placeholder
            placeholder: "%vault_eco_balance%"
            action: SUPERIOR_OR_EQUAL
            value: 500
            deny:
              - type: message
                messages:
                  - "&cYou need $500!"
              - type: sound
                sound: ENTITY_VILLAGER_NO
        success:
          - type: withdraw
            amount: 500
          - type: console-command
            commands:
              - "give %player% diamond_sword 1"
          - type: message
            messages:
              - "&aPurchase successful!"
          - type: sound
            sound: ENTITY_PLAYER_LEVELUP
          - type: close

Toggle Setting with Data​

items:
  toggle:
    slot: 22
    type: SWITCH
    placeholder: "%zmenu_player_value_setting%"
    buttons:
      "on":
        item:
          material: LIME_DYE
          name: "&a&lSetting: ON"
        actions:
          - type: data
            action: SET
            key: "setting"
            value: "off"
          - type: message
            messages:
              - "&7Setting turned &cOFF"
          - type: sound
            sound: UI_BUTTON_CLICK
          - type: refresh
      "off":
        item:
          material: GRAY_DYE
          name: "&7&lSetting: OFF"
        actions:
          - type: data
            action: SET
            key: "setting"
            value: "on"
          - type: message
            messages:
              - "&7Setting turned &aON"
          - type: sound
            sound: UI_BUTTON_CLICK
          - type: refresh

Multi-Action Button​

items:
  reward:
    slot: 13
    item:
      material: CHEST
      name: "&e&lDaily Reward"
    actions:
      - type: console-command
        commands:
          - "give %player% diamond 5"
      - type: deposit
        amount: 1000
      - type: data
        action: SET
        key: "last_reward"
        value: "%zmenu_time_unix_timestamp%"
      - type: title
        title: "&6&lReward Claimed!"
        subtitle: "&75 Diamonds + $1000"
      - type: sound
        sound: ENTITY_PLAYER_LEVELUP
      - type: broadcast
        messages:
          - "&6%player% &7claimed their daily reward!"
      - type: close

Action Order​

Actions execute in the order they're listed. If you need to close the inventory after a teleport, put close before teleport:

actions:
  - type: close
  - type: teleport
    world: "world"
    x: 0
    y: 100
    z: 0

Using Actions in Requirements​

Actions can also be used in deny and success blocks of requirements:

click-requirement:
  vip-check:
    requirements:
      - type: permission
        permission: "server.vip"
        deny:
          - type: message
            messages:
              - "&cYou need VIP!"
    success:
      - type: message
        messages:
          - "&aAccess granted!"

Quick Reference Table​

Common Options (all actions)​

OptionDescription
delayDelay in ticks before execution
chancePercentage chance to execute
deny-chance-actionsFallback actions if chance fails

Action Types​

ActionDescription
messageSend message to player
broadcastSend message to all, resolved per recipient and filterable
broadcast_messageSend message to all, resolved once for the clicking player
action-barShow action bar
titleShow title/subtitle
broadcast_titleShow title/subtitle to all players
toastShow achievement toast
soundPlay sound
player-commandRun command as player
console-commandRun command as console
random-player-commandRun random command(s) as player (zMenu+)
random-console-commandRun random console command(s) (zMenu+)
inventoryOpen inventory
closeClose inventory
backGo back
refreshRefresh the current button's appearance
teleportTeleport player
connectChange server (BungeeCord/Velocity integration)
dataModify player data
depositAdd money
withdrawRemove money
broadcast_soundPlay sound to all players
message-toSend message to specific player
change-titleChange the inventory title
refresh-inventoryRefresh entire inventory
bookOpen a written book
dialogOpen dialog popup
discordSend a message to Discord
discord_componentSend Discord message with buttons
permission-setModify LuckPerms permissions
shopkeeperInteract with Shopkeepers plugin
set_itemPlace an item in menu/player slot(s)
take_itemRemove matching items from the player
refresh_slotRefresh specific slot(s) only
item_giveGive an item to the player's inventory
item_editReplace item at a specific slot
reset-paginationReset pagination context(s) for the player

Next Steps​

Copyright © 2026 GroupeZ|Build #loading...|-