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,60 @@
+# ⚙️ Plateforme & Injection CommandMap - betterMcCommands
+
+Ce document explique le fonctionnement sous le capot de l'injection dynamique, de l'isolation des namespaces et de la gestion du cycle de vie des commandes.
+
+---
+
+## 📑 Sommaire
+- [1. Comment Fonctionne l'Injection Dynamique ?](#1-comment-fonctionne-linjection-dynamique-)
+- [2. Enveloppe Bukkit (`PaperCommandWrapper`)](#2-enveloppe-bukkit-papercommandwrapper)
+- [3. Désenregistrement à Chaud & Hot Reload](#3-désenregistrement-à-chaud--hot-reload)
+- [4. Isolation et Multi-Instances](#4-isolation-et-multi-instances)
+
+---
+
+## 1. Comment Fonctionne l'Injection Dynamique ?
+
+Au lieu de forcer les développeurs à déclarer chaque commande dans le fichier `plugin.yml`, `betterMcCommands` utilise la classe `PaperCommandMapInjector` :
+
+1. **Résolution de la `CommandMap`** :
+   - Sur Paper / Bukkit moderne, `Bukkit.getServer().getCommandMap()` est interrogé.
+   - Sur les versions antérieures, un fallback par réflexion inspecte l'attribut `commandMap` de `CraftServer`.
+2. **Accès à la table des commandes connues (`knownCommands`)** :
+   - L'injecteur accède à la table interne `Map<String, Command>` de `SimpleCommandMap`.
+3. **Enregistrement de la commande racine et de ses alias** :
+   - La commande est enregistrée avec le préfixe du plugin (ex: `/monplugin:commande`).
+   - L'alias principal est rendu disponible directement (ex: `/commande`).
+
+---
+
+## 2. Enveloppe Bukkit (`PaperCommandWrapper`)
+
+Pour que le serveur Minecraft sache router les commandes vers le moteur `betterMcCommands`, chaque `Command` racine est enveloppée dans une instance de `PaperCommandWrapper` qui étend `org.bukkit.command.Command` :
+
+* `execute(CommandSender sender, String label, String[] args)` -> Transmet l'appel au `CommandDispatcher`.
+* `tabComplete(CommandSender sender, String alias, String[] args)` -> Calcule les suggestions via `CommandDispatcher.tabComplete(...)` et les retourne au client.
+
+---
+
+## 3. Désenregistrement à Chaud & Hot Reload
+
+Lorsqu'un plugin est désactivé (`onDisable()`) ou rechargé, il est primordial de retirer proprement les commandes pour éviter les fuites de mémoire et les conflits d'alias.
+
+L'appel à `commandsManager.unregisterAll()` :
+1. Dé-enregistre chaque wrapper de la `CommandMap`.
+2. Supprime toutes les entrées associées de la table `knownCommands`.
+3. Réinitialise le `CooldownManager` et le `ConfirmationManager`.
+4. Vide le bus d'événements `CommandEventManager`.
+
+---
+
+## 4. Isolation et Multi-Instances
+
+Chaque plugin utilisant `betterMcCommands` peut posséder sa propre instance indépendante grâce à :
+
+```java
+BetterMcCommands pluginA = BetterMcCommands.create(monPluginA);
+BetterMcCommands pluginB = BetterMcCommands.create(monPluginB);
+```
+
+Chaque instance possède son propre namespace, son propre bus d'événements et sa propre table de cooldowns/confirmations sans interférence mutuelle.