⏳ 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
2. Permissions de Bypass de Cooldown
3. Réinitialisation Manuelle de Cooldown
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 :

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 :

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 :

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

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.

4.1 KiB Raw Blame History