⏹️Buttons

All information about the buttons

Informations

Buttons allow you to customize the actions in your inventory. You need to specify the type of each button and configure the elements specific to that button type. Below, you'll find the buttons that are integrated by default in the plugin; other plugins can also add new types of buttons.

For each button, you must specify an Item. To learn how to configure an Item, go here.

Configuration

`type`

type: <button type>

The type of the button. By default, the type will be set to NONE. It is important to set the button type if you want to perform specific actions.

`slot`

slot: <number between 0 and inventory limit>

slot: <page>-<slot>

Specify the slot where your item will be displayed.

Slots start at 0.
You can specify the page number directly in the slot. The format should be: <page>-<slot>. For example, for a button on page 2 and slot 8, you would use: 2-8.
To place multiple items in the same slot, you must use the else button.

To display a button on multiple slots, you can do it like this:

slots:
  - 0
  - 1
  - 2
  - 3
  - 4
  ...

You can also create slot ranges using this format: <startslot>-<endslot>.

slots:
  - 0-9 # From slot 0 to slot 9
  - 18
  - 17
  - 26
  - 27
  - 35
  - 36
  - 44-53 # From slot 44 to 53

`page`

page: <page numer>

Allows you to specify the page where the button will be displayed. By default, the page will be set to 1.

`is-permanent`

is-permanent: <true of false>

Allows you to specify if the button should be displayed on all pages of the inventory. If your inventory has only one page, you don’t need to use this option.

`use-cache`

use-cache: <true of false>

Allows you to enable or disable caching on the item. By default, caching will always be used if the button item does not contain a placeholder.

`item`

item: <itemstack>

Allows you to specify the item that will be displayed. For more information, click here.

`sound`

sound: ENTITY_COW_HURT
pitch: 1.5
volume: 0.5

Allows you to play a sound for the player when they click. You must use the sounds available in XSound. You can also adjust the pitch and volume of the sound.

We advise you to use an action to enjoy more functionality.

`messages`

messages:
  - <line 1>
  - <line 2>
  ...

Allows you to send a list of messages to the player upon clicking. You can use the MiniMessage format to send messages with click or hover actions.

We advise you to use an action to enjoy more functionality.

`open-link`

link: <link>
message: <message>
replace: <replace string>
hover:
  - <line 1>
  - <line 2>
  ...

Allows you to send a clickable message to the player. You need to include in your message list a text that will be replaced by the clickable link. An example is provided below.

Please use this only if your server is running an older version of Minecraft. Otherwise, use the MiniMessage format, which is much easier to work with.

Example:

messages:
  - "&8(&6zMenu&8) &fAdd your server to the site &3Serveur Minecraft Vote"
  - "&8(&6zMenu&8) %link% &d!"
open-link:
  link: "https://serveur-minecraft-vote.fr/utiliser/un/code/cadeau?code=ZMENU"
  message: "&b&lClick here"
  replace: "%link%"
  hover:
    - "&bClick here !"

`close-inventory`

close-inventory: <true of false>

Allows you to close the inventory after clicking.

`refresh-on-click`

refresh-on-click: <true or false>

Allows the button to refresh after a click. You can use this feature to create a shop, for example. An example is provided in the default configuration.

We advise you to use an action to enjoy more functionality. If you update the status of a player with orders, to be sure that the inventory update is done correctly, you must put a delay of 1 tick.

`player-head`

player-head: <placeholder>

Allows you to display a player's head based on a placeholder. You can use the placeholder %player% to display the head of the player who opens the inventory.

A caching system ensures the direct display of the skin for the heads.

`permission`

permission: <permission>

Allows you to define a permission that the player must have to display the item. You can reverse the permission by adding ! in front of the permission, which will cause the plugin to check that the player does not have the permission.

You can also define a list of permissions the player must have:

permission:
  - "first.permission"
  - "!second.permission"

We advise you to use a view-requirement to enjoy more functionality.

`or-permission`

Allows you to define a list of permissions, where the player only needs to have one of them.

or-permission:
  - "first.permission"
  - "!second.permission"

We advise you to use a view-requirement to enjoy more functionality.

`else`

else: <else button>

Allows you to display an else button if the player doesn't have the required permission. You can place multiple else buttons in a row without any issues. An example of this usage can be found in the default configuration.

Example:

items:
  |mybutton:
  |  <item configuration>
  |--|else:
  |  |  <first else configuration>
  |  |--|else:
  |  |--|  <second else configuration>

`placeholder`

  placeholder: <placeholder>
  value: <value for placeholder>
  action: <action for placeholder>
  math: <true/false>

Allows you to define a permission using a placeholder. You must specify the placeholder, the action to be performed with the value, and the value that will be checked.

You can use mathematical expressions if you set math to true, this allows you to do more complex actions.

Actions:

BOOLEAN (alias: b=): Checks if a value is true or false.
EQUALS_STRING (alias: s=): Checks if the text is strictly equal to the value.
EQUALSIGNORECASE_STRING (alias: s==): Checks if the text is equal to the value, ignoring case.
CONTAINS_STRING (alias: sc): Checks if the text is contained within the value.
DIFFERENT_STRING (alias: s!=): Checks if the text is different from the value.
SUPERIOR (alias: >): Checks if a number is strictly greater than the value.
LOWER (alias: <): Checks if a number is strictly less than the value.
SUPERIOR_OR_EQUAL (alias: >=): Checks if a number is greater than or equal to the value.
LOWER_OR_EQUAL (alias: <=): Checks if a number is less than or equal to the value.
EQUAL_TO (alias: ==): Verifies that two numbers are identical.

You can check multiple placeholders like this:

placeholders:
  - placeholder: <your placeholder>
    value: <your value>
    action: <your action>
  - placeholder: <your placeholder>
    value: <your value>
    action: <your action>

We advise you to use a view-requirement to enjoy more functionality.

`update`

update: <true or false>

Enables the automatic update of the item's name and lore. To configure the update interval, please refer to this section.

`update-master-button`

update-master-button: <true or false>

Allows you to completely update the button. You need to enable the update option for this feature to be activated. Instead of just updating the name and lore, this option refreshes the entire button. This includes rechecking permissions, requirements, and the else button.

`update-on-click`

update-on-click: <true of false>

Allows your button to be updated whenever a player clicks anywhere in the inventory, regardless of the slot.

`commands`

commands: 
  - "<your command>"

Allows the player to execute a list of commands. You can use the placeholder %player% to retrieve the username of the player executing the commands.

We advise you to use an action to enjoy more functionality.

`console-commands`

console-commands: # Commands to be executed by the console no matter the click
  - "<your command>"
console-right-commands: # Commands to be executed by the console when right-click
  - "<your command>"
console-left-commands: # Commands to be executed by the console when left-click
  - "<your command>"
console-permission-commands: # Commands to be executed by the console if the player has permission
  - "<your command>"
console-permission: "<permission>

You can execute commands from the console based on the player's click, as well as commands that require specific player permissions. You can use the placeholder %player% to retrieve the username of the player executing the commands.

We advise you to use an action to enjoy more functionality.

`view-requirement`

view-requirement:
  requirements: # In this example the player must have a balance greater than or equal to 5000
    - type: placeholder
      placeholder: "%vault_eco_balance%"
      value: "5000"
      action: "SUPERIOR_OR_EQUAL"

Sets the conditions the player must meet to see the button. This can include permissions, placeholders, and other criteria. For more information, refer to this section.

`click-requirement`

Defines the conditions the player must meet to click on the button. These requirements are checked when the player clicks, and actions can be executed based on the success or failure of these conditions. For more information, refer to this section.

`actions`

You can define a list of actions to perform when clicking. These actions can include sending messages, executing commands, opening a book, and more. For more information, refer to this section.

actions:
  - type: message
    messages:
      - "example"

`error-item`

Example of Inventory with Fail Item:

In this example, if the player is not in creative mode, a barrier with the name "Error" will be displayed for 10 ticks.

name: "&8Test"
size: 54
items:
  example:
    item:
      material: DIAMOND
    slot: 22
    error-item:
      duration: 10 # Duration of item display
      item: # Item to display
        material: BARRIER
        name: "&cError"
    click-requirement:
      left-click:
        clicks:
          - ALL
        requirements:
          - type: placeholder
            placeholder: "%player_gamemode%"
            value: "CREATIVE"
            action: equals_string

This feature is only available with zMenu+ !

`NONE`

The NONE type is the default type; it simply displays a button. You don't need to specify it, as it will be automatically selected if the plugin doesn't detect a different type.

`INVENTORY`

The INVENTORY type allows the player to open a new inventory.

inventory: <inventory file name>
plugin: <plugin name>
to-page: <page>
arguments:
  - <argument 1>
  - <argument 2>

inventory: The name of the inventory you want to open. This should match the name of the inventory file.
plugin: The name of the plugin from which the inventory originates. It's advisable to specify the plugin name to avoid opening a different inventory with the same name.
toPage: The page number you want to open. The default is page 1.
arguments: A list of arguments you can add. Each argument can include a name in the following format: <name>:<value>.

You must specify the inventory's name, which corresponds to the file name where the inventory is stored. Additionally, it's recommended to specify the plugin name to avoid confusion if two inventories share the same name.

`BACK`

The BACK type allows you to return to the previous inventory.

`HOME`

The HOME type allows you to return to the main inventory, which is the first one that was opened.

The NEXT type allows you to go to the next page, if it exists. You can use the else element to display another button if there is no next page.

Example:

next:
  type: NEXT
  is-permanent: true
  slot: 50
  item:
    material: ARROW
    name: "&fNext"
  else: #Displays another button if there is no next page.
    item:
      material: BLACK_STAINED_GLASS_PANE

`PREVIOUS`

The PREVIOUS type allows you to go to the previous page, if it exists. You can use the else element to display another button if there is no previous page.

previous:
  type: PREVIOUS
  is-permanent: true
  slot: 48
  item:
    material: ARROW
    name: "&fPrevious"
  else: #Displays another button if there is no next page.
    item:
      material: BLACK_STAINED_GLASS_PANE

`MAINMENU`

The MAINMENU type allows you to return to the main inventory specified in the config.json.

`JUMP`

The JUMP type allows you to change to a predefined page.

jump-button:
  type: JUMP
  toPage: 5

`SWITCH`

The SWITCH button allows you to use a placeholder and compare the result with multiple options. This makes it easy to create a quick and simplified display for buttons that require various actions.

switch:
  <default button here>
  buttons:
    "first key":
      <first button>
    "second key":
      <second button>
    "third key":
      <third button>          
    ...

You can put several buttons in your switch. And each button can be as complete as possible, you have no limitation !

You must specify the slot for each button. You need to use the refresh inventory action to update your switch button.

Example

In this example, the switch button is used to navigate between pages by using player data.

name: "&8Test"
size: 9
items:
  switch:
    type: SWITCH
    slot: 4
    item:
      material: PAPER
      name: '&fTuto &7#1'
      lore:
        - "&8This is the first page"
        - ""
        - "&7Click for the next page"
    actions:
      - type: data
        action: SET
        key: switch_value
        value: 2
      - type: refresh inventory
    key: "%zmenu_player_value_switch_value%"
    buttons:
      "2":
        slot: 4
        item:
          material: PAPER
          name: '&fTuto &7#2'
          lore:
            - "&8This is the second page"
            - ""
            - "&7Click for the next page"
        actions:
          - type: data
            action: SET
            key: switch_value
            value: 3
          - type: refresh inventory
      "3":
        slot: 4
        item:
          material: PAPER
          name: '&fTuto &7#3'
          lore:
            - "&8This is the third page"
            - ""
            - "&7Click for the next page"
        actions:
          - type: data
            action: SET
            key: switch_value
            value: 1
          - type: refresh inventory

You can compare numbers by specifying the operator in your switch key. You can use >=, <=, >, and <. For example, you could use: >=10 — your placeholder value must then be greater than or equal to 10.

`PAGINATION`

Example of Inventory with Pagination Button:

In this example, the items will be displayed in slots 21, 22, and 23 across multiple pages.

The list of items includes the material and the name. You can put anything you want in the list. To use the values, you must reference them with the placeholder keys. In this example, the keys will be %material% and %name%.

You can also modify the values like this:

%lower_<key>% - Displays the value in lowercase.
%upper_<key>% - Displays the value in uppercase.
%capitalize_<key>% - Displays the value with the first letter capitalized.

You can use placeholders everywhere, including in your requirements, commands, and other placeholders.

name: "&8&lPagination &r&7%page%&8/&7%maxPage%"
size: 54
items:
  example:
    type: PAGINATION
    elements:
      - material: DIAMOND
        name: "diaMond"
      - material: IRON_INGOT
        name: "iron_INGOT"
      - material: EMERALD
        name: "emeRald"
      - material: COAL
        name: "cOAl"
      - material: GOLD_INGOT
        name: "gold_INGOT"
    slots:
      - 21-23
    item:
      material: "%material%"
      name: "&e%index% &7- &b%current%"
      lore:
        - "&8&m-----------------------"
        - ""
        - "&f%name% &8- &7Normal"
        - "&f%upper_name% &8- &fUpper case"
        - "&f%lower_name% &8- &7lower case"
        - "&f%capitalize_name% &8- &7Capitalized"
        - ""
        - "&8&m-----------------------"
  next:
    type: NEXT
    is-permanent: true
    slot: 50
    item:
      material: ARROW
      name: "&fNext"
  previous:
    type: PREVIOUS
    is-permanent: true
    slot: 48
    item:
      material: ARROW
      name: "&fPrevious"

This feature is only available with zMenu+ !

`DYNAMIC_PAGINATION`

This feature allows you to create a dynamic inventory using placeholders, offering limitless possibilities such as creating a ranking system. The only limit is your imagination.

In the example below, placeholders are generated by zMenu+ as an example:

%zmenu+_pagination_size% - Returns the size of your list. This value will change when the plugin is loaded.
%zmenu+_pagination_name_<index>% - Returns text based on the index. The text is generated automatically when the plugin is loaded.

You must specify the start and end of the pagination using start and end, which work with PlaceholderAPI.

Additionally, you have three internal placeholders to help you identify the button number that is displayed:

%index% - Returns the index of the button, starting at 0.
%current% - Returns the index of the button plus 1, starting at 1.
%value% - Returns the value of the button.

If your pagination does not start with 0, you must use this placeholder to retrieve the correct index of the button.

name: "&8Dynamic Pagination &7%page%/%maxPage%"
size: 54
items:
  pagination:
    type: DYNAMIC_PAGINATION
    start: 10 # You need to specify the beginning, here 10. But the easiest way is to start at 0
    end: "%zmenu+_pagination_size%" # The number or pagination must stop
    slots:
      - 20-24
      - 29-33
    item:
      material: IRON_INGOT
      name: "&fHey its &e%zmenu+_pagination_name_%value%% &8- &f%index%"
      lore:
        - "&7Index&8: &f%index%"
        - "&7Current&8: &f%current%"
        - "&7Value&8: &f%value%"

  next:
    type: NEXT
    is-permanent: true
    slot: 50
    item:
      material: ARROW
      name: "&fNext"

  previous:
    type: PREVIOUS
    is-permanent: true
    slot: 48
    item:
      material: ARROW
      name: "&fPrevious"

This feature is only available with zMenu+ !

`INPUT`

This feature allows the player to input a message in the chat and triggers actions based on success or error.

Input Types:

NUMBER - Checks a number; you can set a minimum and maximum value.
TEXT - Checks a text input; you can set a regex pattern for validation.
ONLINE_PLAYER - Checks if the input matches the nickname of an online player.

You can add conditions based on the input type:

For NUMBER, you can specify a minimum and maximum value.
For TEXT, you can use a regex pattern for validation.

Example: In this example, the button checks if the chosen number is between 0 and 100.

name: "&8Input Inventory"
size: 27
items:
  choose-amount:
    slot: 13
    type: INPUT
    item:
      material: DIAMOND_SWORD
      name: '&fChoose a number'
      lore:
        - ''
        - '&7Please choose a number between &b0&f and &a100'
    # Type of input to check
    # NUMBER - Allows to check a number, you can set a minimum and maximum
    # TEXT - Allows to check a text, you can set regex
    # ONLINE_PLAYER - Allows to check the nickname of a player online
    inputType: NUMBER
    # Conditions has checked, works with PlaceholderAPI
    conditions:
      min: 0
      max: 100
      # regex: "^[a-zA-Z0-9]+$"
    # Action performed in case of successful conditions
    success-actions:
      - type: console_command
        commands:
          - "bc %player% has just chosen the number %input% !" # or placeholder: %zmenu_input%
    # Action performed in case conditions failed
    error-actions:
      - type: message
        messages:
          - "&cYou must choose a number between 0 and 100."
    # Action performed when clicking, by default the inventory will not close, you must close it, then send a message or perform other action at the same time
    actions:
      - type: message
        messages:
          - "&7Please choose a number between &b0&f and &a100&8:"
      - type: close

This feature is only available with zMenu+ !

PreviousInventories NextRequirements

Last updated 3 months ago