115 lines
4.1 KiB
Markdown
115 lines
4.1 KiB
Markdown
# ⏳ Cooldowns & Répétition de Commandes - betterMcCommands
|
|
|
|
Ce guide détaille la gestion native des temps de recharge (cooldowns) par joueur et l'exécution cadencée / répétée d'actions de commandes.
|
|
|
|
---
|
|
|
|
## 📑 Sommaire
|
|
- [1. Configuration des Cooldowns](#1-configuration-des-cooldowns)
|
|
- [2. Permissions de Bypass de Cooldown](#2-permissions-de-bypass-de-cooldown)
|
|
- [3. Réinitialisation Manuelle de Cooldown](#3-réinitialisation-manuelle-de-cooldown)
|
|
- [4. Répétition & Tâches Cadencées (`CommandRepeater`)](#4-répétition--tâches-cadencées-commandrepeater)
|
|
|
|
---
|
|
|
|
## 1. Configuration des Cooldowns
|
|
|
|
Chaque commande ou sous-commande peut posséder son propre temps de recharge :
|
|
|
|
```java
|
|
BetterMcCommands.builder("kit")
|
|
.description("Kit quotidien")
|
|
.playerOnly()
|
|
// Cooldown de 24 heures
|
|
.cooldown(Duration.ofHours(24))
|
|
.executes(context -> {
|
|
context.replySuccess("Kit quotidien reçu !");
|
|
})
|
|
.register();
|
|
```
|
|
|
|
* Si un joueur exécute la commande pendant son cooldown, l'exécution est bloquée et un message l'informe du temps restant (ex: `Veuillez patienter 14h 25m avant de réutiliser cette commande`).
|
|
* L'événement `CommandCooldownEvent` est déclenché, permettant d'adapter le message ou d'annuler le blocage sous certaines conditions.
|
|
|
|
---
|
|
|
|
## 2. Permissions de Bypass de Cooldown
|
|
|
|
Pour autoriser certains groupes (VIP, Modérateurs, Staff) à ignorer le temps de recharge :
|
|
|
|
```java
|
|
BetterMcCommands.builder("heal")
|
|
.playerOnly()
|
|
.cooldown(Duration.ofMinutes(10))
|
|
// Les joueurs possédant cette permission n'ont aucun cooldown
|
|
.cooldownBypass("monplugin.heal.bypass")
|
|
.executes(context -> {
|
|
Player p = context.getPlayer();
|
|
p.setHealth(p.getMaxHealth());
|
|
context.replySuccess("Vous avez été soigné !");
|
|
})
|
|
.register();
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Réinitialisation Manuelle de Cooldown
|
|
|
|
Vous pouvez réinitialiser le cooldown d'un joueur par programmation :
|
|
|
|
```java
|
|
Command healCommand = ...;
|
|
Player target = Bukkit.getPlayer("Luc");
|
|
|
|
commandsManager.getCooldownManager().resetCooldown(healCommand, target);
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Répétition & Tâches Cadencées (`CommandRepeater`)
|
|
|
|
L'utilitaire `CommandRepeater` permet d'exécuter une action liée à la commande de manière répétée à intervalle régulier, tout en gérant le suivi de progression et la possibilité d'annulation prématurée.
|
|
|
|
### Exemple : Compte à rebours avant téléportation
|
|
```java
|
|
BetterMcCommands.builder("tpcountdown")
|
|
.playerOnly()
|
|
.executes(context -> {
|
|
Player p = context.getPlayer();
|
|
Location destination = p.getWorld().getSpawnLocation();
|
|
|
|
// Répète 5 fois toutes les 1 seconde (20 ticks)
|
|
CommandRepeater.repeat(monPlugin, context, 5, Duration.ofSeconds(1),
|
|
progress -> {
|
|
int secondesRestantes = progress.getTotalRuns() - progress.getCurrentRun() + 1;
|
|
|
|
// Si le joueur bouge, on peut annuler la boucle
|
|
if (hasMoved(p)) {
|
|
progress.cancel();
|
|
context.replyError("Téléportation annulée car vous avez bougé !");
|
|
return;
|
|
}
|
|
|
|
context.reply("<gold>Téléportation dans <yellow>" + secondesRestantes + "s</yellow>...</gold>");
|
|
},
|
|
() -> {
|
|
// Action finale exécutée après la fin des 5 secondes
|
|
p.teleport(destination);
|
|
context.replySuccess("Téléporté avec succès !");
|
|
}
|
|
);
|
|
})
|
|
.register();
|
|
```
|
|
|
|
### Méthodes de `CommandRepeatProgress` :
|
|
* `progress.getCurrentRun()` : Numéro de l'itération en cours (commence à 1).
|
|
* `progress.getTotalRuns()` : Nombre total d'itérations prévues.
|
|
* `progress.isLastRun()` : true si c'est la dernière itération.
|
|
* `progress.cancel()` : Interrompt immédiatement toutes les itérations restantes.
|
|
* `progress.getContext()` : Récupère le contexte d'exécution d'origine.
|
|
|
|
---
|
|
|
|
> 📖 **Étape suivante** : Découvrez le fonctionnement interne dans [07_PLATFORM_AND_INJECTION.md](07_PLATFORM_AND_INJECTION.md).
|