# 📜 Instructions & Consignes du Projet - GamingCore (Système de Guilde)

Ce document consigne les directives d'architecture, règles de développement et spécifications fonctionnelles du projet **GamingCore**.

---

## 🎯 1. Vision du Projet
Développement d'un système de **Guilde complet, modulaire et hautement configurable** pour Minecraft (Paper 1.20.1+ / Java 21 LTS - target Java 17).

---

## 📐 2. Règles & Standards de Développement

### 🔹 Conception du Code
* **Méthodes & Logique Métier d'Abord** : Tout le système doit reposer sur des méthodes et services métier découplés (Managers, Repositories, Calculators), indépendants du système de commande ou d'UI.
* **Dynamisme & Modularité** : Le code doit être découpé en parties logiques claires et évolutives.
* **Documentation Obligatoire** : **Chaque méthode** doit comporter une Javadoc / un commentaire détaillé explicitant :
  * Son rôle et son comportement.
  * Ses paramètres (`@param`).
  * Sa valeur de retour (`@return`).
  * Les éventuelles exceptions levées (`@throws`).

### 🔹 Dépendances & Intégrations
* **Paper API 1.20.4** : API Bukkit/Paper cross-version.
* **Vault API 1.7.1** : Gestion de l'économie (dépôt, retrait, vérification de solde).
* **WorldGuard 7.0.9 & WorldEdit 7.3.0** : Intégration et compatibilité régionale.
* **Kyori Adventure & MiniMessage** : Couleurs HEX, gradients et composants de texte modernes.
* **XSeries 13.0.0** : Abstraction des matériaux, sons et particules.

---

## 🏰 3. Spécifications Métier du Système de Guilde

### 1. Structure d'une Guilde
* Création soumise à un coût économique (Vault) et au claim obligatoire du chunk initial.
* Données : `UUID`, `nom`, `tag`, `description`, `solde bancaire`, `point de ralliement (home)`, `membres`, `rangs`, `claims`.

### 2. Rangs & Permissions Dynamiques par Guilde
* Chaque guilde peut créer, renommer, hiérarchiser (priorité) et supprimer ses propres rangs.
* Rangs initiaux par défaut à la création :
  * **👑 Chef (Leader)** : Priorité maximale (100), toutes les permissions, non supprimable.
  * **⚔ Officier (Officer)** : Priorité intermédiaire (50), gestion des membres et claims.
  * **🛡 Membre (Member)** : Priorité de base (1), rang par défaut des recrues.
* Permissions granulaires configurables par rang :
  * `CLAIM`, `UNCLAIM`, `SET_HOME`, `HOME`, `INVITE`, `KICK`, `PROMOTE`, `DEMOTE`, `MANAGE_RANKS`, `BANK_DEPOSIT`, `BANK_WITHDRAW`, `BUILD`, `BREAK`, `INTERACT`, `CONTAINER`.

### 3. Moteur Économique & Calcul Spatio-Temporel des Chunks
Le prix d'acquisition d'un nouveau chunk suit la formule spatio-temporelle avec surchauffe glissante sur 24h :

$$\text{PrixFinal}(N, R) = \left[ P_{\text{base}} \times (1 + \text{Taux})^{(N - 1)^\alpha} + (N - 1) \times \text{Palier} \right] \times \left[ 1 + \left( k_{\text{base}} + k_{\text{taille}} \times \left(\frac{N}{10}\right) \right) \times R^{\delta} \right]$$

* **$N$** : Nombre total de chunks possédés.
* **$R$** : Nombre de chunks achetés dans les dernières 24h (décroissance automatique).
* **Effet d'échelle** : La surchauffe temporelle est plus sévère pour une grande guilde que pour une petite.

### 4. Banque de Guilde
* Solde partagé avec dépôts libres et retraits sécurisés par permissions de rang.

### 5. Invitations
* Invitations temporaires expirables (ex: 60s) avec acceptation/refus.

### 6. Protection Territoriale & Listeners
* Protection des blocs, conteneurs, portes et explosions sur les chunks de guilde en fonction des permissions de rang du joueur.

---

## 🗂️ 4. Organisation des Packages

```
fr.luc.gamingcore/
 ├── Main.java                          (Point d'entrée du plugin)
 ├── model/                             (Entités et Enums du domaine)
 │    ├── Guild.java
 │    ├── GuildMember.java
 │    ├── GuildRank.java
 │    ├── GuildPermission.java
 │    ├── GuildClaim.java
 │    └── GuildInvite.java
 ├── economy/                           (Gestion économique & Formule mathématique)
 │    ├── EconomyManager.java
 │    └── ChunkPriceCalculator.java
 ├── database/                          (Persistance SQLite/MySQL)
 │    ├── DatabaseManager.java
 │    └── GuildRepository.java
 ├── manager/                           (Logique métier et services)
 │    ├── GuildManager.java
 │    └── InviteManager.java
 ├── listener/                          (Interception des événements et protection)
 │    └── TerritoryProtectionListener.java
 └── util/                              (Utilitaires de texte et formatage)
      └── TextUtil.java
```