Aller au contenu principal

Actions

Actions are commands executed when a player interacts with a button. zMenu provides 28+ 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

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
  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)

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

change-title​

Change the inventory title (requires PacketEvents plugin).

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

Options:

OptionTypeRequiredDescription
inventory-nameStringYesThe new inventory title to display

Note: This action requires the PacketEvents plugin to be installed on your server.

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

toast​

Display a toast notification (achievement popup).

- type: "toast"
  icon: DIAMOND
  message: "&aAchievement Unlocked!"
  frame: TASK  # TASK, GOAL, or CHALLENGE

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"
attention

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"

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

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

Economy Actions​

deposit​

Add money to 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.

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.

Discord Actions​

discord​

Send a message to a Discord webhook.

- type: discord
  webhook: "https://discord.com/api/webhooks/..."
  content: "%player% made a purchase!"
  username: "Shop Bot"          # Optional
  avatar_url: "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/..."
  embeds:
  - title: "New Purchase"
  description: "%player% bought an item"
  color: "#00FF00"

Integration Actions​

luckperm-set​

Modify LuckPerms permissions/groups.

- type: luckperm-set
  group: "vip"
  duration: 2592000  # Seconds (30 days)

Options:

OptionTypeRequiredDescription
groupStringYesName of the permission group.
durationIntegerNoDuration in seconds (default: permanent).

Note: Used to modify LuckPerms permissions or groups for players.

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

shopkeeper​

Interact with Shopkeepers plugin.

- type: shopkeeper
  name: "shop_name"

Complete Examples​

Purchase with Feedback​

items:
  buy-item:
    slot: 13
    item:
      material: DIAMOND_SWORD
      name: "&6&lDiamond Sword"
      lore:
        - "&7Price: &a$500"
    click-requirement:
      requirements:
        - type: placeholder
          value: "%vault_eco_balance%"
          compare: ">="
          number: 500
          deny:
            - type: message
              messages:
                - "&cYou need $500!"
            - type: sound
              sound: ENTITY_VILLAGER_NO
      success:
        - type: currency-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: currency-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:
  requirements:
    - type: permission
      permission: "server.vip"
      deny:
        - type: message
          messages:
            - "&cYou need VIP!"
  success:
    - type: message
      messages:
        - "&aAccess granted!"

Quick Reference Table​

ActionDescription
messageSend message to player
broadcastSend message to all
action-barShow action bar
titleShow title/subtitle
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
luckperm-setModify LuckPerms permissions
shopkeeperInteract with Shopkeepers plugin

Next Steps​

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