# 🏗️ 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`)](#1-commande-racine-bettermccommandsbuilder)
- [2. Sous-Commandes Imbriquées (`BetterMcCommands.subBuilder`)](#2-sous-commandes-imbriquées-bettermccommandssubbuilder)
- [3. Restrictions d'Émetteurs (`CommandSenderType`)](#3-restrictions-démetteurs-commandsendertype)
- [4. Permissions et Alias](#4-permissions-et-alias)
- [5. Le Contexte d'Exécution (`CommandContext`)](#5-le-contexte-dexécution-commandcontext)

---

## 1. Commande Racine (`BetterMcCommands.builder`)

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

```java
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 :

```java
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](03_TYPED_ARGUMENTS.md).