Installation

This guide covers the installation and initial configuration of zEssentials.

RequirementsCopy Anchor Link

Before installing, ensure your server meets these requirements:

Supported VersionsCopy Anchor Link

zEssentials ships one NMS adapter per Minecraft version. The following versions are supported:

Supported PlatformsCopy Anchor Link

Installation StepsCopy Anchor Link

1. Download the PluginCopy Anchor Link

Download zEssentials from one of these sources:

• Modrinth
• groupez.dev
• Discord #builds channel for development versions

2. Install DependenciesCopy Anchor Link

Install the required dependencies on your server:

1. zMenu - Download from Modrinth and place the .jar in your plugins/ folder. zEssentials uses zMenu for all of its GUI interfaces.
2. PlaceholderAPI - Download from SpigotMC and place the .jar in your plugins/ folder. Required for placeholder support across all modules.

Both are declared as required server dependencies in paper-plugin.yml: Paper loads them before zEssentials and refuses to load zEssentials if one of them is missing.

Install any optional dependencies you need:

• Vault - Exposes the zEssentials economy to other plugins through the Vault API
• WorldGuard - Region protection checks (used by the WorldEdit module)
• SuperiorSkyblock2 - Island-based permission checks for skyblock servers
• BentoBox - Declared as an optional dependency so that it is loaded before zEssentials
• NuVotifier - Receives votes for the Vote module
• BlockTracker - Tracks player-placed blocks
• MythicMobs - Custom mob names in death messages
• NChat - Applies zEssentials mutes to NChat messages
• ProtocolLib - Optional packet-level integration, not required by any module
• AxVaults / PlayerVaults - Only needed to migrate vault data into zEssentials

See Hooks & Integrations for details on each integration.

3. Install the PluginCopy Anchor Link

1. Stop your server
2. Place zEssentials.jar in your plugins/ folder
3. Start your server
4. The plugin will generate all default configuration files and module configs

4. Verify InstallationCopy Anchor Link

Run /zessentials (alias /ess) in-game or from the console. If the plugin is loaded correctly, it displays the plugin version. You can also check the server console for lines similar to:

[zEssentials] Loading server plugin zEssentials v1.0.4.0
[zEssentials] Enabling zEssentials v1.0.4.0
[zEssentials] Create <n> commands.
[zEssentials] The database connection is valid ! (SQLITE)

If you see the following warning instead, the server is running Spigot and zEssentials is inactive:

[zEssentials] zEssentials is inactive: no commands, modules or API are available on Spigot.
[zEssentials] Install Paper, or a compatible fork, to use zEssentials.
[zEssentials] Download: https://papermc.io/downloads

File StructureCopy Anchor Link

After first startup, zEssentials creates the following structure:

plugins/zEssentials/
├── config.yml                          # Main configuration
├── database.db                         # SQLite database (if storage-type: SQLITE)
├── users/                              # Player files (if storage-type: JSON)
├── messages/                           # Message files (EN, FR, DE, ES, IT, NL, ZH)
├── patterns/                           # zMenu patterns (home_up.yml, home_down.yml)
└── modules/
    ├── afk/config.yml                  # AFK detection
    ├── automessage/config.yml          # Automatic announcements
    ├── chat/config.yml                 # Chat formatting, ping, item display
    ├── customcommands/config.yml       # Your own commands (/discord, /map...)
    ├── death_message/config.yml        # Death messages
    ├── discord/config.yml              # Discord webhooks and account linking
    ├── economy/                        # config.yml, baltop.yml, confirm_pay_inventory.yml
    ├── hologram/                       # config.yml, holograms/
    ├── home/                           # config.yml, homes.yml, homes_donut.yml, home_delete.yml, public_homes.yml
    ├── items/config.yml                # Item utilities
    ├── join_quit/config.yml            # Join/quit messages
    ├── kits/                           # config.yml, kits.yml, kit_preview.yml, kits_categories.yml, kits/
    ├── mailbox/                        # config.yml, mailbox.yml, mailbox_admin.yml
    ├── messages/config.yml             # Private messages
    ├── rules/                          # config.yml, rules.yml
    ├── sanction/                       # config.yml, sanction.yml, sanctions.yml, sanction_history.yml
    ├── scoreboard/config.yml           # Dynamic scoreboard
    ├── spawn/config.yml                # Spawn and first spawn
    ├── steps/config.yml                # Step/progression tracking
    ├── teleportation/                  # config.yml, confirm_request_inventory.yml, confirm_request_here_inventory.yml
    ├── vault/                          # config.yml, vault.yml, vault-admin.yml, vault-configuration.yml
    ├── vote/                           # config.yml, vote.yml
    ├── warp/                           # config.yml, warps.yml
    └── worldedit/                      # config.yml, pw-help.yml

Database ConfigurationCopy Anchor Link

zEssentials supports several storage backends, selected with the storage-type option in config.yml. See the Database page for the full details.

SQLite (Default)Copy Anchor Link

SQLite is the default storage method and requires no additional configuration. Best for testing:

storage-type: SQLITE

The database file is stored at plugins/zEssentials/database.db.

MySQL / MariaDB / HikariCPCopy Anchor Link

Recommended for production environments and multi-server setups:

storage-type: HIKARICP # or MYSQL / MARIADB

database-configuration:
  table-prefix: "zessentials_"
  host: 192.168.10.10
  port: 3306
  user: homestead
  password: 'secret'
  database: zessentials
  debug: false

MYSQL, MARIADB and HIKARICP all use a HikariCP connection pool. MARIADB connects with the MariaDB driver (jdbc:mariadb:), the two other values use a jdbc:mysql: URL.

Default Database Configuration ValuesCopy Anchor Link

Redis ConfigurationCopy Anchor Link

The configuration file contains a Redis section intended for multi-server synchronization (cross-server private messages, kicks, broadcasts, cooldowns...):

redis-configuration:
  host: "192.168.10.10"
  port: 6379
  password: "123456a"

Server Type ConfigurationCopy Anchor Link

server-type: PAPER

First ConfigurationCopy Anchor Link

After installation, here are the recommended first steps:

1. Storage - Choose your storage backend (SQLITE, MYSQL, MARIADB or HIKARICP) in config.yml
2. Modules - Review and enable/disable modules in the modules/ directory based on your needs
3. Economy - If using the Economy module, configure it in modules/economy/config.yml and install Vault if other plugins need to use it
4. Homes - Set home limits per permission in modules/home/config.yml
5. Kits - Create your server kits in modules/kits/kits/
6. First join - Enable enable-first-join-teleport in config.yml if new players must be teleported to the first spawn (disabled by default)
7. Messages - Customize plugin messages in the messages/ directory

See the Configuration section for detailed options.

TroubleshootingCopy Anchor Link

Plugin does not startCopy Anchor Link

• Make sure the server runs Paper (or a fork) 1.20.6+. On Spigot, zEssentials stays inactive and only logs a warning.
• Check the Java version with java -version: Java 21+ is required, Java 25 for Minecraft 26.x
• Verify that zMenu and PlaceholderAPI are installed and load without errors
• Check that the server could download the MariaDB driver on first start (internet access or Maven Central mirror)
• Check the server console for error messages referencing fr.maxlego08.essentials.ZEssentialsPlugin
• Ensure the .jar file is not corrupted by re-downloading it

"Cannot initialize zEssentials: zMenu ... service is unavailable"Copy Anchor Link

zEssentials retrieves the zMenu services (InventoryManager, ButtonManager and PatternManager) as soon as it enables. If zMenu failed to enable, zEssentials now stops immediately with an explicit error instead of failing later:

Cannot initialize zEssentials: zMenu InventoryManager service is unavailable. Check that zMenu enabled successfully and its API is shared with zEssentials.

• Scroll up in the console and fix the error reported by zMenu first (outdated version, missing dependency...)
• Update zMenu to the latest version
• Do not load or reload zEssentials or zMenu at runtime with a plugin manager, restart the server instead

Modules not loadingCopy Anchor Link

• Verify the module folder exists in plugins/zEssentials/modules/
• Check that the module is set to enable: true in its config.yml
• Look for errors in the console that reference the specific module name
• Ensure all optional dependencies used by that module are installed (e.g. NuVotifier for votes)

Database connection failedCopy Anchor Link

• Verify your database credentials in config.yml are correct
• Ensure the MySQL/MariaDB server is running and accessible from the Minecraft server
• Check firewall settings if using a remote database
• Confirm the database specified in the configuration exists and the user has proper permissions
• Enable database-configuration.debug to log the SQL queries

Economy not workingCopy Anchor Link

• Check the Economy module is enabled in modules/economy/config.yml
• If other plugins use Vault, ensure Vault is installed: zEssentials registers itself as the Vault economy provider (only the economy with vault: true is exposed)
• Run /vault-info to verify that Vault detects zEssentials as the economy provider

PlaceholderAPI placeholders not workingCopy Anchor Link

• Ensure PlaceholderAPI is installed and loaded
• Run /papi list to check if the zEssentials expansion is registered
• Verify the placeholder syntax is correct (e.g. %zessentials_user_balance_money%)

Interfaces not appearingCopy Anchor Link

• Verify zMenu is installed and working properly
• Check that the inventory files exist in the module folders (e.g. modules/home/homes.yml)
• Look for errors in the console when attempting to open a menu
• Ensure zMenu is up to date with the latest version

Next StepsCopy Anchor Link

• Commands & Permissions
• Placeholders
• Configuration
• Database
• API & Events