docs: ajout de la suite de documentation complète dans /docs et mise à jour du README

2026-08-23 18:04:36 +02:00
parent a2ccf0eb8c
commit 81edbea01d
8 changed files with 821 additions and 0 deletions
@@ -0,0 +1,114 @@
+# ⏳ 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).