@@ -0,0 +1,439 @@
# 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–
| Capacités classe | Ability 1– `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– `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×
├── 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 (tableau ou `#Grid.Slots.N`) — le client rejette
> ces commandes et déconnecte. Les grilles utilisent `InventorySectionId` ; l'affichage passe par
> des overlays `ItemSlot` (`ItemId` / `Quantity`).
> 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×
| 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–
| 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–
| **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× × ×
### 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–
| 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×
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 )
gpatruno