# Directives & Architecture du Projet betterMcGuis

## 🎯 Objectif
`betterMcGuis` est une bibliothèque Java moderne, fluide et événementielle pour la création dynamique d'interfaces graphiques (GUIs / Menus interactifs / Inventaires) sur serveurs Minecraft Paper et Spigot (1.20.4+).

## 🌟 Principes Clés
1. **DSL Fluide & Déclaratif** : Création chainable d'inventaires (Coffres 1-6 lignes, Hoppers, Distributeurs, Enclumes).
2. **ItemBuilder Riches** : Prise en charge native de MiniMessage, enchantements, flags, têtes de joueurs, armures teintées, CustomModelData et PDC.
3. **Système de Layouts / Patterns** : Définition visuelle des inventaires par matrice de caractères (ASCII Masks / Patterns).
4. **Types de GUIs Avancés** :
   - GUI Simple (`Gui`)
   - GUI Paginé (`PaginatedGui`)
   - GUI Défilant (`ScrollableGui`)
   - GUI à Onglets (`TabbedGui`)
   - GUI Animé (`AnimatedGui`)
   - GUI avec zones d'interaction / coffre de dépôt (`StorageGui` / `EditableSlots`)
5. **Gestionnaire d'Événements & Cycle de Vie** :
   - Événements complets : `GuiOpenEvent`, `GuiCloseEvent`, `GuiClickEvent`, `GuiPageChangeEvent`, `GuiRefreshEvent`.
   - Hooks locaux (`.onOpen()`, `.onClose()`, `.onClick()`) et écouteurs globaux annotés `@GuiEventHandler`.
6. **Protection contre les Glitches** :
   - Annulation sécurisée des clics, shift-clicks, drag-and-drop et échanges rapides (Hotbar swap).
   - Nettoyage automatique des états lors de la déconnexion ou fermeture de l'inventaire.
7. **Indépendance & Testabilité** : Classes métier découplées du moteur Minecraft pour des tests unitaires rapides et fiables.