gpatruno
440 lines
18 KiB
Markdown
440 lines
18 KiB
Markdown
# 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 (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×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)
|