GroupeZ Docs
Configurations

Config.yml

Main configuration file reference

The config.yml file is the main configuration file for zMenu. It controls global plugin settings, database configuration, performance options, and more.

File Location

plugins/zMenu/config.yml

Complete Configuration Reference

#######################################
#          Debug Settings             #
#######################################

# Enable debug messages in console
enable-debug: false

# Enable debug timing information
enable-debug-time: false

# Enable per-operation performance debugging for inventory opening
enable-performance-debug: false

performance-debug:
  # Minimum execution time (ms) for an operation to appear in output
  threshold-ms: 10
  filter:
    # DISABLED - show all, WHITELIST - only listed, BLACKLIST - hide listed
    # Supports wildcards: "buildButton.*"
    mode: DISABLED
    operations: []

# Show informational messages about inventory/order loading
enable-information-message: true

# Skip the update check on startup
skip-update-check: false

#######################################
#         Storage Settings            #
#######################################

# Storage type for player data
# Options: SQLITE, MYSQL, MARIADB, NONE
storage-type: SQLITE

# Database configuration (for MySQL/MariaDB)
database-configuration:
  table-prefix: "zmenu_"
  host: "localhost"
  port: 3306
  user: "username"
  password: "password"
  database: "zmenu"
  debug: false

# Interval (seconds) for batching SQL saves instead of one query per update
batch-task: 10

#######################################
#           Logging Settings          #
#######################################

# Log inventory opens to the database
enable-player-open-inventory-logs: true

# Print console messages when files are saved or loaded
enable-log-storage-file: false

# Show a message to the player when /zm open <inventory> <player> <display> is used
enable-open-message: true

#######################################
#        Formatting Settings          #
#######################################

# Enable MiniMessage format (requires Minecraft 1.17+)
# This allows modern formatting like <gradient:red:blue>
enable-mini-message-format: true

#######################################
#         Command Settings            #
#######################################

# Force player commands to run via chat (useful for fake commands not registered in Spigot)
enable-player-command-in-chat: false

# Allow buttons to execute commands with OP-level permissions.
# WARNING: Security-sensitive. Only enable if you understand the risks.
# Requires server restart to take effect.
enable-player-commands-as-op-action: false

# Method used to grant temporary elevated permissions (when enable-player-commands-as-op-action is true)
# ATTACHMENT: grants permission * temporarily (recommended)
# SET_OP: temporarily sets player as OP
# BOTH: combines both methods
op-grant-method: ATTACHMENT

#######################################
#        Inventory Behavior           #
#######################################

# Action types to skip when a player switches between zMenu inventories (prevents re-opening old menus)
skip-close-actions-on-inventory-switch:
  - inventory
  - inv
  - back

# Use the faster FastEvent system (refer to documentation before enabling)
enable-fast-event: false

# Disable double-click detection to avoid duplicate interactions
disable-double-click-event: true

# Click types that are handled in menus
all-clicks-type:
  - MIDDLE
  - RIGHT
  - LEFT
  - SHIFT_RIGHT
  - SHIFT_LEFT

#######################################
#        Performance Settings         #
#######################################

# Cache item stacks for better performance
enable-cache-item-stack: true

# Enable click cooldown to prevent spam clicking
enable-cooldown-click: true

# Cooldown duration (milliseconds) between clicks
cooldown-click-milliseconds: 100

# Limit click packets received from players (requires PacketEvents plugin)
enable-packet-event-click-limiter: false

# Minimum time (ms) between packet-level click events
packet-event-click-limiter-milliseconds: 50

# Enable PlaceholderAPI caching
enable-cache-placeholder-api: false

# PlaceholderAPI cache duration (ticks, 20 = 1 second)
cache-placeholder-api: 20

# Cache offline player data (seconds)
cache-offline-player: 300

# Auto-save player data interval (seconds)
seconds-save-player-data: 600

# Auto-save player inventories interval (seconds)
seconds-save-player-inventories: 600

#######################################
#         Security Settings           #
#######################################

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

# Send a Discord notification when a dupe attempt is detected
enable-anti-dupe-discord-notification: false

# Webhook URL for anti-dupe Discord notifications
anti-dupe-discord-webhook-url: "https://discord.com/api/webhooks/<your webhook url>"

# Message sent to Discord on dupe detection. Supports %player%, %amount%, %itemname%
anti-dupe-message: "**%player%** used %amount% %itemname% from zMenu. It has been removed!"

#######################################
#          Menu Settings              #
#######################################

# Default main menu inventory name
main-menu: "example"

# Use swap item offhand key (F) to open main menu
use-swap-item-off-hand-key-to-open-main-menu: false

# Require shift + offhand key instead of just offhand key
use-swap-item-off-hand-key-to-open-main-menu-needs-shift: false

# Specific menu paths to load at startup (leave empty to load all)
specify-path-menus: []

# Generate default configuration files if they don't exist
generate-default-file: true

# Automatically reload an inventory when its file is modified, added or deleted
hot-reload:
  enable: false
  delay-milliseconds: 500

# How many dialog_list dialogs can be nested inside each other
dialog-list-max-depth: 4

#######################################
#          Download / API             #
#######################################

# Allow use of /zm download command
enable-download-command: false

# API URL for Minecraft Inventory Builder (do not change this value)
api-url: "https://minecraft-inventory-builder.com/api/v2/"

Configuration Options Explained

Debug Settings

enable-debug

Enables detailed debug messages in the console. Useful for troubleshooting issues.

enable-debug: false

When to enable:

  • Troubleshooting inventory loading issues
  • Debugging placeholder problems
  • Reporting bugs to the developer

enable-debug-time

Shows timing information for operations.

enable-debug-time: false

enable-performance-debug

Logs per-operation execution times when opening inventories (button building, item rendering, etc.).

enable-performance-debug: false

performance-debug:
  threshold-ms: 10   # Only show operations slower than this
  filter:
    mode: DISABLED   # DISABLED | WHITELIST | BLACKLIST
    operations: []   # Supports wildcards: "buildButton.*"

enable-information-message

Shows informational messages in console when an inventory or command is successfully loaded.

enable-information-message: true

skip-update-check

Skips the automatic update check on startup.

skip-update-check: false

Storage Settings

storage-type

Determines how player data is stored.

TypeDescription
SQLITELocal file-based database (default)
MYSQLMySQL server
MARIADBMariaDB server
NONENo persistent storage
storage-type: SQLITE

Recommendations:

  • Single server: Use SQLITE
  • Network/BungeeCord: Use MYSQL or MARIADB
  • No player data needed: Use NONE

database-configuration

MySQL/MariaDB connection settings.

database-configuration:
  table-prefix: "zmenu_"
  host: "localhost"
  port: 3306
  user: "minecraft"
  password: "secure_password"
  database: "minecraft_db"
  debug: false
OptionDescription
table-prefixPrefix for database tables
hostDatabase server address
portDatabase port (default: 3306)
userDatabase username
passwordDatabase password
databaseDatabase name
debugEnable SQL debug logging

batch-task

Interval in seconds for batching SQL saves. Instead of one query per update, all pending changes are saved in a single query.

batch-task: 10

Logging Settings

enable-player-open-inventory-logs

Logs when players open zMenu inventories to the database.

enable-player-open-inventory-logs: true

enable-log-storage-file

Prints console messages when configuration files are saved or loaded.

enable-log-storage-file: false

enable-open-message

When enabled, using /zm open <inventory> <player> <display> shows the display message to the target player.

enable-open-message: true

Formatting Settings

enable-mini-message-format

Enables MiniMessage formatting for text. Requires Minecraft 1.17+ and Paper (or a Paper fork).

enable-mini-message-format: true

When enabled, you can use:

name: "<gradient:red:blue>Gradient Text</gradient>"
lore:
  - "<rainbow>Rainbow!</rainbow>"
  - "<bold><gold>Bold gold</gold></bold>"

Command Settings

enable-player-command-in-chat

Forces player commands to run via chat rather than command dispatch. Useful for "fake" commands not registered in Paper/Spigot.

enable-player-command-in-chat: false

enable-player-commands-as-op-action

Allows buttons to execute commands with OP-level permissions.

enable-player-commands-as-op-action: false

Security Warning

Only enable this if you fully understand the security implications. Misuse can give players elevated permissions.

op-grant-method

The method used to temporarily grant elevated permissions (only when enable-player-commands-as-op-action: true).

MethodDescription
ATTACHMENTGrants * permission temporarily (recommended, safer)
SET_OPTemporarily sets the player as OP
BOTHCombines both methods (maximum compatibility)
op-grant-method: ATTACHMENT

Inventory Behavior

skip-close-actions-on-inventory-switch

Lists action types that are skipped when a player opens another zMenu inventory. Prevents actions like back or inventory from reopening old menus on inventory switch.

skip-close-actions-on-inventory-switch:
  - inventory
  - inv
  - back

enable-fast-event

Replaces some Bukkit events with a faster alternative for better performance.

enable-fast-event: false

disable-double-click-event

Prevents interactions from being triggered by double-clicking.

disable-double-click-event: true

all-clicks-type

List of click types handled by zMenu menus. Remove click types you don't want to handle.

all-clicks-type:
  - MIDDLE
  - RIGHT
  - LEFT
  - SHIFT_RIGHT
  - SHIFT_LEFT

Performance Settings

enable-cache-item-stack

Caches created ItemStacks to improve performance.

enable-cache-item-stack: true

Recommendation: Keep enabled unless you experience issues.

enable-cache-placeholder-api

Caches PlaceholderAPI results to reduce parsing overhead.

enable-cache-placeholder-api: false

Enabling this means placeholders won't update instantly. Use with caution.

cache-placeholder-api

Duration to cache placeholder results (in ticks).

cache-placeholder-api: 20  # 1 second

cache-offline-player

How long to cache offline player data (seconds).

cache-offline-player: 300  # 5 minutes

Click Settings

enable-cooldown-click

Prevents spam clicking by adding a cooldown between clicks.

enable-cooldown-click: true

cooldown-click-milliseconds

The cooldown duration between clicks.

cooldown-click-milliseconds: 100  # 0.1 seconds

Adjust based on your needs:

  • Lower = More responsive, risk of accidental double-clicks
  • Higher = Safer, might feel sluggish

Security Settings

enable-anti-dupe

Enables the anti-item-duplication system.

enable-anti-dupe: true

This detects and prevents common item duplication exploits involving inventory GUIs.

enable-anti-dupe-discord-notification

Sends a Discord webhook notification when a duplication attempt is detected.

enable-anti-dupe-discord-notification: false
anti-dupe-discord-webhook-url: "https://discord.com/api/webhooks/..."
anti-dupe-message: "**%player%** used %amount% %itemname% from zMenu. It has been removed!"

Supported placeholders in anti-dupe-message: %player%, %amount%, %itemname%.

enable-packet-event-click-limiter

Limits click packets received from players (requires the PacketEvents plugin).

enable-packet-event-click-limiter: false
packet-event-click-limiter-milliseconds: 50

The default inventory opened by the MAIN_MENU button type and the F key shortcut.

main-menu: "example"

This should match an inventory filename (without .yml) in your inventories/ folder.

use-swap-item-off-hand-key-to-open-main-menu

Allow players to press F (swap offhand key) to open the main menu.

use-swap-item-off-hand-key-to-open-main-menu: false

When to enable:

  • You want easy menu access without commands
  • Your server has a main hub menu

When to keep disabled:

  • Players need the F key for actual item swapping
  • You use custom resource packs with F key bindings

use-swap-item-off-hand-key-to-open-main-menu-needs-shift

When combined with use-swap-item-off-hand-key-to-open-main-menu: true, the player must also hold Shift to open the menu.

use-swap-item-off-hand-key-to-open-main-menu-needs-shift: false

specify-path-menus

List of specific menu file paths to load at startup. Leave empty to load all menus in the inventories/ folder.

specify-path-menus: []

generate-default-file

When enabled, creates default configuration files if they do not already exist.

generate-default-file: true

hot-reload

The hot reload has its own page with every detail: Hot Reload.

Watches the inventories/ folder (and all its subfolders) and applies your changes without any command:

  • Modified file: the inventory is reloaded.
  • New file: the inventory is loaded.
  • Deleted file (or deleted folder): the inventory is unloaded.
hot-reload:
  enable: false
  delay-milliseconds: 500
OptionDescription
enableEnables the hot reload. Disabled by default.
delay-millisecondsTime to wait after the last change of a file before reloading it. Text editors often save a file in several steps, this avoids reloading it several times.

Good to know:

  • Players viewing an inventory when it is reloaded see the new version open instantly, on the same page and with the same previous inventories (a back button opens the new version too). If the inventory is unloaded (file deleted, enable: false), it is closed.
  • A file that cannot be loaded (YAML syntax error, unknown button type, invalid size...) is not applied: the previous version stays loaded and the error is shown in the console until you fix the file.
  • Only the inventories/ folder is watched. Files listed in specify-path-menus, patterns and commands still require /zm reload.
  • Enabling or disabling the option takes effect after /zm reload or /zm reload config (or within two seconds when changed from the in-game configuration dialog).
  • On top of the file system events, the folder is scanned every two seconds. Changes are therefore detected even where the file system sends no event: Docker containers (Pterodactyl, bind mounts), WSL, network shares, files uploaded over SFTP.
  • A file is reloaded when its content or its modification date changes. Saving a file again without any change still reloads it, but the same version is never reloaded twice.

Console logs:

Every action is logged in the console with a [HotReload] prefix:

[zMenu] [HotReload] Inventory hot reload enabled, watching .../plugins/zMenu/inventories (native recursive watch, 12 file(s), 12 loaded inventory(ies), scan every 2000ms, delay 500ms).
[zMenu] [HotReload] Change detected on example.yml, reloading the inventory...
[zMenu] [HotReload] Inventory example.yml reloaded in 14ms, reopened for 1 player(s).

You will also see the YAML errors, the files that could not be loaded, the inventories unloaded after a deletion, and the files that are disabled (enable: false) or waiting for a load requirement. With enable-debug set to true, each file event, each change found by the scan and each ignored (unchanged) file is logged as well.

Troubleshooting: if nothing happens when you save a file, first check that the Inventory hot reload enabled line appears at startup or after /zm reload. Then enable enable-debug to see whether the changes are detected.

When to enable:

  • While creating or editing menus, to see your changes instantly
  • On a test/development server

dialog-list-max-depth

How many dialog_list dialogs can be nested inside each other (a list inside a list inside a list...). Default: 4.

dialog-list-max-depth: 4

This does not limit how many dialogs a list contains. A list sends every dialog it contains, including the content of nested lists, in the packet that opens it, so deep nesting makes that packet bigger and can disconnect the player. Lists nested deeper than this value are left out.

seconds-save-player-data

How often (in seconds) player data is automatically saved.

seconds-save-player-data: 600  # 10 minutes

seconds-save-player-inventories

How often (in seconds) player inventory data is automatically saved.

seconds-save-player-inventories: 600  # 10 minutes

Download / API Settings

enable-download-command

Enables the /zm download <url> [force] command to download inventories from a URL.

enable-download-command: false

api-url

The API URL for the Minecraft Inventory Builder website integration. Do not change this value.

api-url: "https://minecraft-inventory-builder.com/api/v2/"

Example Configurations

Basic Server (SQLite)

enable-debug: false
storage-type: SQLITE
enable-mini-message-format: true
enable-cache-item-stack: true
enable-anti-dupe: true
enable-cooldown-click: true
cooldown-click-milliseconds: 100
main-menu: "main"

Network Server (MySQL)

enable-debug: false
storage-type: MYSQL
database-configuration:
  table-prefix: "zmenu_"
  host: "mysql.mynetwork.com"
  port: 3306
  user: "zmenu_user"
  password: "secure_password_here"
  database: "minecraft_network"
enable-mini-message-format: true
enable-cache-item-stack: true
enable-cache-placeholder-api: true
cache-placeholder-api: 40
enable-anti-dupe: true
main-menu: "hub_menu"

Performance-Focused

enable-debug: false
storage-type: SQLITE
enable-cache-item-stack: true
enable-cache-placeholder-api: true
cache-placeholder-api: 60
cache-offline-player: 600
enable-cooldown-click: true
cooldown-click-milliseconds: 150

Development/Testing

enable-debug: true
enable-debug-time: true
enable-performance-debug: true
performance-debug:
  threshold-ms: 5
  filter:
    mode: DISABLED
    operations: []
skip-update-check: true
hot-reload:
  enable: true
storage-type: SQLITE
enable-cache-item-stack: false
enable-cache-placeholder-api: false
enable-cooldown-click: false
enable-player-open-inventory-logs: true

Reloading Configuration

After making changes:

/zm reload config

Or reload everything:

/zm reload

Database configuration changes require a server restart to take effect.

Best Practices

  1. Start with defaults: Only change what you need
  2. Enable caching on large servers: Improves performance
  3. Use MySQL for networks: Allows data sharing across servers
  4. Keep anti-dupe enabled: Protects your economy
  5. Test debug mode: Useful when setting up, disable in production
  6. Set appropriate click cooldown: Balance responsiveness and safety

Troubleshooting

Database Connection Failed

  1. Verify credentials are correct
  2. Check database server is running
  3. Ensure the database exists
  4. Check firewall allows connections
  5. Verify user has proper permissions

Placeholders Not Updating

  1. Disable placeholder caching temporarily
  2. Check if PlaceholderAPI is installed
  3. Verify the expansion is downloaded

Performance Issues

  1. Enable item stack caching
  2. Enable placeholder caching
  3. Increase click cooldown
  4. Check for inventory loops (A opens B opens A)

Next Steps

Custom Commands

Create custom commands to open your inventories

API Introduction

Getting started with the zMenu API

On this page

File LocationComplete Configuration ReferenceConfiguration Options ExplainedDebug Settingsenable-debugenable-debug-timeenable-performance-debugenable-information-messageskip-update-checkStorage Settingsstorage-typedatabase-configurationbatch-taskLogging Settingsenable-player-open-inventory-logsenable-log-storage-fileenable-open-messageFormatting Settingsenable-mini-message-formatCommand Settingsenable-player-command-in-chatenable-player-commands-as-op-actionop-grant-methodInventory Behaviorskip-close-actions-on-inventory-switchenable-fast-eventdisable-double-click-eventall-clicks-typePerformance Settingsenable-cache-item-stackenable-cache-placeholder-apicache-placeholder-apicache-offline-playerClick Settingsenable-cooldown-clickcooldown-click-millisecondsSecurity Settingsenable-anti-dupeenable-anti-dupe-discord-notificationenable-packet-event-click-limiterMenu Settingsmain-menuuse-swap-item-off-hand-key-to-open-main-menuuse-swap-item-off-hand-key-to-open-main-menu-needs-shiftspecify-path-menusgenerate-default-filehot-reloaddialog-list-max-depthseconds-save-player-dataseconds-save-player-inventoriesDownload / API Settingsenable-download-commandapi-urlExample ConfigurationsBasic Server (SQLite)Network Server (MySQL)Performance-FocusedDevelopment/TestingReloading ConfigurationBest PracticesTroubleshootingDatabase Connection FailedPlaceholders Not UpdatingPerformance IssuesNext 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.