GroupeZ Docs
ConfigurationsButtonsButton Types

SWITCH Button

Button that displays different items based on conditions

The SWITCH button type displays different items based on a placeholder value. This allows you to create dynamic buttons that change appearance based on player data or other conditions.

Usage

items:
  toggle:
    type: SWITCH
    slot: 13
    key: "%zmenu_player_value_notifications%"
    buttons:
      "true":
        item:
          material: LIME_DYE
          name: "&a&lNotifications: ON"
        lore:
          - "&7Click to disable"
        actions:
          - type: data
            action: SET
            key: "notifications"
            value: "false"
          - type: refresh

      "false":
        slot: 13
        item:
          material: GRAY_DYE
          name: "&7&lNotifications: OFF"
        lore:
          - "&7Click to enable"
        actions:
          - type: data
            action: SET
            key: "notifications"
            value: "true"
          - type: refresh

    # Default state
    item:
      material: GRAY_DYE
      name: "&7&lNotifications: OFF"

Properties

key

Required. The placeholder to evaluate for determining which button to display.

key: "%zmenu_player_value_setting%"

buttons

Required. A map of values to button configurations. The key is the placeholder result, and the value is the button config to display.

buttons:
  "value1":
    item:
      material: DIAMOND
    actions:
      - type: message
        messages: ["Value is 1"]
  "value2":
    item:
      material: EMERALD
    actions:
      - type: message
        messages: ["Value is 2"]

Default State

The default state (when the placeholder value doesn't match any key in the buttons section) is defined by the standard button properties (item, actions, etc.) placed directly at the button level.

items:
  my-switch:
    type: SWITCH
    slot: 13
    key: "%placeholder%"
    buttons:
      "value1":
        item:
          material: DIAMOND
    # This is the default state
    item:
      material: BARRIER
      name: "&cUnknown State"

Examples

Toggle Setting

items:
  toggle-pvp:
    type: SWITCH
    slot: 13
    key: "%zmenu_player_value_pvp_enabled%"
    buttons:
      "true":
        item:
          material: DIAMOND_SWORD
          name: "&c&lPvP: ENABLED"
          lore:
            - "&7You can be attacked by players"
            - ""
            - "&e▸ Click to disable"
          glow: true
        actions:
          - type: data
            action: SET
            key: "pvp_enabled"
            value: "false"
          - type: message
            messages:
              - "&aPvP has been disabled!"
          - type: sound
            sound: BLOCK_NOTE_BLOCK_PLING
          - type: refresh

      "false":
        slot: 13
        item:
          material: SHIELD
          name: "&a&lPvP: DISABLED"
          lore:
            - "&7You are protected from players"
            - ""
            - "&e▸ Click to enable"
        actions:
          - type: data
            action: SET
            key: "pvp_enabled"
            value: "true"
          - type: message
            messages:
              - "&cPvP has been enabled!"
          - type: sound
            sound: ENTITY_ENDER_DRAGON_GROWL
          - type: refresh

    # Default state if placeholder doesn't match "true" or "false"
    item:
      material: SHIELD
      name: "&a&lPvP: DISABLED"
    actions:
      - type: data
        action: SET
        key: "pvp_enabled"
        value: "true"
      - type: refresh

Multi-State Button

items:
  difficulty:
    type: SWITCH
    slot: 22
    key: "%zmenu_player_value_difficulty%"
    buttons:
      "easy":
        slot: 13
        item:
          material: LIME_WOOL
          name: "&a&lDifficulty: EASY"
          lore:
            - "&7Current: Easy mode"
            - ""
            - "&e▸ Click to change to Normal"
        actions:
          - type: data
            action: SET
            key: "difficulty"
            value: "normal"
          - type: refresh

      "normal":
        slot: 13
        item:
          material: YELLOW_WOOL
          name: "&e&lDifficulty: NORMAL"
          lore:
            - "&7Current: Normal mode"
            - ""
            - "&e▸ Click to change to Hard"
        actions:
          - type: data
            action: SET
            key: "difficulty"
            value: "hard"
          - type: refresh

      "hard":
        slot: 13
        item:
          material: RED_WOOL
          name: "&c&lDifficulty: HARD"
          lore:
            - "&7Current: Hard mode"
            - ""
            - "&e▸ Click to change to Easy"
        actions:
          - type: data
            action: SET
            key: "difficulty"
            value: "easy"
          - type: refresh

    # Default state
    item:
      material: YELLOW_WOOL
      name: "&e&lDifficulty: NORMAL"
    actions:
      - type: data
        action: SET
        key: "difficulty"
        value: "hard"
      - type: refresh

Rank-Based Display

items:
  rank-display:
    type: SWITCH
    slot: 4
    key: "%luckperms_primary_group_name%"
    buttons:
      "default":
        slot: 13
        item:
          material: COAL
          name: "&7&lMember"
          lore:
            - "&7Your current rank"

      "vip":
        slot: 13
        item:
          material: IRON_INGOT
          name: "&a&lVIP"
          lore:
            - "&7Your current rank"
          glow: true

      "mvp":
        slot: 13
        item:
          material: GOLD_INGOT
          name: "&6&lMVP"
          lore:
            - "&7Your current rank"
          glow: true

      "admin":
        slot: 13
        item:
          material: DIAMOND
          name: "&b&lAdmin"
          lore:
            - "&7Your current rank"
          glow: true

    # Default state
    item:
      material: COAL
      name: "&7&lMember"

Progress Indicator

items:
  quest-status:
    type: SWITCH
    slot: 31
    key: "%zmenu_player_value_quest_stage%"
    buttons:
      "0":
        slot: 13
        item:
          material: PAPER
          name: "&7&lQuest: Not Started"
          lore:
            - "&7Begin your adventure!"
            - ""
            - "&e▸ Click to start"
        actions:
          - type: data
            action: SET
            key: "quest_stage"
            value: "1"
          - type: message
            messages:
              - "&aQuest started! Talk to the village elder."
          - type: refresh

      "1":
        slot: 13
        item:
          material: WRITABLE_BOOK
          name: "&e&lQuest: In Progress"
          lore:
            - "&7Talk to the village elder"
            - ""
            - "&7Progress: &e1/3"

      "2":
        slot: 13
        item:
          material: WRITABLE_BOOK
          name: "&e&lQuest: In Progress"
          lore:
            - "&7Collect 10 wheat"
            - ""
            - "&7Progress: &e2/3"

      "3":
        slot: 13
        item:
          material: ENCHANTED_BOOK
          name: "&a&lQuest: Complete!"
          lore:
            - "&7Return for your reward"
            - ""
            - "&e▸ Click to claim"
          glow: true
        actions:
          - type: console-command
            commands:
              - "give %player% diamond 5"
          - type: data
            action: SET
            key: "quest_stage"
            value: "done"
          - type: message
            messages:
              - "&aYou received 5 diamonds!"
          - type: refresh

      "done":
        slot: 13
        item:
          material: BOOK
          name: "&8&lQuest: Completed"
          lore:
            - "&7You've completed this quest"

    # Default state
    item:
      material: PAPER
      name: "&7&lQuest: Not Started"

Important Notes

  1. Use refresh action - Always include a refresh action when changing the state
  2. Quote string values - Values like "true" and "false" need quotes
  3. Provide default - Always define a default for unexpected values
  4. Player data integration - Works great with %zmenu_player_value_*% placeholders

Common Use Cases

  • Toggle settings (on/off)
  • Multi-option selectors
  • Progress indicators
  • Rank-based displays
  • State machines
  • Conditional rewards

Best Practices

  1. Always refresh after state changes
  2. Use descriptive keys for player data
  3. Provide visual feedback (sounds, messages)
  4. Include default state for new players
  5. Use clear visual distinction between states

Next Steps

MAIN_MENU Button

Button that opens the configured main menu

PAGINATION Button

Display paginated content in your menus

On this page

UsagePropertieskeybuttonsDefault StateExamplesToggle SettingMulti-State ButtonRank-Based DisplayProgress IndicatorImportant NotesCommon Use CasesBest PracticesRelated FeaturesNext Steps
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.