first

docs/README-UI.md

@@ -0,0 +1,408 @@
+# Interface utilisateur MMORPG — conception UI/UX
+
+Document de référence pour l'interface joueur du plugin **com.disklexar:MMORPG** sur Hytale.
+Objectif : une UI type MMORPG **moderne, ergonomique, immersive et intuitive**, compatible avec les
+contraintes d'un plugin **serveur** (assets `.ui` embarqués, `CustomUIHud`, `CustomUIPage`).
+
+---
+
+## Principes directeurs
+
+| Principe | Application |
+|----------|-------------|
+| **Lisibilité en combat** | Contrastes élevés, tailles minimales 12 px, icônes + texte court |
+| **Hiérarchie visuelle** | HUD persistant discret ; menus modaux pour la gestion profonde |
+| **Feedback immédiat** | Cooldowns, buffs et dégâts reflétés en < 1 s côté client |
+| **Cohérence** | Palette sombre `#1a1c20` / accents `#c8a45c` (or MMORPG) sur tous les écrans |
+| **Responsive** | Ancres relatives (`Left`, `Right`, `Bottom`) + grilles flex, pas de pixels fixes centraux |
+| **Dégradation gracieuse** | Commandes chat (`/mmorpg info`, `/mmorpg profile`) si un asset `.ui` est invalide |
+
+### Palette
+
+```
+Fond HUD      #1a1c20 @ 85 %    Barre pleine vie   #3d8f5a
+Fond slot     #24262a            Barre vide         #2a2d32
+Texte primaire #e8e8ec           Mana / énergie     #4a8fd4
+Texte secondaire #878e9c          XP / niveau        #c8a45c
+Buff positif  #5cb85c            Debuff négatif     #c9302c
+Bordure focus #c8a45c            Overlay modal      #1b1b1f @ 93 %
+```
+
+---
+
+## Architecture globale
+
+```mermaid
+flowchart TB
+  subgraph hud [HUD persistant — en jeu]
+    Vitals[Barres vie / mana / XP]
+    Buffs[Buffs & debuffs]
+    Hotbar[Barre d'action]
+    AbilityBar[Barre capacités classe]
+  end
+
+  subgraph menus [Menus joueur — modaux]
+    Shell[Coquille MmorpgPlayerShell.ui]
+    Char[Onglet Personnage]
+    Inv[Onglet Inventaire]
+    Skills[Onglet Arbre de compétences]
+  end
+
+  subgraph server [Serveur Java]
+    ABS[AbilityBarService]
+    PIP[PlayerInfoPage]
+    Future[HudVitalsService — M1]
+    FutureMenu[PlayerMenuPage — M1]
+  end
+
+  ABS --> AbilityBar
+  Future --> Vitals
+  Future --> Buffs
+  Future --> Hotbar
+  FutureMenu --> Shell
+  Shell --> Char
+  Shell --> Inv
+  Shell --> Skills
+  PIP -.->|fallback actuel| Char
+```
+
+### Arborescence des assets (cible)
+
+```
+src/main/resources/Common/UI/Custom/
+├── Huds/
+│   ├── MmorpgVitalsHud.ui          # Vie, mana, XP (bas-gauche)
+│   ├── MmorpgBuffTrayHud.ui        # Buffs / debuffs (sous les barres)
+│   ├── MmorpgHotbarHud.ui          # Slots objets + raccourcis
+│   └── MmorpgAbilityBar.ui         # ✅ Implémenté — 3 slots classe
+├── Pages/
+│   ├── MmorpgPlayerShell.ui        # Fenêtre à onglets (coquille)
+│   ├── MmorpgCharacterTab.ui       # Onglet Personnage
+│   ├── MmorpgInventoryTab.ui       # Onglet Inventaire
+│   └── MmorpgSkillTreeTab.ui       # Onglet Arbre de compétences
+└── Widgets/
+    ├── MmorpgProgressBar.ui        # Barre réutilisable (vie, mana, XP)
+    ├── MmorpgBuffIcon.ui           # Icône buff avec timer
+    └── MmorpgSkillNode.ui          # Nœud d'arbre de compétences
+```
+
+### Mapping code serveur
+
+| Composant UI | Classe Java | Statut |
+|--------------|-------------|--------|
+| Barre capacités | `AbilityBarHud` + `AbilityBarService` | ✅ Actif |
+| Profil joueur (liste) | `PlayerInfoPage` | ✅ Actif (layout base-game) |
+| Coquille à onglets | `PlayerMenuPage` | 🔲 M1 |
+| Barres vitales HUD | `VitalsHud` + `VitalsHudService` | 🔲 M1 |
+| Buff tray | `BuffTrayHud` | 🔲 M1 |
+| Hotbar étendue | `HotbarHud` | 🔲 M2 |
+
+---
+
+## 1. Affichage principal (HUD)
+
+Le HUD reste **toujours visible** en exploration et en combat. Les éléments natifs Hytale
+(inventaire rapide, minimap) sont conservés ; le plugin ajoute des calques `CustomUIHud`
+(`z-order` croissant : vitals → buffs → hotbar → capacités).
+
+### 1.1 Disposition écran (desktop 16:9)
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  [Minimap native]                                          [Quêtes]*     │
+│                                                                          │
+│                         MONDE / COMBAT                                   │
+│                                                                          │
+│                                                                          │
+│  ┌─ Vitals ─────────────────┐                                           │
+│  │ ♥  ████████░░  840/1000  │  ← Vie                                     │
+│  │ ◆  ██████░░░░   120/200  │  ← Mana / énergie                          │
+│  │ ★  Nv.42  ████░  67 %    │  ← Niveau + barre XP                       │
+│  └──────────────────────────┘                                           │
+│  [Buff][Buff][Debuff]...      ← Buff tray (max 8 icônes visibles)        │
+│                                                                          │
+│         [1][2][3][4][5][6][7][8][9][0]  ← Hotbar objets                │
+│              [Cap1][Cap2][Cap3]          ← Barre capacités classe        │
+└──────────────────────────────────────────────────────────────────────────┘
+* futur module quêtes
+```
+
+### 1.2 Barres de vie, mana et XP
+
+**Fichier cible :** `Huds/MmorpgVitalsHud.ui`
+
+| Élément | ID serveur | Donnée source | Comportement |
+|---------|------------|---------------|--------------|
+| Barre de vie | `#HealthBar`, `#HealthText` | Composants entité joueur (vanilla) + bonus MMORPG futurs | Remplissage proportionnel ; flash rouge si < 25 % |
+| Barre de mana | `#ManaBar`, `#ManaText` | Attribut MMORPG (M1) | Masquée si classe sans mana (ex. Chevalier) |
+| Niveau | `#LevelLabel` | `PlayerProfile.level` | `Nv. {n}` |
+| Barre XP | `#XpBar`, `#XpText` | `ProgressionService` | `{current}/{required}` + pourcentage |
+
+**Rafraîchissement :** toutes les 500 ms via `VitalsHudService` ; push immédiat sur gain d'XP ou dégâts.
+
+**Widget réutilisable `MmorpgProgressBar.ui` :**
+
+```
+Group #ProgressBar
+  Group #Fill          — largeur dynamique (ui.set Width ou FlexWeight)
+  Label  #ValueText    — "840 / 1000"
+```
+
+### 1.3 Buffs et debuffs actifs
+
+**Fichier cible :** `Huds/MmorpgBuffTrayHud.ui`
+
+| Propriété | Valeur |
+|-----------|--------|
+| Position | Au-dessus des barres vitales, aligné à gauche |
+| Capacité | 8 icônes visibles ; défilement horizontal si > 8 |
+| Par icône | Image, nom court, timer circulaire ou compte à rebours |
+| Sources serveur | `CombatBuffService`, `StunService`, effets de classe |
+
+**IDs dynamiques :** `#BuffSlot0` … `#BuffSlot7` — le serveur injecte des instances de
+`Widgets/MmorpgBuffIcon.ui` via `appendInline`.
+
+**Code couleur :** bordure verte = buff allié ; rouge = debuff ; or = effet neutre / passif.
+
+### 1.4 Barre d'action (hotbar)
+
+**Fichier cible :** `Huds/MmorpgHotbarHud.ui`
+
+La hotbar MMORPG **complète** la barre native sans la remplacer :
+
+| Zone | Slots | Contenu |
+|------|-------|---------|
+| Objets consommables | 1–0 (10) | Potions, nourriture, gadgets MMORPG |
+| Capacités classe | Ability 1–3 | Géré par `MmorpgAbilityBar.ui` (déjà séparé) |
+| Slot utilitaire | `U` (optionnel) | Monture, outil de métier |
+
+**Par slot :**
+
+- Icône de l'objet / compétence
+- Raccourci clavier (coin supérieur droit)
+- Overlay cooldown (assombrissement + texte secondes)
+- Bordure dorée si sélectionné
+
+**Interaction :** les slots 1–3 déclenchent `mmorpg_cast_ability` ; les autres passent par
+l'inventaire natif ou des interactions custom futures.
+
+### 1.5 Barre de capacités de classe (implémentée)
+
+**Fichier :** `Common/UI/Custom/MmorpgAbilityBar.ui`  
+**Service :** `AbilityBarService` — affichage automatique à la connexion si le joueur a une classe.
+
+| Slot | ID | Touche | Mise à jour |
+|------|-----|--------|-------------|
+| 1 | `#Slot1Name`, `#Slot1Key` | Ability 1 | Nom + cooldown (`Charge (3s)`) |
+| 2 | `#Slot2Name`, `#Slot2Key` | Ability 2 | idem |
+| 3 | `#Slot3Name`, `#Slot3Key` | Ability 3 | idem |
+
+**Commande debug :** `/mmorpg hud` — force la synchronisation.
+
+---
+
+## 2. Menus joueur
+
+Ouverture cible : **`C`** ou `/mmorpg menu` → coquille à onglets.  
+État actuel : `/mmorpg menu` ouvre `PlayerInfoPage` (liste verticale, layout `WarpListPage.ui`).
+
+### 2.1 Coquille — `MmorpgPlayerShell.ui`
+
+```
+Panel (centré, max 900×600, fond #1b1b1fEE)
+├── Header
+│   ├── Portrait / icône classe     #ClassPortrait
+│   ├── Nom joueur                  #PlayerName
+│   └── Monnaie                     #MoneyLabel
+├── TabBar (horizontal)
+│   ├── Button #TabCharacter        "Personnage"
+│   ├── Button #TabInventory        "Inventaire"
+│   └── Button #TabSkills           "Compétences"
+├── ContentHost #TabContent         (swap le document de l'onglet actif)
+└── Footer
+    └── Button #CloseButton           "Fermer"
+```
+
+**Navigation :** `UIEventBuilder` lie chaque onglet ; le serveur charge le `.ui` de l'onglet
+dans `#TabContent` via `ui.clear` + `ui.append`.
+
+### 2.2 Onglet Personnage
+
+**Fichier cible :** `Pages/MmorpgCharacterTab.ui`
+
+| Section | Champs | Source `PlayerProfile` |
+|---------|--------|------------------------|
+| Identité | Nom, race, classe | `displayName`, `raceId`, `classId` |
+| Progression | Niveau, XP, barre XP | `level`, `experience` |
+| Attributs* | Force, Agilité, Intelligence… | M1 — stats dérivées |
+| Pouvoirs passifs | Liste à puces | `powers` → `PowerCatalog` |
+| Métiers | Liste à puces | `jobs` → `JobCatalog` |
+| Social | Groupe, guilde | `groupId`, `guildId` |
+| Statistiques | Temps de jeu, argent, dates | `PlayerInfoView` (existant) |
+
+\* Les attributs numériques sont un placeholder visuel jusqu'à l'implémentation M1.
+
+**Layout :** deux colonnes sur grand écran — gauche : portrait + barres ; droite : listes
+pouvoirs / métiers / social.
+
+### 2.3 Onglet Inventaire
+
+**Fichier cible :** `Pages/MmorpgInventoryTab.ui`
+
+> Un plugin serveur **ne peut pas modifier l'inventaire natif**. Cet onglet est une **vue MMORPG**
+> complémentaire (items tagués, équipement RPG, filtres).
+
+| Zone | Description |
+|------|-------------|
+| `#EquipmentPaperDoll` | Silhouette : tête, torse, mains, jambes, arme principale / secondaire |
+| `#InventoryGrid` | Grille 8×5 (40 slots) — items avec rareté (bordure couleur) |
+| `#ItemDetails` | Panneau droit : nom, stats, description, boutons Utiliser / Jeter |
+| `#CategoryTabs` | Filtres : Tout, Équipement, Consommables, Matériaux, Quête |
+| `#WeightBar` | Encumbrance (futur) |
+
+**Ergonomie :**
+
+- Clic gauche : sélection + détails
+- Double-clic : utiliser (si consommable)
+- Shift-clic : déplacer vers équipement (futur)
+- Recherche texte `#SearchField` en haut de grille
+
+### 2.4 Onglet Arbre de compétences
+
+**Fichier cible :** `Pages/MmorpgSkillTreeTab.ui`
+
+| Élément | Description |
+|---------|-------------|
+| `#TreeCanvas` | Zone scrollable / zoomable (pincer sur mobile) |
+| `#SkillNode_*` | Nœuds : icône, rang actuel / max, prérequis |
+| `#PointsAvailable` | Points de compétence non dépensés |
+| `#NodeTooltip` | Survol : nom, effet, coût, prérequis |
+| `#ResetButton` | Réinitialisation (coût en monnaie, futur) |
+
+**États visuels d'un nœud (`Widgets/MmorpgSkillNode.ui`) :**
+
+| État | Apparence |
+|------|-----------|
+| Verrouillé | Grisé, cadenas |
+| Disponible | Bordure or clignotante légère |
+| Appris (rang 1–n) | Rempli, rang affiché |
+| Max | Bordure brillante, étoile |
+
+**Données :** JSON ou table SQLite `skill_nodes` (M1+) ; rendu initial basé sur la classe active
+(`ClassCatalog` → 3 branches par classe en V1).
+
+---
+
+## 3. Responsive et multi-résolution
+
+### Breakpoints (ratio largeur / hauteur viewport client)
+
+| Profil | Condition | Adaptations |
+|--------|-----------|-------------|
+| **Desktop** | largeur ≥ 1280 px | Menus 900 px ; HUD complet ; 2 colonnes Personnage |
+| **Compact** | 1024–1279 px | Menus 720 px ; buff tray 6 icônes ; texte réduit 1 px |
+| **Small** | < 1024 px | Menus plein écran ; vitals empilés ; hotbar 6 slots visibles + scroll |
+| **Ultrawide** | ratio > 2.1 | HUD ancré aux tiers gauche/droite, pas aux bords extrêmes |
+
+### Règles d'ancrage (fichiers `.ui`)
+
+```
+# HUD bas
+Anchor: (Bottom: 24, Left: 24)           — vitals
+Anchor: (Bottom: 28, Left: 0, Right: 0)  — ability bar (centré)
+
+# Menu modal
+Anchor: Center
+Style: (MaxWidth: 900, Width: 90%)
+```
+
+- Préférer `FlexWeight`, `Padding: (Full: n)` et `LayoutMode: Top/Right` aux positions absolues.
+- Les groupes vides utilisent `Anchor: (Width: 6)` comme séparateurs (pattern `MmorpgAbilityBar.ui`).
+- Tester en 1920×1080, 1366×768 et 1280×720.
+
+### Accessibilité
+
+- Contraste texte / fond ≥ 4.5:1 (WCAG AA)
+- Taille police minimale 12 px (HUD) / 14 px (menus)
+- Les cooldowns affichent **chiffres + assombrissement** (pas la couleur seule)
+- Raccourcis clavier listés dans chaque infobulle de slot
+
+---
+
+## 4. Flux utilisateur
+
+```mermaid
+sequenceDiagram
+  participant J as Joueur
+  participant C as Client Hytale
+  participant S as Serveur MMORPG
+
+  J->>C: Connexion
+  C->>S: PlayerReadyEvent
+  S->>S: loadOrCreate(profile)
+  alt a une classe
+    S->>C: addCustomHud(MmorpgAbilityBar)
+  end
+  S->>C: Message bienvenue (niveau, race)
+
+  J->>C: /mmorpg menu ou touche C
+  C->>S: openCustomPage
+  S->>C: PlayerInfoPage (puis PlayerMenuPage)
+
+  J->>C: Ability 1
+  C->>S: SyncInteractionChains (filtré)
+  S->>C: CancelInteractionChain + cast
+  S->>C: update HUD cooldowns
+```
+
+---
+
+## 5. Commandes et raccourcis
+
+| Action | Commande / touche | Écran |
+|--------|-------------------|-------|
+| Ouvrir profil | `/mmorpg menu` | Menu (liste → coquille) |
+| Profil chat | `/mmorpg info` | Fallback texte |
+| Résumé court | `/mmorpg profile` | Chat |
+| Forcer HUD capacités | `/mmorpg hud` | HUD |
+| Capacité 1–3 | Touches Ability 1/2/3 | HUD + exécution |
+| Fermer menu | Échap | — |
+
+**Raccourcis cibles (M1) :** `C` → menu ; `K` → arbre de compétences ; `I` déjà natif inventaire.
+
+---
+
+## 6. Phases d'implémentation
+
+| Phase | Livrables UI | Dépendances gameplay |
+|-------|--------------|----------------------|
+| **M0** ✅ | `MmorpgAbilityBar.ui`, `PlayerInfoPage`, `/mmorpg hud` | Classes, capacités |
+| **M1** | `MmorpgVitalsHud`, `MmorpgBuffTray`, `MmorpgPlayerShell` + onglet Personnage | Stats vie/mana, buffs |
+| **M2** | Onglet Inventaire MMORPG, `MmorpgHotbarHud` | Items tagués, équipement |
+| **M3** | Onglet Arbre de compétences | Points de compétence, déblocages |
+| **M4** | Quêtes dans HUD, tooltips riches | Module quêtes |
+
+---
+
+## 7. Validation et tests
+
+1. **Asset pack** : `IncludesAssetPack: true` dans `manifest.json` — chaque `.ui` doit être
+   validé en jeu (un fichier invalide **crash le client** à la connexion).
+2. **Checklist par écran :**
+   - [ ] Connexion sans crash client
+   - [ ] HUD visible après choix de classe
+   - [ ] Cooldowns décrémentent chaque seconde
+   - [ ] Déconnexion retire le HUD (`AbilityBarService.dismiss`)
+   - [ ] Menu s'ouvre et se ferme (Échap)
+   - [ ] Responsive : pas de chevauchement à 1366×768
+3. **Logs serveur :** rechercher `Ability bar HUD` dans `devserver/logs/`.
+
+---
+
+## 8. Références projet
+
+- Code HUD actif : `src/main/java/com/disklexar/mmorpg/ui/`
+- Asset barre capacités : `src/main/resources/Common/UI/Custom/MmorpgAbilityBar.ui`
+- Scaffold pages : `assetpack/ui/Pages/MmorpgPlayerInfo.ui`
+- Guide asset pack : [assetpack/README.md](../assetpack/README.md)
+- Architecture : [ARCHITECTURE.md](ARCHITECTURE.md)