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,128 @@
+# 🏗️ 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).