docs: add guild development plan and pricing curve formulas

docs/guild_dev_plan.md

@@ -0,0 +1,196 @@
+# 🏰 Plan de Développement - Système de Guilde (GamingCore)
+
+**Date :** 20 Août 2026  
+**Projet :** Plugin de Guilde Minecraft (1.20.1+ / Paper API)  
+**Auteur :** Luc & Gemini Antigravity  
+
+---
+
+## 📖 1. Vision & Fonctionnalités Clés
+
+Le système de guilde permet aux joueurs de former des équipes, de revendiquer des territoires (chunks), d'accumuler des richesses dans une banque commune, et de gérer finement leur hiérarchie interne grâce à des **rangs et permissions personnalisables par guilde**.
+
+### 🌟 Piliers Fonctionnels :
+1. **Création & Territoire Initial** :
+   - Coût de création configurable (argent via Vault).
+   - Claim obligatoire du premier chunk lors de la création pour établir le cœur de la guilde.
+2. **Système de Claim de Chunks & Croissance des Coûts** :
+   - Claim chunk par chunk avec protection territoriale complète (anti-grief, accès aux coffres, interactions).
+   - Formule mathématique progressive pour le prix des chunks supplémentaires.
+3. **Banque de Guilde (Économie Vault)** :
+   - Compte en banque partagé pour payer les claims, les améliorations ou les taxes.
+   - Dépôts libres, retraits régis par permission de rang, journal des transactions.
+4. **Rangs & Permissions Personnalisables par Guilde** :
+   - Chaque guilde peut créer, modifier, renommer et supprimer ses propres rangs (ex: *Recrue*, *Guerrier*, *Officier*, *Général*, *Chef*).
+   - Attribution granulaire de permissions à chaque rang (Claim, Unclaim, Invite, Kick, Promote, Withdraw, etc.).
+5. **Invitations Sécurisées** :
+   - Invitations temporaires avec timer d'expiration (ex: 60s) et interface d'acceptation/refus.
+6. **Interface Graphique Moderne (Custom GUI & Textures Pixel-Art)** :
+   - Menus inventaires ergonomiques.
+   - Compatibilité avec les textures personnalisées de Resource Pack (glyphes d'icônes, overlays de conteneurs custom).
+
+---
+
+## 🧮 2. Formules Mathématiques du Prix des Chunks
+
+Pour équilibrer l'économie d'un serveur, le prix d'un chunk ne doit être ni trop punitif au début (pour encourager les petites guildes), ni trop bas sur la durée (pour éviter qu'une guilde n'accapare toute la carte).
+
+### 📐 Formule Recommandée : **Exponentielle Amortie Paramétrable**
+
+Soit $N$ le numéro du chunk à acheter ($N = 1$ est le 1er chunk de création) :
+
+$$\text{Prix}(N) = P_{\text{base}} \times \left(1 + \text{Taux}\right)^{(N - 1)^{\alpha}} + (N - 1) \times \text{Palier}$$
+
+#### ⚙️ Paramètres par défaut dans `config.yml` :
+* $P_{\text{base}} = 1\,000\$$ (Prix de base du premier chunk)
+* $\text{Taux} = 0.08$ (Croissance de +8% de base)
+* $\alpha = 0.95$ (Facteur d'amortissement pour lisser les grands nombres)
+* $\text{Palier} = 150\$$ (Ajout linéaire fixe par chunk)
+
+#### 📊 Tableau de simulation des coûts :
+| Chunk n° ($N$) | Coût du chunk | Coût cumulé total | Profil guilde |
+| :--- | :--- | :--- | :--- |
+| **1** (Création) | **1 000 $** | 1 000 $ | Début / Création |
+| **2** | **1 230 $** | 2 230 $ | Extension mineure |
+| **3** | **1 485 $** | 3 715 $ | Petite base (3 chunks) |
+| **5** | **2 080 $** | 7 510 $ | Base moyenne (5 chunks) |
+| **10** | **4 120 $** | 22 450 $ | Guilde active (10 chunks) |
+| **20** | **10 850 $** | 92 300 $ | Grande forteresse (20 chunks) |
+| **30** | **23 400 $** | 258 000 $ | Métropole / Empire |
+
+> 💡 **Variante 2 (Quadratique simple)** :  
+> $\text{Prix}(N) = P_{\text{base}} + A \cdot (N - 1)^2$ (Ex: $1000 + 50 \times (N-1)^2$)  
+> *Facile à comprendre pour les joueurs, progression douce au départ puis forte sur la fin.*
+
+---
+
+## 🗄️ 3. Schéma Relationnel de Base de Données (SQLite / MySQL)
+
+```
+┌────────────────────────────────────────────────────────┐
+│                        guilds                          │
+├────────────────────────────────────────────────────────┤
+│ id           VARCHAR(36) PK (UUID)                     │
+│ name         VARCHAR(16) UNIQUE                        │
+│ tag          VARCHAR(6)                                │
+│ description  VARCHAR(128)                              │
+│ balance      DOUBLE DEFAULT 0.0                        │
+│ home_world   VARCHAR(64)                               │
+│ home_x,y,z   DOUBLE                                    │
+│ home_yaw,pitch FLOAT                                   │
+│ created_at   TIMESTAMP                                 │
+└──────────────────────────┬─────────────────────────────┘
+                           │ 1:N
+         ┌─────────────────┼──────────────────┐
+         ▼                 ▼                  ▼
+┌──────────────────┐ ┌─────────────┐ ┌──────────────────┐
+│  guild_members   │ │ guild_ranks │ │   guild_claims   │
+├──────────────────┤ ├─────────────┤ ├──────────────────┤
+│ player_uuid PK   │ │ id PK       │ │ id PK (AUTO)     │
+│ guild_id FK      │ │ guild_id FK │ │ guild_id FK      │
+│ rank_id FK       │ │ name        │ │ world VARCHAR(64)│
+│ joined_at        │ │ priority INT│ │ chunk_x INT      │
+└──────────────────┘ │ perms TEXT  │ │ chunk_z INT      │
+                     │ is_default  │ │ claimed_at       │
+                     └─────────────┘ └──────────────────┘
+```
+
+---
+
+## 🛡️ 4. Permissions de Rangs Granulaires
+
+Chaque guilde possède des rangs personnalisés avec une liste de permissions activables/désactivables :
+
+| Permission | Description |
+| :--- | :--- |
+| `CLAIM` | Revendiquer de nouveaux chunks pour la guilde |
+| `UNCLAIM` | Libérer un chunk de la guilde |
+| `SET_HOME` | Définir le point de ralliement (`/guild sethome`) |
+| `HOME` | Se téléporter au point de ralliement (`/guild home`) |
+| `INVITE` | Inviter de nouveaux joueurs dans la guilde |
+| `KICK` | Expulser des membres de rang inférieur |
+| `PROMOTE` | Augmenter le rang d'un membre |
+| `DEMOTE` | Rétrograder le rang d'un membre |
+| `MANAGE_RANKS` | Créer, renommer, modifier les permissions des rangs |
+| `BANK_DEPOSIT` | Déposer de l'argent dans la banque de guilde |
+| `BANK_WITHDRAW`| Retirer de l'argent de la banque de guilde |
+| `INTERACT` | Ouvrir portes, boutons, leviers dans les claims |
+| `CONTAINER` | Ouvrir les coffres, fours, shulkers dans les claims |
+| `BUILD` | Poser des blocs dans les claims |
+| `BREAK` | Casser des blocs dans les claims |
+
+---
+
+## 🗺️ 5. Découpage en Phases de Développement
+
+```mermaid
+graph TD
+    A[Phase 1 : Économie Vault & Modèles de Données] --> B[Phase 2 : Système de Territoires & Claims de Chunks]
+    B --> C[Phase 3 : Gestionnaire de Rangs & Permissions Personnalisées]
+    C --> D[Phase 4 : Commandes & Invitations]
+    D --> E[Phase 5 : Protection des Terres & Listeners]
+    E --> F[Phase 6 : Interfaces Graphiques & Textures Pixel-Art]
+```
+
+### 📌 **Phase 1 : Intégration Économie & Base de Données**
+- Intégration de l'API **Vault** (`net.milkbowl.vault.economy.Economy`).
+- Mise en place du `DatabaseManager` (SQLite / MySQL) avec tables `guilds`, `guild_members`, `guild_ranks`, `guild_claims`.
+- Modèles Java (`Guild`, `GuildMember`, `GuildRank`, `GuildClaim`, `GuildPermission`).
+
+### 📌 **Phase 2 : Moteur de Claim & Calcul Mathématique**
+- Gestionnaire de coordonnées de chunks `(world, chunkX, chunkZ)`.
+- Implémentation de la formule mathématique de coût progressif.
+- Vérification de contiguïté des claims (optionnel : forcer les claims adjacents ou libres).
+
+### 📌 **Phase 3 : Hiérarchie Dynamique des Rangs**
+- Création automatique des 3 rangs par défaut à la création de la guilde :
+  - **👑 Chef (Leader)** : Toutes les permissions, non supprimable.
+  - **⚔ Officier (Officer)** : Invitations, claim, kick membres, accès banque.
+  - **🛡 Membre (Member)** : Rang par défaut, build, home, dépôt banque.
+- Mécanisme d'ajout/suppression/édition de rangs par le chef de guilde.
+
+### 📌 **Phase 4 : Commandes Complètes & Invitations**
+- Utilisation de notre **Command Framework Dynamique** :
+  - `/guild create <nom>` : Vérifie le solde Vault du joueur, claim le chunk actuel et crée la guilde.
+  - `/guild delete [confirm]` : Dissout la guilde et libère tous les claims.
+  - `/guild invite <joueur>` & `/guild accept <guilde>` / `/guild deny`.
+  - `/guild kick <joueur>`
+  - `/guild claim` & `/guild unclaim` (avec confirmation et affichage du prix calculé).
+  - `/guild bank [deposit|withdraw] <montant>`
+  - `/guild rank [create|delete|setperm|setpriority] ...`
+  - `/guild sethome` & `/guild home`
+  - `/guild info [guilde]` & `/guild members [guilde]`
+
+### 📌 **Phase 5 : Protection Territoriale (Listeners Bukkit)**
+- `BlockBreakListener` / `BlockPlaceListener` : Empêche les non-membres ou membres sans permission de construire.
+- `PlayerInteractListener` : Protection des coffres, portes, conteneurs.
+- `EntityDamageListener` / `ExplosionListener` : Protection anti-grief (creepers, TNT sur terres de guilde).
+- Notifications en Action Bar / Chat lors de l'entrée/sortie d'un territoire de guilde.
+
+### 📌 **Phase 6 : Menus Inventaires & Support Textures Pixel-Art**
+- Création d'un mini-framework d'inventaire interactif (`GuiManager`, `GuiButton`).
+- Menus principaux :
+  - Panneau de contrôle de la guilde (`/guild menu`).
+  - Gestionnaire de membres & rangs interactif.
+  - Journal de banque & interface de dépôt/retrait.
+- Intégration de textures pixel-art custom (Resource Pack).
+
+---
+
+## 🎨 6. Création de Textures Pixel-Art pour Menus / GUI
+
+**Oui, je suis tout à fait capable de concevoir et générer des textures pixel-art pour vos interfaces !**
+
+### Comment cela fonctionne concrètement :
+1. **Génération visuelle** : Je peux concevoir des textures pixel-art (arrières-plans de menus, cadres d'inventaires médiévaux/RPG, boutons custom, icônes de rangs, bannières de guilde).
+2. **Intégration Minecraft (Resource Pack)** :
+   - Création de la structure du Resource Pack (`assets/minecraft/textures/gui/...`).
+   - Configuration des polices personnalisées (`assets/minecraft/font/default.json`) et caractères d'espacement négatif (*negative space*).
+3. **Affichage dans le plugin** :
+   - Utilisation de Kyori Adventure / MiniMessage pour afficher le fond de texture personnalisé dans le titre de l'inventaire :
+     ```java
+     Component title = Component.text("\uE001").font(Key.key("gamingcore:gui"))
+             .append(Component.text(" Gestion de Guilde").color(NamedTextColor.DARK_GRAY));
+     Inventory gui = Bukkit.createInventory(null, 54, title);
+     ```
+   - Remplissage des slots avec les items interactifs positionnés précisément sur les emplacements de la texture.