# 🏰 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 (Spatio-Temporel)

Pour équilibrer l'expansion territoriale sur le serveur, le coût d'acquisition d'un nouveau chunk prend en compte **deux dimensions** :
1. **La Dimension Spatiale ($N$)** : La taille totale de la guilde (plus la guilde est grande, plus le prix structurel de base est élevé).
2. **La Dimension Temporelle / Vélocité ($R_{24h}$)** : Le nombre de chunks achetés récemment (fenêtre glissante de 24h).
3. **Le Couplage Espace-Temps** : Une grande guilde qui tente une expansion rapide subit une pénalité de surchauffe bien plus violente qu'une petite guilde.

---

### 📐 Modèle Mathématique Unifié

Le prix d'un chunk pour une guilde possédant $N$ chunks et ayant acheté $R$ chunks dans les dernières 24h est donné par :

$$\text{PrixFinal}(N, R) = P_{\text{structurel}}(N) \times M_{\text{surchauffe}}(N, R)$$

---

#### 1️⃣ Prix Structurel de Base : $P_{\text{structurel}}(N)$
$$P_{\text{structurel}}(N) = P_{\text{base}} \times \left(1 + \text{Taux}\right)^{(N - 1)^{\alpha}} + (N - 1) \times \text{Palier}$$

* $P_{\text{base}} = 1\,000\$$ (Prix du 1er chunk de création)
* $\text{Taux} = 0.08$ (+8% de croissance)
* $\alpha = 0.95$ (Facteur d'amortissement)
* $\text{Palier} = 150\$$ (Linéarité)

---

#### 2️⃣ Multiplicateur de Surchauffe Temporelle : $M_{\text{surchauffe}}(N, R)$
$$M_{\text{surchauffe}}(N, R) = 1 + \left( k_{\text{base}} + k_{\text{taille}} \times \left(\frac{N}{10}\right) \right) \times R^{\delta}$$

* **$R$** : Nombre de chunks achetés dans les dernières 24h ($R=0$ si 1er achat de la journée).
* **$k_{\text{base}} = 0.05$** : Hausse minimale de base (+5% par claim récent).
* **$k_{\text{taille}} = 0.03$** : Coefficient d'amplification selon la taille de la guilde (+3% de surchauffe par tranche de 10 chunks).
* **$\delta = 1.15$** : Exposant de sévérité anti-spam (rend les achats massifs consécutifs exponentiellement plus chers).

---

### 📊 Comparaison Concrète : Petite Guilde (5 chunks) vs Grande Guilde (50 chunks)

Imaginons que les deux guildes souhaitent acheter **5 nouveaux chunks consécutifs en moins de 24h** :

#### 🔹 Cas 1 : Petite Guilde (Taille actuelle : 5 chunks)
*Prix de base structurel : ~2 080 $ par chunk*
*Pénalité par claim récent : $+6.5\%$*

| Achat n° dans les 24h | $R$ (antécédents 24h) | Surchauffe ($M_{\text{surchauffe}}$) | Prix du chunk | Surcoût appliqué |
| :---: | :---: | :---: | :---: | :---: |
| **1er achat** (Chunk 6) | $R = 0$ | $\times 1.00$ | **2 400 $** | $+0\%$ |
| **2ème achat** (Chunk 7) | $R = 1$ | $\times 1.065$ | **2 930 $** | $+6.5\%$ |
| **3ème achat** (Chunk 8) | $R = 2$ | $\times 1.14$ | **3 580 $** | $+14.4\%$ |
| **4ème achat** (Chunk 9) | $R = 3$ | $\times 1.23$ | **4 360 $** | $+23.1\%$ |
| **5ème achat** (Chunk 10) | $R = 4$ | $\times 1.32$ | **5 280 $** | $+32.0\%$ |
| **Total dépensé (5 chunks)** | | | **18 550 $** | *(Hausse modérée, accessible)* |

---

#### 🔹 Cas 2 : Grande Guilde (Taille actuelle : 50 chunks)
*Prix de base structurel : ~48 500 $ par chunk*
*Pénalité par claim récent : $+20.0\%$ (amplifiée par la taille de 50 chunks)*

| Achat n° dans les 24h | $R$ (antécédents 24h) | Surchauffe ($M_{\text{surchauffe}}$) | Prix du chunk | Surcoût appliqué |
| :---: | :---: | :---: | :---: | :---: |
| **1er achat** (Chunk 51) | $R = 0$ | $\times 1.00$ | **50 200 $** | $+0\%$ |
| **2ème achat** (Chunk 52) | $R = 1$ | $\times 1.20$ | **62 400 $** | $+20.0\%$ |
| **3ème achat** (Chunk 53) | $R = 2$ | $\times 1.44$ | **77 900 $** | $+44.3\%$ |
| **4ème achat** (Chunk 54) | $R = 3$ | $\times 1.71$ | **96 000 $** | $+71.0\%$ |
| **5ème achat** (Chunk 55) | $R = 4$ | $\times 1.98$ | **116 000 $** | $+98.5\%$ |
| **Total dépensé (5 chunks)** | | | **402 500 $** | *(Hausse très punitive, le 5ème chunk coûte le double !)* |

---

### ⏱️ Décroissance Temporelle & Fenêtre Glissante (Rolling Window)

* **Calcul 100% Automatique via SQL** :
  ```sql
  SELECT COUNT(*) FROM guild_claims 
  WHERE guild_id = ? AND claimed_at >= DATETIME('now', '-24 hours');
  ```
* **Résultat en jeu** :
  * Si la guilde attend quelques heures, chaque claim vieux de plus de 24h sort automatiquement du calcul.
  * Le prix redescend naturellement à son niveau de base sans intervention ni timer lourd en mémoire.
  * Encourage la stratégie, la planification et évite les accaparements éclairs de territoires pendant les nuits ou périodes creuses.


---

## 🗄️ 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.
