betterMcCommands/docs/04_LIFECYCLE_EVENTS.md

🎯 Système d'Événements & Cycle de Vie - betterMcCommands

betterMcCommands intègre un système d'événements complet permettant d'intercepter, modifier, auditer ou bloquer chaque étape de l'exécution d'une commande.

---

📑 Sommaire

• 1. Vue d'Ensemble du Cycle de Vie
• 2. Les Deux Méthodes d'Écoute
  • Méthode A : Hooks Fluides sur le Builder
  • Méthode B : Classes d'Écouteurs avec @CommandEventHandler
• 3. Référence Exhaustive des Événements
• 4. Exemples Pratiques

---

1. Vue d'Ensemble du Cycle de Vie

Lorsqu'un joueur ou la console exécute une commande :

1. Vérification d'émetteur et permission -> CommandPermissionDeniedEvent (si refus).
2. Vérification du Cooldown -> CommandCooldownEvent (si cooldown actif).
3. Parsing des arguments -> CommandSyntaxErrorEvent (si syntaxe invalide).
4. Demande de Confirmation -> CommandConfirmationRequiredEvent (si confirmation requise).
5. Pré-exécution -> CommandPreExecuteEvent (annulable).
6. Exécution métier -> Appel du CommandExecutor.
7. Post-exécution -> CommandPostExecuteEvent (durée d'exécution, statut de réussite/échec, logs).

---

2. Les Deux Méthodes d'Écoute

Méthode A : Hooks Fluides sur le Builder

Permet d'attacher un comportement spécifique directement à une commande :

BetterMcCommands.builder("trade")
    .onPreExecute(event -> {
        if (event.isPlayer() && isInCombat(event.getPlayer())) {
            event.setCancelled(true);
            event.reply("<red>Vous ne pouvez pas échanger en combat !</red>");
        }
    })
    .onPostExecute(event -> {
        System.out.println("Trade exécuté en " + event.getExecutionDuration().toMillis() + "ms.");
    })
    .executes(context -> {
        context.replySuccess("Échange ouvert !");
    })
    .register();

---

Méthode B : Classes d'Écouteurs avec @CommandEventHandler

Idéal pour centraliser la sécurité, l'audit et les métriques globales :

package fr.luc.monplugin.listener;

import fr.luc.bettermccommands.event.*;
import fr.luc.bettermccommands.event.annotation.CommandEventHandler;

public class CommandAuditListener {

    // Écoute TOUTES les commandes avant leur exécution
    @CommandEventHandler(priority = 10)
    public void onAnyPreExecute(CommandPreExecuteEvent event) {
        System.out.println("[Audit] Demande d'exécution : /" + event.getNode().getFullName() +
                " par " + event.getSender().getName());
    }

    // Écoute UNIQUEMENT la commande racine 'admin'
    @CommandEventHandler(command = "admin")
    public void onAdminPostExecute(CommandPostExecuteEvent event) {
        if (!event.isSuccessful()) {
            System.err.println("[Alerte Sécurité] Échec sur commande admin : " + event.getNode().getFullName());
        }
    }

    // Personnalise les messages de refus de permission
    @CommandEventHandler
    public void onPermissionDenied(CommandPermissionDeniedEvent event) {
        if (event.getRequiredPermission() != null) {
            event.setCustomErrorMessage("<dark_red><bold>Accès Refusé</bold></dark_red> : Permission requise <gray>[" + event.getRequiredPermission() + "]</gray>.");
        }
    }

    // Personnalise l'avertissement de cooldown
    @CommandEventHandler
    public void onCooldown(CommandCooldownEvent event) {
        event.setCustomMessage("<red>⏳ Patientez <gold>" + event.getRemainingCooldown().toSeconds() + "s</gold> avant de réutiliser cette commande.</red>");
    }
}

Pour enregistrer cette classe :

commandsManager.registerListeners(new CommandAuditListener());

---

3. Référence Exhaustive des Événements

Classe d'Événement	Description	Données Disponibles	Annulable ?
CommandPreExecuteEvent	Déclenché immédiatement avant l'exécution métier.	getNode(), getSender(), getContext()	✅ Oui
CommandPostExecuteEvent	Déclenché après la fin de l'exécution.	getResult(), getExecutionDuration(), getException(), isSuccessful()	❌ Non
CommandPermissionDeniedEvent	Déclenché lors d'un échec de permission ou restriction console/joueur.	getRequiredPermission(), getRequiredSenderType(), setCustomErrorMessage(...)	✅ Oui
CommandSyntaxErrorEvent	Déclenché lors d'un argument manquant ou format incorrect.	getErrorReason(), getUsage(), setCustomMessage(...)	✅ Oui
CommandCooldownEvent	Déclenché lorsqu'un joueur tente d'exécuter une commande sous cooldown.	getRemainingCooldown(), setCustomMessage(...)	✅ Oui
CommandConfirmationRequiredEvent	Déclenché lorsqu'une commande requiert une confirmation préalable.	getTimeout(), setCustomPromptMessage(...)	✅ Oui
CommandTabCompleteEvent	Déclenché lors du calcul des suggestions d'auto-complétion.	getSuggestions(), addSuggestion(...), getCurrentInput()	✅ Oui

---

📖 Étape suivante : Découvrez la validation et la confirmation dans 05_VALIDATION_AND_CONFIRMATION.md.