Foufure/HytaleMMORPG

Fork 0

Files

T

gpatruno 48a1b900c7

Build / build (push) Has been cancelled

Details

webapp

2026-06-06 21:59:51 +02:00

18 KiB

Raw Permalink Blame History

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

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

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

Asset pack : IncludesAssetPack: true dans manifest.json — chaque .ui doit être validé en jeu (un fichier invalide crash le client à la connexion).
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
Logs serveur : rechercher Ability bar HUD dans devserver/logs/.

8. Références

Documentation Custom UI (officielle / guides)

Custom UI — vue d'ensemble — HUD vs pages, append / set, sélecteurs
Layout — Anchor, LayoutMode, FlexWeight (utilisé pour le panneau inventaire 3 colonnes)
Common Styling — Common.ui, styles vanilla réutilisables
Guide 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
Architecture : ARCHITECTURE.md

18 KiB Raw Permalink Blame History Unescape Escape