GroupeZ Docs
Configurations

Requirements

Complete guide to the requirements system in zMenu - conditions for buttons and inventories

Requirements are conditions that must be met before a button is displayed, clicked, or an inventory is opened. They are the core system for creating dynamic, conditional menus in zMenu.

How Requirements Work

A requirement checks a condition (permission, placeholder value, item in inventory, etc.). Based on the result:

  • If all requirements are met, the success actions are executed
  • If any requirement fails, the deny actions of that requirement are executed
click-requirement:
  vip-requirement:
    clicks:
      - ALL
    requirements:
      - type: permission
        permission: "server.vip"
        deny:
          - type: message
            messages:
              - "&cYou need VIP to use this!"
    success:
      - type: message
        messages:
          - "&aWelcome, VIP!"

Where to Use Requirements

Requirements can be used in three contexts:

view-requirement (Buttons)

Controls whether a button is visible. If the requirements are not met, the button is hidden entirely.

items:
  vip-only:
    slot: 0
    view-requirement:
      requirements:
        - type: permission
          permission: "server.vip"
    item:
      material: DIAMOND
      name: "&b&lVIP Item"

click-requirement (Buttons)

Controls whether a button can be clicked. The button remains visible, but the click is denied if conditions are not met.

items:
  purchase:
    slot: 0
    click-requirement:
      purchase:
        clicks:
          - ALL
        requirements:
          - type: placeholder
            placeholder: "%vault_eco_balance%"
            action: SUPERIOR_OR_EQUAL
            value: 100
            deny:
              - type: message
                messages:
                  - "&cYou need $100 to purchase this!"
              - type: sound
                sound: ENTITY_VILLAGER_NO
        success:
          - type: withdraw
            amount: 100
          - type: message
            messages:
              - "&aPurchase successful!"
    item:
      material: GOLD_INGOT
      name: "&e&lPurchase - $100"

view-requirement / open-requirement (Inventories)

Controls whether an inventory can be opened. Applied at the inventory level, not on individual buttons. open-requirement is an alias for view-requirement at the inventory level.

# In your inventory file
name: "&6VIP Menu"
size: 54

view-requirement:
  requirements:
    - type: permission
      permission: "server.vip"
      deny:
        - type: message
          messages:
            - "&cYou need VIP to access this menu!"

If the requirement is not met, the inventory will not open and the deny actions will execute.

Requirement Types

permission

Checks if the player has a specific permission.

requirements:
  - type: permission
    permission: "server.admin"
KeyTypeDescription
permissionStringThe permission node to check

You can use any permission from any permission plugin (LuckPerms, etc.). This is the simplest and most common requirement type.

placeholder

Compares a placeholder value against a target. This is the most versatile requirement type.

Numeric comparison

requirements:
  - type: placeholder
    placeholder: "%player_level%"
    action: SUPERIOR_OR_EQUAL
    value: 10
KeyTypeDescription
placeholderStringThe placeholder to evaluate
actionStringThe comparison operator
valueNumber/StringThe value to compare against
targetString(Optional) Evaluate the placeholder for this player (by name)

String comparison

requirements:
  - type: placeholder
    placeholder: "%player_world%"
    action: EQUALS_STRING
    value: "world_nether"

Comparison Operators

Numeric:

AliasDescriptionAction
==Equal toaction: EQUAL_TO
!=Not equal toaction: DIFFERENT
>Greater thanaction: SUPERIOR
>=Greater than or equalaction: SUPERIOR_OR_EQUAL
<Less thanaction: LOWER
<=Less than or equalaction: LOWER_OR_EQUAL

String:

AliasDescriptionAction
s=Exact string matchaction: EQUALS_STRING
s!=String not equalaction: DIFFERENT_STRING
s==Case-insensitive string matchaction: EQUALSIGNORECASE_STRING
scString containsaction: CONTAINS_STRING

Boolean:

AliasDescriptionAction
b=Compare with booleanaction: BOOLEAN

Math Expressions

Enable math: true to evaluate mathematical expressions in placeholder values:

requirements:
  - type: placeholder
    math: true
    placeholder: "%zmenu_player_value_cookie%"
    value: "%price%+(%price%*%zmenu_player_value_upgrades%*1.15)"
    action: SUPERIOR_OR_EQUAL

This evaluates the math expression before comparing. Useful for dynamic pricing, scaling costs, or complex conditions.

money

Checks if the player has enough money in their account. Works with BeastTokens, Vault, PlayerPoints, ElementalTokens, ElementalGems, Level, Experience, zEssentials, EcoBits, CoinsEngine and VotingPlugin.

Uses CurrenciesAPI.

requirements:
  - type: money
    amount: 1000
KeyTypeDescription
amountNumberThe minimum balance required
economyStringThe currency name (optional)
currencyStringThe economy name (only needed for zEssentials, CoinsEngine and EcoBits)

Example with specific currency and economy:

requirements:
  - type: money
    amount: 500
    currency: "CoinsEngine"
    economy: "gems"

This requirement only checks the balance. To actually withdraw money on success, use the withdraw action in the success block.

item

Checks if the player has a specific item in their inventory.

requirements:
  - type: item
    item:
      material: DIAMOND
      amount: 5
    verification: SIMILAR
KeyTypeDescription
item.materialStringThe Minecraft material name
amountNumberThe minimum quantity required
verificationString(Optional) Verification type: SIMILAR, EXACT, MATERIAL, AIR, AMOUNT (Default: SIMILAR)

You can also check for items with specific properties:

requirements:
  - type: item
    item:
      material: DIAMOND_SWORD
      name: "&6Legendary Blade"
    amount: 1

check-inventory

Checks the item placed in a specific slot of the menu (or of the player's inventory). Unlike item, which scans the whole inventory, this requirement targets a single slot. It is mainly used together with the item_drag button to validate what a player dropped into a slot.

requirements:
  - type: check-inventory
    slot: 13
    item:
      material: DIAMOND
    type: full                 # Item comparison type (default: full)
    require-player-item: false # Require the slot to actually contain a player item
    is-player-inventory: false # Check a slot of the player's inventory instead of the menu
    success:
      - type: message
        messages:
          - "&aCorrect item!"
    deny:
      - type: message
        messages:
          - "&cWrong item!"
KeyTypeDescription
slotNumberThe slot to check (required)
itemItemThe item to compare against
typeStringItem comparison type (e.g. full, similar, modelid). Default: full
require-player-itemBooleanIf true, the slot must contain an item put there by the player (default: false)
is-player-inventoryBooleanIf true, checks a slot in the player's inventory instead of the menu (default: false)
in-spigot-inventoryBooleanAlias for is-player-inventory (default: false)
successListActions executed when the slot matches the item
denyListActions executed when the slot does not match

luckperm

Checks if the player belongs to a specific LuckPerms group. Requires LuckPerms.

requirements:
  - type: luckperm
    group: vip
KeyTypeDescription
groupStringThe LuckPerms group name

job

Checks if the player has a specific job. Requires Jobs Reborn.

requirements:
  - type: job
    job: Miner
KeyTypeDescription
jobStringThe job name

regex

Checks if a value matches a regular expression pattern. Commonly used with the INPUT button type to validate player input.

requirements:
  - type: regex
    input: "%input%"
    regex: "^[1-9][0-9]?$|^64$"
KeyTypeDescription
inputStringThe value to test against the regex
regexStringThe regular expression pattern

Example: Validate numeric input between 1 and 64:

items:
  set-amount:
    type: INPUT
    slot: 13
    inputType: NUMBER
    conditions:
      min: 1
      max: 64
    success-actions:
      - type: data
        key: "amount"
        value: "%input%"
      - type: refresh
    item:
      material: HOPPER
      name: "&6&lSet Amount"
    click-requirement:
      check:
        clicks:
          - ALL
        requirements:
          - type: regex
            input: "%input%"
            regex: "^[1-9][0-9]?$|^64$"
            deny:
             - type: message
               messages:
                 - "&cPlease enter a number between 1 and 64"
      success:
        - type: data
          key: "amount"
          value: "%input%"
        - type: refresh

playername

Checks the player's name.

Type key spelling

The registered type key is playername (no hyphen). Using type: player-name will not work.

requirements:
  - type: playername
    player-name: "Notch"
KeyTypeDescription
player-nameStringThe player name to check (also accepts playerName or playername as field aliases)

cuboid

Checks if the player is located inside a cuboid zone. You must define the world and the coordinates of the two opposite corners of the cuboid.

requirements:
  - type: cuboid
    cuboids:
      - "world,0,60,0,100,120,100"

The format is <world name>,<x1>,<y1>,<z1>,<x2>,<y2>,<z2>.

KeyTypeDescription
cuboidsList of StringsList of cuboid zones in the format world,x1,y1,z1,x2,y2,z2

You can define multiple cuboids. The requirement passes if the player is inside any of them:

requirements:
  - type: cuboid
    cuboids:
      - "world,0,60,0,100,120,100"
      - "world,-50,40,-50,50,100,50"
      - "world_nether,10,30,10,50,80,50"

item-rule

Checks whether the item in a given slot satisfies an item rule. This bridges the requirements system with the rule system used by the item_drag button.

requirements:
  - type: item-rule
    slot: 13
    rule:
      type: material
      materials:
        - DIAMOND
        - EMERALD
    deny:
      - type: message
        messages:
          - "&cOnly diamonds or emeralds are accepted here!"
KeyTypeDescription
slotNumberThe inventory slot to inspect
ruleObjectThe item rule to evaluate (see Item Rules for all rule types)

and

zMenu+ only

This feature is only available with zMenu+.

Combines multiple requirements where all must be met. This allows you to group requirements together and nest them with or blocks for complex logic.

requirements:
  - type: and
    requirements:
      - type: permission
        permission: "server.vip"
      - type: placeholder
        placeholder: "%player_level%"
        action: SUPERIOR_OR_EQUAL
        value: 10
KeyTypeDescription
requirementsListThe list of sub-requirements that must all pass

or

zMenu+ only

This feature is only available with zMenu+.

Combines multiple requirements where only a minimum number must be met.

requirements:
  - type: or
    minimum: 1
    random: false
    requirements:
      - type: permission
        permission: "server.vip"
      - type: permission
        permission: "server.premium"
KeyTypeDescription
minimumNumberThe minimum number of requirements that must pass
randomBooleanWhether the list of requirements should be traversed randomly
requirementsListThe list of sub-requirements

Combining and + or

You can combine and and or requirements to create complex conditions. For example, the player must have permission A and B, plus must have permission C or D:

name: "&8Test And/Or"
size: 54
items:
  test:
    slot: 22
    view-requirement:
      requirements:
        - type: and
          requirements:
            - type: permission
              permission: zmenu.test
              success:
                - type: message
                  messages:
                    - "&7Test And 1 - &aOK"
              deny:
                - type: message
                  messages:
                    - "&7Test And 1 - &cKO"
            - type: permission
              permission: zmenu.test2
              success:
                - type: message
                  messages:
                    - "&7Test And 2 - &aOK"
              deny:
                - type: message
                  messages:
                    - "&7Test And 2 - &cKO"
        - type: or
          minimum: 1
          random: true
          requirements:
            - type: permission
              permission: zmenu.test3
              success:
                - type: message
                  messages:
                    - "&7Test Or 1 - &aOK"
              deny:
                - type: message
                  messages:
                    - "&7Test Or 1 - &cKO"
            - type: permission
              permission: zmenu.test4
              success:
                - type: message
                  messages:
                    - "&7Test Or 2 - &aOK"
              deny:
                - type: message
                  messages:
                    - "&7Test Or 2 - &cKO"
    item:
      material: PAPER
      name: "&aTest And/Or"
    else:
      item:
        material: PAPER
        name: "&cTest And/Or"

In this example, the player must have zmenu.test and zmenu.test2 (the and block), plus must have zmenu.test3 or zmenu.test4 (the or block with minimum: 1). Each sub-requirement has its own success and deny actions for feedback.

Success and Deny Actions

Each requirement can have deny actions, and the overall requirement block can have success actions.

deny

Actions executed when this specific requirement is not met. Defined inside each individual requirement.

requirements:
  - type: permission
    permission: "server.vip"
    deny:
      - type: message
        messages:
          - "&cYou need VIP rank!"
      - type: sound
        sound: ENTITY_VILLAGER_NO

success

Actions executed when all requirements are met. Defined at the requirement block level (outside the requirements list).

click-requirement:
  purchase:
    clicks:
      - ALL
    requirements:
      - type: placeholder
        placeholder: "%vault_eco_balance%"
        action: SUPERIOR_OR_EQUAL
        value: 500
        deny:
          - type: message
            messages:
              - "&cYou need $500!"
    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

All action types can be used in both deny and success blocks.

Multiple Requirements

You can combine multiple requirements. All requirements must be met for the condition to pass. If any single requirement fails, its deny actions are executed.

click-requirement:
  default:
    clicks:
      - ALL
    requirements:
      - type: permission
        permission: "server.vip"
        deny:
          - type: message
            messages:
              - "&cYou need VIP rank!"
      - type: placeholder
        placeholder: "%vault_eco_balance%"
        action: SUPERIOR_OR_EQUAL
        value: 1000
        deny:
          - type: message
            messages:
              - "&cYou need $1000!"
      - type: item
        item:
          material: DIAMOND
          amount: 5
        deny:
          - type: message
            messages:
              - "&cYou need 5 diamonds!"
    success:
      - type: message
        messages:
          - "&aAll conditions met!"

In this example, the player must have the VIP permission AND $1000 AND 5 diamonds. If any condition fails, the corresponding deny message is shown.

The else System

The else block works with view-requirement to display an alternative button when the requirement is not met. Instead of hiding the button entirely, you can show a different item.

Basic else

items:
  vip-button:
    slot: 0
    view-requirement:
      requirements:
        - type: permission
          permission: "vip.access"
    item:
      material: DIAMOND_BLOCK
      name: "&b&lVIP Content"
    else:
      item:
        material: COAL_BLOCK
        name: "&7&lLocked"
        lore:
          - "&cRequires VIP rank"

If the player has vip.access, they see a diamond block. Otherwise, they see a coal block with a "locked" message.

Nested else Chains

You can chain multiple else blocks to create a state machine with several visual states. Each else can have its own view-requirement:

items:
  reward:
    slot: 0

    # State 1: Already claimed
    view-requirement:
      requirements:
        - type: placeholder
          placeholder: "%zmenu_player_value_claimed%"
          value: "true"
          action: EQUAL_TO
    item:
      material: MINECART
      name: "&a&lReward Claimed"
      lore:
        - "&7You already claimed this reward"

    else:
      # State 2: Not enough level
      view-requirement:
        requirements:
          - type: placeholder
            placeholder: "%player_level%"
            value: "10"
            action: LOWER
      item:
        material: BARRIER
        name: "&c&lLocked"
        lore:
          - "&7Requires level 10"

      else:
        # State 3: Ready to claim
        item:
          material: CHEST
          name: "&e&lClaim Reward"
          lore:
            - "&7Click to claim!"
        click-requirement:
          claim:
            clicks:
              - ALL
            requirements:
              - type: placeholder
                placeholder: "%player_level%"
                value: "10"
                action: SUPERIOR_OR_EQUAL
          success:
            - type: data
              action: SET
              key: "claimed"
              value: "true"
            - type: console-command
              commands:
                - "give %player% diamond 10"
            - type: sound
              sound: ENTITY_PLAYER_LEVELUP

The system evaluates each view-requirement from top to bottom:

  1. If the first requirement matches, that button state is shown
  2. If not, it moves to the else block and checks its requirement
  3. This continues through the chain
  4. The final else without a view-requirement acts as the default

Named Click Requirements

Inside click-requirement, you can define named requirement groups with specific click types. This allows different conditions for different click actions.

click-requirement:
  purchase:
    clicks:
      - ALL
    requirements:
      - type: placeholder
        placeholder: "%vault_eco_balance%"
        action: SUPERIOR_OR_EQUAL
        value: 100
        deny:
          - type: message
            messages:
              - "&cYou need $100!"
    success:
      - type: withdraw
        amount: 100
      - type: message
        messages:
          - "&aPurchased!"
KeyAliasesTypeDescription
clicks—ListClick types this group responds to
requirementsrequirementListThe conditions to check
success—ListActions executed when the minimum number of requirements pass
deny—ListActions executed when the minimum number is NOT reached (group-level fallback)
minimum-requirementminimumRequirementIntegerMinimum number of requirements that must pass (default: all)

Available click types: ALL, LEFT, RIGHT, SHIFT_LEFT, SHIFT_RIGHT, MIDDLE, DROP, CONTROL_DROP

minimum-requirement

Set minimum-requirement: 1 if you want the success block to fire when at least one requirement passes rather than requiring all of them.

Example with different actions per click:

click-requirement:
  buy-one:
    clicks:
      - LEFT
    requirements:
      - type: placeholder
        placeholder: "%vault_eco_balance%"
        action: SUPERIOR_OR_EQUAL
        value: 100
        deny:
          - type: message
            messages:
              - "&cYou need $100!"
    success:
      - type: withdraw
        amount: 100
      - type: console-command
        commands:
          - "give %player% diamond 1"
  buy-stack:
    clicks:
      - RIGHT
    requirements:
      - type: placeholder
        placeholder: "%vault_eco_balance%"
        action: SUPERIOR_OR_EQUAL
        value: 6400
        deny:
          - type: message
            messages:
              - "&cYou need $6400!"
    success:
      - type: withdraw
        amount: 6400
      - type: console-command
        commands:
          - "give %player% diamond 64"

Complete Examples

Shop Item with Price Check

A button that sells an item only if the player can afford it:

items:
  shop-sword:
    slot: 13
    type: NONE
    item:
      material: DIAMOND_SWORD
      name: "&6&lDiamond Sword"
      lore:
        - "&8&m─────────────────"
        - ""
        - "&7Price: &a$500"
        - "&7Your balance: &e$%vault_eco_balance%"
        - ""
        - "&8&m─────────────────"
        - ""
        - "&e▸ Click to purchase"
      glow: true
    click-requirement:
      purchase:
        clicks:
          - ALL
        requirements:
          - type: placeholder
            placeholder: "%vault_eco_balance%"
            action: SUPERIOR_OR_EQUAL
            value: 500
            deny:
              - type: message
                messages:
                  - "&cYou need $500 to buy this!"
              - 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

Daily Reward with Cooldown

A button that can only be clicked once every 24 hours using player data and timestamps:

items:
  daily-reward:
    slot: 22
    item:
      material: CHEST
      name: "&e&lDaily Reward"
      lore:
        - "&7Claim your daily reward!"
    click-requirement:
      claim:
        clicks:
          - ALL
        requirements:
          - type: placeholder
            placeholder: "%zmenu_math_{zmenu_time_unix_timestamp}-{zmenu_player_value_last_daily}%"
            action: SUPERIOR_OR_EQUAL
            value: 86400
            deny:
              - type: message
                messages:
                  - "&cYou already claimed today's reward!"
      success:
        - type: data
          action: SET
          key: "last_daily"
          value: "%zmenu_time_unix_timestamp%"
        - type: console-command
          commands:
            - "give %player% diamond 5"
        - type: data
          action: ADD
          key: "daily_streak"
          value: "1"
        - type: message
          messages:
            - "&aDaily reward claimed!"
            - "&7Streak: &e%zmenu_player_value_daily_streak%"
        - type: sound
          sound: ENTITY_PLAYER_LEVELUP

VIP-Gated Menu

An inventory that only VIP players can open:

name: "&6&lVIP Lounge"
size: 54

view-requirement:
  requirements:
    - type: permission
      permission: "server.vip"
      deny:
        - type: message
          messages:
            - "&cThis menu is reserved for VIP members!"
        - type: sound
          sound: ENTITY_VILLAGER_NO

open-actions:
  - type: sound
    sound: BLOCK_CHEST_OPEN
  - type: message
    messages:
      - "&aWelcome to the VIP lounge!"

items:
  # ... your VIP-only buttons

Rank-Based Button with else Chain

A button that shows different content based on the player's rank:

items:
  rank-display:
    slot: 4

    # Diamond rank
    view-requirement:
      requirements:
        - type: luckperm
          group: diamond
    item:
      material: DIAMOND_BLOCK
      name: "&b&lDiamond Rank"
      lore:
        - "&7Your rank: &bDiamond"

    else:
      # Gold rank
      view-requirement:
        requirements:
          - type: luckperm
            group: gold
      item:
        material: GOLD_BLOCK
        name: "&6&lGold Rank"
        lore:
          - "&7Your rank: &6Gold"

      else:
        # Default (no rank)
        item:
          material: STONE
          name: "&7&lNo Rank"
          lore:
            - "&7You don't have a rank"
            - "&eVisit our store to get one!"

Player Data Spending System

A button that checks a custom currency stored in player data:

items:
  spend-coins:
    slot: 15
    item:
      material: DIAMOND
      name: "&b&lBuy Diamond"
      lore:
        - "&7Cost: &e50 coins"
        - "&7Your coins: &f%zmenu_player_value_coins%"
    click-requirement:
      purchase:
        clicks:
          - ALL
        requirements:
          - type: placeholder
            placeholder: "%zmenu_player_value_coins%"
            action: SUPERIOR_OR_EQUAL
            value: 50
            deny:
              - type: message
                messages:
                  - "&cYou need 50 coins!"
      success:
        - type: data
          action: SUBTRACT
          key: "coins"
          value: "50"
        - type: console-command
          commands:
            - "give %player% diamond 1"
        - type: refresh

Initialize Default Values

Use a hidden button with view-requirement to set default player data on first visit:

items:
  initialize:
    slot: 0
    view-requirement:
      requirements:
        - type: placeholder
          placeholder: "%zmenu_player_value_initialized%"
          action: DIFFERENT
          value: "true"
    item:
      material: AIR
    actions:
      - type: data
        action: SET
        key: "coins"
        value: "0"
      - type: data
        action: SET
        key: "initialized"
        value: "true"
      - type: refresh

This invisible button checks if the player has been initialized. If not, it sets default values and refreshes the inventory.

Actions

Complete reference for all action types in zMenu

Item Rules

Flexible item-matching system used to validate items dropped into a menu

On this page

How Requirements WorkWhere to Use Requirementsview-requirement (Buttons)click-requirement (Buttons)view-requirement / open-requirement (Inventories)Requirement TypespermissionplaceholderNumeric comparisonString comparisonComparison OperatorsMath Expressionsmoneyitemcheck-inventoryluckpermjobregexplayernamecuboiditem-ruleandorCombining and + orSuccess and Deny ActionsdenysuccessMultiple RequirementsThe else SystemBasic elseNested else ChainsNamed Click RequirementsComplete ExamplesShop Item with Price CheckDaily Reward with CooldownVIP-Gated MenuRank-Based Button with else ChainPlayer Data Spending SystemInitialize Default Values
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.