# 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
│   ├── MmorpgInventoryPage.ui      # 🟡 Début — inventaire MMORPG (coquille + grille)
│   ├── MmorpgInventoryTab.ui       # Onglet Inventaire (futur, dans coquille à onglets)
│   └── 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 (fallback) | `PlayerInfoPage` | ✅ Actif (`/mmorpg menucustom`) |
| Menu à onglets | `PlayerMenuPage` | ✅ Actif (`/mmorpg menu`) |
| Onglet Personnage | `MmorpgCharacterTab.ui` | ✅ Actif |
| Onglet Inventaire | `MmorpgInventoryTab.ui` + `PlayerInventoryReader` | ✅ Actif |
| Onglet Compétences | `MmorpgSkillsTab.ui` | ✅ Actif (capacités classe + branches 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` | Q (Use Ability 1) | Nom + cooldown (`Charge (3s)`) |
| 2 | `#Slot2Name`, `#Slot2Key` | E (Use Ability 2) | idem |
| 3 | `#Slot3Name`, `#Slot3Key` | R (Use Ability 3) | idem |

Les labels `#Slot*Key` / `#Ability*Key` sont remplis par `AbilitySlotKeys` avec les raccourcis
Hytale par défaut (`[Q]`, `[E]`, `[R]`). Le serveur ne connaît pas les rebinding client.

**Commande debug :** `/mmorpg hud` — force la synchronisation.

---

## 2. Menus joueur

Ouverture : **`/mmorpg menu`** → coquille à onglets (`PlayerMenuPage`).  
Fallback chat : `/mmorpg info` si la page UI échoue.

### 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 inventaire :** `Pages/MmorpgInventoryPage.ui` — document **racine** pour l'onglet Inventaire (`/mmorpg inventory`)  
**Fichier coquille :** `Pages/MmorpgPlayerShell.ui` — Personnage / Compétences uniquement

> Relié à l'inventaire **vanilla** via `ItemGrid.InventorySectionId` (sac, barre rapide, armure, utilitaire).
> **`InventorySectionId` ne fonctionne pas** dans une coquille imbriquée : l'inventaire doit être le document
> racine (`MmorpgInventoryPage.ui`). Changement d'onglet vers/depuis Inventaire → `rebuild()` complet.
> Ne pas appeler `#Grid.Slots` depuis le serveur — le client rejette cette commande et déconnecte.
> Glisser-déposer synchronisé ; panneau détails au clic.

| Zone | ID | Section vanilla |
|------|-----|-----------------|
| Armure | `#ArmorGrid` | `ARMOR_SECTION_ID` (-3) |
| Utilitaire | `#UtilityGrid` | `UTILITY_SECTION_ID` (-5) |
| Sac | `#StorageGrid` | `STORAGE_SECTION_ID` (-2), 9×4 |
| Barre rapide | `#HotbarGrid` | `HOTBAR_SECTION_ID` (-1) |
| Détails | `#ItemDetails` | Clic / survol slot → `PlayerInventoryReader` |

**À venir :** filtres par catégorie, stats MMORPG sur items tagués, boutons Utiliser / Jeter.

**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 — **début** : `MmorpgInventoryPage.ui` |
| **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

### Documentation Custom UI (officielle / guides)

- [Custom UI — vue d'ensemble](https://hytalemodding.dev/en/docs/official-documentation/custom-ui) — HUD vs pages, `append` / `set`, sélecteurs
- [Layout](https://hytalemodding.dev/en/docs/official-documentation/custom-ui/layout) — `Anchor`, `LayoutMode`, `FlexWeight` (utilisé pour le panneau inventaire 3 colonnes)
- [Common Styling](https://hytalemodding.dev/en/docs/official-documentation/custom-ui/common-styling) — `Common.ui`, styles vanilla réutilisables
- [Guide plugin UI](https://hytalemodding.dev/en/docs/guides/plugin/ui) — chemin `Common/UI/Custom`, `IncludesAssetPack`, mode diagnostic client

**Rappels appris en production :**

- `CustomUIHud` : uniquement `append(document)` + `set()` — pas de `appendInline` / `clear` (crash client).
- Propriétés dynamiques : préférer `ProgressBar.Value` plutôt que `Group.Width` (rejeté par le client).
- Ancrage HUD : le groupe racine doit avoir `Anchor: (Left: …, Width: …)` sinon centrage écran.

### Fichiers projet

- Code UI : `src/main/java/com/disklexar/mmorpg/ui/`
- HUD vitals + capacités : `src/main/resources/Common/UI/Custom/MmorpgAbilityBar.ui`
- Inventaire (début) : `src/main/resources/Common/UI/Custom/Pages/MmorpgInventoryPage.ui`
- Profil (scaffold) : `src/main/resources/Common/UI/Custom/Pages/MmorpgPlayerInfo.ui`
- Guide asset pack : [assetpack/README.md](../assetpack/README.md)
- Architecture : [ARCHITECTURE.md](ARCHITECTURE.md)