Installation

Ce guide couvre l'installation et la configuration initiale de zEssentials.

PrérequisCopier le lien vers ce titre

Avant l'installation, assurez-vous que votre serveur répond à ces exigences :

Versions supportéesCopier le lien vers ce titre

zEssentials embarque un adaptateur NMS par version de Minecraft. Les versions suivantes sont supportées :

Plateformes supportéesCopier le lien vers ce titre

Étapes d'installationCopier le lien vers ce titre

1. Télécharger le pluginCopier le lien vers ce titre

Téléchargez zEssentials depuis l'une de ces sources :

• Modrinth
• groupez.dev
• Le salon Discord #builds pour les versions de développement

2. Installer les dépendancesCopier le lien vers ce titre

Installez les dépendances requises sur votre serveur :

1. zMenu - Téléchargez-le depuis Modrinth et placez le .jar dans votre dossier plugins/. zEssentials utilise zMenu pour toutes ses interfaces.
2. PlaceholderAPI - Téléchargez-le depuis SpigotMC et placez le .jar dans votre dossier plugins/. Requis pour le support des placeholders dans tous les modules.

Ces deux plugins sont déclarés comme dépendances serveur obligatoires dans le paper-plugin.yml : Paper les charge avant zEssentials et refuse de charger zEssentials si l'un d'eux est absent.

Installez les dépendances optionnelles dont vous avez besoin :

• Vault - Expose l'économie de zEssentials aux autres plugins via l'API Vault
• WorldGuard - Vérification des régions protégées (utilisée par le module WorldEdit)
• SuperiorSkyblock2 - Vérification des permissions sur les îles pour les serveurs skyblock
• BentoBox - Déclaré comme dépendance optionnelle pour être chargé avant zEssentials
• NuVotifier - Réception des votes pour le module Vote
• BlockTracker - Suivi des blocs posés par les joueurs
• MythicMobs - Noms des mobs personnalisés dans les messages de mort
• NChat - Applique les mutes de zEssentials aux messages NChat
• ProtocolLib - Intégration optionnelle au niveau des paquets, requise par aucun module
• AxVaults / PlayerVaults - Uniquement nécessaires pour migrer les données des coffres vers zEssentials

Consultez Hooks & Intégrations pour le détail de chaque intégration.

3. Installer le pluginCopier le lien vers ce titre

1. Arrêtez votre serveur
2. Placez zEssentials.jar dans votre dossier plugins/
3. Démarrez votre serveur
4. Le plugin génère tous les fichiers de configuration par défaut ainsi que ceux des modules

4. Vérifier l'installationCopier le lien vers ce titre

Exécutez /zessentials (alias /ess) en jeu ou depuis la console. Si le plugin est correctement chargé, il affiche sa version. Vous pouvez également vérifier dans la console du serveur la présence de lignes similaires à :

[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)

Si vous voyez plutôt l'avertissement suivant, le serveur tourne sous Spigot et zEssentials est inactif :

[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

Structure des fichiersCopier le lien vers ce titre

Après le premier démarrage, zEssentials crée la structure suivante :

plugins/zEssentials/
├── config.yml                          # Configuration principale
├── database.db                         # Base SQLite (si storage-type: SQLITE)
├── users/                              # Fichiers des joueurs (si storage-type: JSON)
├── messages/                           # Fichiers de messages (EN, FR, DE, ES, IT, NL, ZH)
├── patterns/                           # Patterns zMenu (home_up.yml, home_down.yml)
└── modules/
    ├── afk/config.yml                  # Détection AFK
    ├── automessage/config.yml          # Annonces automatiques
    ├── chat/config.yml                 # Format du chat, ping, affichage d'items
    ├── customcommands/config.yml       # Vos propres commandes (/discord, /map...)
    ├── death_message/config.yml        # Messages de mort
    ├── discord/config.yml              # Webhooks Discord et liaison de comptes
    ├── 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                # Utilitaires d'items
    ├── join_quit/config.yml            # Messages de connexion/déconnexion
    ├── kits/                           # config.yml, kits.yml, kit_preview.yml, kits_categories.yml, kits/
    ├── mailbox/                        # config.yml, mailbox.yml, mailbox_admin.yml
    ├── messages/config.yml             # Messages privés
    ├── rules/                          # config.yml, rules.yml
    ├── sanction/                       # config.yml, sanction.yml, sanctions.yml, sanction_history.yml
    ├── scoreboard/config.yml           # Scoreboard dynamique
    ├── spawn/config.yml                # Spawn et premier spawn
    ├── steps/config.yml                # Suivi des étapes/progression
    ├── 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

Configuration de la base de donnéesCopier le lien vers ce titre

zEssentials supporte plusieurs moteurs de stockage, choisis avec l'option storage-type du config.yml. Consultez la page Base de données pour tous les détails.

SQLite (par défaut)Copier le lien vers ce titre

SQLite est le stockage par défaut et ne nécessite aucune configuration supplémentaire. Idéal pour les tests :

storage-type: SQLITE

Le fichier de base de données est stocké dans plugins/zEssentials/database.db.

MySQL / MariaDB / HikariCPCopier le lien vers ce titre

Recommandé pour les environnements de production et les configurations multi-serveurs :

storage-type: HIKARICP # ou MYSQL / MARIADB

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

MYSQL, MARIADB et HIKARICP utilisent tous un pool de connexions HikariCP. MARIADB se connecte avec le driver MariaDB (jdbc:mariadb:), les deux autres valeurs utilisent une URL jdbc:mysql:.

Valeurs par défaut de la configurationCopier le lien vers ce titre

Configuration RedisCopier le lien vers ce titre

Le fichier de configuration contient une section Redis prévue pour la synchronisation multi-serveurs (messages privés, kicks, annonces, cooldowns entre serveurs...) :

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

Type de serveurCopier le lien vers ce titre

server-type: PAPER

Première configurationCopier le lien vers ce titre

Après l'installation, voici les premières étapes recommandées :

1. Stockage - Choisissez votre moteur de stockage (SQLITE, MYSQL, MARIADB ou HIKARICP) dans config.yml
2. Modules - Passez en revue les modules du dossier modules/ et activez/désactivez-les selon vos besoins
3. Économie - Si vous utilisez le module Économie, configurez-le dans modules/economy/config.yml et installez Vault si d'autres plugins doivent l'utiliser
4. Homes - Définissez les limites de homes par permission dans modules/home/config.yml
5. Kits - Créez les kits de votre serveur dans modules/kits/kits/
6. Première connexion - Activez enable-first-join-teleport dans config.yml si les nouveaux joueurs doivent être téléportés au premier spawn (désactivé par défaut)
7. Messages - Personnalisez les messages du plugin dans le dossier messages/

Consultez la section Configuration pour le détail des options.

DépannageCopier le lien vers ce titre

Le plugin ne démarre pasCopier le lien vers ce titre

• Vérifiez que le serveur tourne sous Paper (ou un fork) 1.20.6+. Sur Spigot, zEssentials reste inactif et affiche seulement un avertissement.
• Vérifiez la version de Java avec java -version : Java 21+ est requis, Java 25 pour Minecraft 26.x
• Vérifiez que zMenu et PlaceholderAPI sont installés et se chargent sans erreur
• Vérifiez que le serveur a pu télécharger le driver MariaDB au premier démarrage (accès Internet ou miroir Maven Central)
• Recherchez dans la console les erreurs mentionnant fr.maxlego08.essentials.ZEssentialsPlugin
• Assurez-vous que le fichier .jar n'est pas corrompu en le téléchargeant à nouveau

« Cannot initialize zEssentials: zMenu ... service is unavailable »Copier le lien vers ce titre

zEssentials récupère les services de zMenu (InventoryManager, ButtonManager et PatternManager) dès son activation. Si zMenu n'a pas réussi à s'activer, zEssentials s'arrête désormais immédiatement avec une erreur explicite au lieu d'échouer plus tard :

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

• Remontez dans la console et corrigez d'abord l'erreur signalée par zMenu (version obsolète, dépendance manquante...)
• Mettez zMenu à jour vers la dernière version
• Ne chargez pas et ne rechargez pas zEssentials ou zMenu à chaud avec un gestionnaire de plugins, redémarrez plutôt le serveur

Les modules ne se chargent pasCopier le lien vers ce titre

• Vérifiez que le dossier du module existe dans plugins/zEssentials/modules/
• Vérifiez que le module est configuré avec enable: true dans son config.yml
• Recherchez dans la console les erreurs mentionnant le nom du module
• Assurez-vous que les dépendances optionnelles utilisées par ce module sont installées (par exemple NuVotifier pour les votes)

Échec de la connexion à la base de donnéesCopier le lien vers ce titre

• Vérifiez que les identifiants de la base de données dans config.yml sont corrects
• Assurez-vous que le serveur MySQL/MariaDB est démarré et accessible depuis le serveur Minecraft
• Vérifiez les règles du pare-feu si vous utilisez une base de données distante
• Confirmez que la base indiquée dans la configuration existe et que l'utilisateur possède les permissions nécessaires
• Activez database-configuration.debug pour afficher les requêtes SQL

L'économie ne fonctionne pasCopier le lien vers ce titre

• Vérifiez que le module Économie est activé dans modules/economy/config.yml
• Si d'autres plugins utilisent Vault, assurez-vous que Vault est installé : zEssentials s'enregistre lui-même comme fournisseur d'économie Vault (seule l'économie avec vault: true est exposée)
• Exécutez /vault-info pour vérifier que Vault détecte bien zEssentials comme fournisseur d'économie

Les placeholders PlaceholderAPI ne fonctionnent pasCopier le lien vers ce titre

• Assurez-vous que PlaceholderAPI est installé et chargé
• Exécutez /papi list pour vérifier que l'expansion zEssentials est enregistrée
• Vérifiez la syntaxe du placeholder (par exemple %zessentials_user_balance_money%)

Les interfaces ne s'affichent pasCopier le lien vers ce titre

• Vérifiez que zMenu est installé et fonctionne correctement
• Vérifiez que les fichiers d'inventaires existent dans les dossiers des modules (par exemple modules/home/homes.yml)
• Recherchez des erreurs dans la console lors de l'ouverture d'un menu
• Assurez-vous que zMenu est à jour

Étapes suivantesCopier le lien vers ce titre

• Commandes & Permissions
• Placeholders
• Configuration
• Base de données
• API & Événements