betterMcCommands/docs/02_COMMAND_BUILDER_DSL.md

🏗️ Fluent Builder DSL - betterMcCommands

La création de commandes et de sous-commandes repose sur un pattern Builder chainable et intuitif.

---

📑 Sommaire

• 1. Commande Racine (BetterMcCommands.builder)
• 2. Sous-Commandes Imbriquées (BetterMcCommands.subBuilder)
• 3. Restrictions d'Émetteurs (CommandSenderType)
• 4. Permissions et Alias
• 5. Le Contexte d'Exécution (CommandContext)

---

1. Commande Racine (BetterMcCommands.builder)

Une commande racine est créée via BetterMcCommands.builder(String name) :

BetterMcCommands.builder("spawn")
    .description("Téléporte le joueur au point d'apparition")
    .aliases("hub", "lobby")
    .permission("monplugin.command.spawn")
    .playerOnly()
    .executes(context -> {
        Player player = context.getPlayer();
        player.teleport(player.getWorld().getSpawnLocation());
        context.replySuccess("Téléportation au spawn effectuée !");
    })
    .register();

---

2. Sous-Commandes Imbriquées (BetterMcCommands.subBuilder)

Vous pouvez ajouter autant de sous-commandes que nécessaire avec subBuilder(String name) et les imbriquer sans limite de profondeur :

BetterMcCommands.builder("guilde")
    .description("Gestion de votre guilde")
    .permission("guilde.use")
    // /guilde (sans sous-commande) affiche l'aide par défaut
    .executes(context -> {
        context.reply("<yellow>=== Commandes de Guilde ===</yellow>");
        context.reply("<gold>/guilde info</gold> <gray>- Informations sur votre guilde</gray>");
        context.reply("<gold>/guilde admin rank set <joueur> <grade></gold> <gray>- Rangs</gray>");
    })
    
    // Sous-commande : /guilde info
    .subcommand(BetterMcCommands.subBuilder("info")
        .description("Affiche les infos de la guilde")
        .executes(context -> {
            context.replySuccess("Informations de la guilde affichées.");
        })
    )
    
    // Sous-commandes imbriquées : /guilde admin rank set <joueur> <grade>
    .subcommand(BetterMcCommands.subBuilder("admin")
        .description("Administration de guilde")
        .permission("guilde.admin")
        .subcommand(BetterMcCommands.subBuilder("rank")
            .description("Gestion des rangs")
            .subcommand(BetterMcCommands.subBuilder("set")
                .description("Attribue un rang à un membre")
                .argument(Arguments.player("joueur"))
                .argument(Arguments.string("grade"))
                .executes(context -> {
                    Player cible = context.getTargetPlayer("joueur");
                    String grade = context.getString("grade");
                    context.replySuccess("Grade " + grade + " appliqué à " + cible.getName());
                })
            )
        )
    )
    .register();

---

3. Restrictions d'Émetteurs (CommandSenderType)

Contrôlez qui a le droit d'exécuter la commande :

• .playerOnly() : Seuls les joueurs connectés en jeu peuvent exécuter la commande.
• .consoleOnly() : Seule la console du serveur peut exécuter la commande.
• .senderType(CommandSenderType.ALL) (défaut) : Tous les émetteurs sont autorisés.

En cas de non-respect, un message d'erreur est automatiquement retourné et l'événement CommandPermissionDeniedEvent est déclenché.

---

4. Permissions et Alias

• .permission("ma.permission") : Spécifie la permission Bukkit requise.
• .aliases("alias1", "alias2", ...) : Enregistre un ou plusieurs alias qui redirigent vers cette commande ou sous-commande.

---

5. Le Contexte d'Exécution (CommandContext)

L'objet CommandContext transmis à l'exécuteur executes(context -> ...) fournit :

Méthode	Description
context.getSender()	Récupère l'émetteur brut (CommandSender).
context.getPlayer()	Récupère le joueur (Player) ou lève une exception si console.
context.getConsole()	Récupère la console (ConsoleCommandSender).
context.isPlayer()	Teste si l'émetteur est un joueur.
context.getLabel()	Retourne l'alias ou le nom utilisé pour l'appel.
context.getRawArgs()	Retourne le tableau des arguments bruts passés par le joueur.
context.get(name, Class<T>)	Récupère un argument converti et typé.
context.getString(name)	Récupère un argument de type chaîne.
context.getInt(name)	Récupère un argument entier.
context.getDouble(name)	Récupère un argument décimal.
context.getBoolean(name)	Récupère un argument booléen.
context.getTargetPlayer(name)	Récupère un joueur cible (Player).
context.getWorld(name)	Récupère un monde Bukkit (World).
context.getDuration(name)	Récupère une durée (Duration).
context.reply(miniMessage)	Envoie un message formaté en MiniMessage.
context.replySuccess(msg)	Envoie un message de succès préfixé en vert.
context.replyError(msg)	Envoie un message d'erreur préfixé en rouge.
context.setMetadata(key, val)	Stocke une donnée contextuelle temporaire.

---

📖 Étape suivante : Explorez tous les types d'arguments disponibles dans 03_TYPED_ARGUMENTS.md.