Installing zMenu

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:

Requirement	Version
Minecraft	1.19 to 1.21+ (Paper 26+ supported)
Java	Java 21 (required)
Server Software	Paper, Purpur, Pufferfish, or Folia

Paper is now required

zMenu is a Paper-only plugin — it ships a paper-plugin.yml and will not load on Spigot. Run it on Paper, a Paper fork (Purpur / Pufferfish) or Folia.

Recommended Setup

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

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:

• Modrinth (Primary): https://modrinth.com/plugin/zmenu
• SpigotMC: https://www.spigotmc.org/resources/zmenu.110402/

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:

Recommended Plugins

Plugin	Purpose
PlaceholderAPI	Display dynamic values in items and messages
Vault	Economy integration
LuckPerms	Permission-based requirements

Item Plugins (Optional)

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

Plugin	Integration
ItemsAdder	Custom items and textures
Oraxen	Custom items and models
HeadDatabase	Custom player heads
Slimefun	Slimefun items
MythicMobs	MythicMobs items
ExecutableItems	ExecutableItems support

Other Integrations

Plugin	Integration
Jobs Reborn	Job level requirements
zHead	Custom head textures
packetevents	Required 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