121 lines
5.3 KiB
Markdown
121 lines
5.3 KiB
Markdown
# 🎯 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](#1-vue-densemble-du-cycle-de-vie)
|
|
- [2. Les Deux Méthodes d'Écoute](#2-les-deux-méthodes-découte)
|
|
- [Méthode A : Hooks Fluides sur le Builder](#méthode-a--hooks-fluides-sur-le-builder)
|
|
- [Méthode B : Classes d'Écouteurs avec `@CommandEventHandler`](#méthode-b--classes-découteurs-avec-commandeventhandler)
|
|
- [3. Référence Exhaustive des Événements](#3-référence-exhaustive-des-événements)
|
|
- [4. Exemples Pratiques](#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 :
|
|
|
|
```java
|
|
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 :
|
|
|
|
```java
|
|
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 :
|
|
```java
|
|
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](05_VALIDATION_AND_CONFIRMATION.md).
|