# ⏳ 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).