GroupeZ Docs

Installing zMenu

How to download, install, and configure zMenu on your Minecraft server

This guide will walk you through the process of installing zMenu on your Minecraft server.

Requirements

Before installing zMenu, make sure your server meets the following requirements:

RequirementVersion
Minecraft1.20.6 and newer (Paper 26+ supported)
JavaJava 21 (required)
Server SoftwarePaper, Purpur, Pufferfish, or Folia

Paper is required

zMenu is a Paper-only plugin — it ships a paper-plugin.yml, which only Paper reads. Run it on Paper, a Paper fork (Purpur / Pufferfish) or Folia.

On Spigot the plugin still loads and enables, but nothing works: no menu, no command, no API. It only prints a warning in the console, and sends the same warning on join to players holding zmenu.paper.warning (operators by default), telling you to install Paper.

Recommended Setup

For the best experience, we recommend using Paper or Purpur. This enables MiniMessage formatting support and provides better performance.

Migrating from DeluxeMenus?

Keep your menus: once zMenu is installed, run /zm convert deluxemenus to convert every DeluxeMenus menu into a zMenu inventory. See Migrate from DeluxeMenus.

First start needs internet

On first load zMenu downloads a few runtime libraries (the MariaDB driver and Reflections) through Paper's library loader. On a restricted network you can point it at a mirror with the PAPER_DEFAULT_CENTRAL_REPOSITORY environment variable or the -Dorg.bukkit.plugin.java.LibraryLoader.centralURL JVM flag.

Download

You can download zMenu from the following sources:

Development Builds

Get the latest development versions in the #builds channel on Discord.

Installation Steps

Step 1: Download the Plugin

Download the latest version of zMenu.jar from one of the sources listed above.

Step 2: Install the Plugin

  1. Stop your Minecraft server if it's running
  2. Place the zMenu.jar file in your server's plugins/ folder
  3. Start your server

Step 3: Verify Installation

After starting your server, verify that zMenu loaded correctly:

  1. Check the server console for:

    [zMenu] zMenu has been enabled!

  2. Run the command /zm version in-game or from console to see version information

Step 4: Initial Configuration

After the first startup, zMenu will create the following folder structure:

plugins/zMenu/
├── config.yml                    # Main configuration file
├── global-placeholders.yml       # Global placeholder values
├── commands/
│   └── commands.yml              # Custom command definitions
├── inventories/
│   ├── basic_inventory.yml       # Example inventory
│   ├── advanced_inventory.yml    # Advanced example
│   └── pro_inventory.yml         # Pro example
├── patterns/
│   └── pattern_example.yml       # Example pattern
├── items/
│   └── default-items.yml         # Reusable item definitions
├── actions_patterns/
│   └── default-actions.yml       # Default action patterns
└── dialogs/                      # Dialog templates (1.20.5+)

Optional Dependencies

zMenu works standalone but integrates with many popular plugins for enhanced functionality:

PluginPurpose
PlaceholderAPIDisplay dynamic values in items and messages
VaultEconomy integration
LuckPermsPermission-based requirements

Item Plugins (Optional)

These plugins allow you to use custom items in your menus:

PluginIntegration
ItemsAdderCustom items and textures
OraxenCustom items and models
HeadDatabaseCustom player heads
SlimefunSlimefun items
MythicMobsMythicMobs items
ExecutableItemsExecutableItems support

Other Integrations

PluginIntegration
Jobs RebornJob level requirements
zHeadCustom head textures
packeteventsRequired for dialog system (1.20.5+)

Configuration Files

config.yml

The main configuration file controls global plugin settings. Here's an overview of key options:

# Enable debug mode for troubleshooting
enable-debug: false

# Database settings (SQLITE, MYSQL, MARIADB, or NONE)
storage-type: SQLITE

# Enable MiniMessage formatting (Paper/Purpur only)
enable-mini-message-format: true

# Cache settings for performance
enable-cache-item-stack: true
enable-cache-placeholder-api: false

# Anti-dupe protection
enable-anti-dupe: true

# Click cooldown to prevent spam
enable-cooldown-click: true
cooldown-click-milliseconds: 100

# Default inventory opened by main menu button
main-menu: "example"

See the config.yml documentation for all available options.

Troubleshooting

Plugin Not Loading

If zMenu doesn't appear in /plugins:

  1. Check console for errors during startup
  2. Verify the JAR file isn't corrupted (re-download if needed)
  3. Make sure you're using a compatible server version

Configuration Errors

If you see YAML parsing errors:

  1. Use a YAML validator like YAML Lint
  2. Check for incorrect indentation (use spaces, not tabs)
  3. Ensure special characters are quoted properly

Placeholders Not Working

If PlaceholderAPI placeholders don't work:

  1. Make sure PlaceholderAPI is installed
  2. Install the required expansion: /papi ecloud download <expansion>
  3. Reload PlaceholderAPI: /papi reload

Updating zMenu

To update zMenu:

  1. Download the latest version
  2. Stop your server
  3. Replace the old zMenu.jar with the new one
  4. Start your server
  5. Run /zm reload if configurations haven't changed

Backup First

Always backup your plugins/zMenu/ folder before updating, especially if you've customized configurations.

Next Steps

Now that zMenu is installed, learn how to:

  1. Understand the configuration system
  2. Create your first inventory
  3. Use commands and permissions

Getting Started

Introduction to zMenu - The most powerful inventory plugin for Minecraft

Migrate from DeluxeMenus

Convert your DeluxeMenus menus into zMenu inventories with a single command

On this page

RequirementsDownloadInstallation StepsStep 1: Download the PluginStep 2: Install the PluginStep 3: Verify InstallationStep 4: Initial ConfigurationOptional DependenciesRecommended PluginsItem Plugins (Optional)Other IntegrationsConfiguration Filesconfig.ymlTroubleshootingPlugin Not LoadingConfiguration ErrorsPlaceholders Not WorkingUpdating zMenuNext 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.