UiCore
Présentation
UiCore dessine des menus, des cartes, un HUD, des dialogues, une minicarte et une carte du monde dans l'espace GUI du client vanilla, sans mod client. Il y parvient avec un core shader (text.vsh) fourni par le resource pack : tout ce qui est dessiné est un glyphe de police, et le shader lit l'ascent et la couleur du glyphe pour savoir où le placer sur une grille fixe de 15 par 15. Le résultat est identique pour chaque joueur, quels que soient son échelle d'interface, son champ de vision ou la taille de sa fenêtre, et il peut apparaître n'importe où à l'écran plutôt que seulement là où s'ouvre un inventaire.
UiCore remplace deux anciens outils : AdvancedMenus (menus en coffre) et BetterHud. Un menu n'est plus un inventaire de coffre : c'est une vue, une pile de couches de composants que vous créez dans le panneau web et que le joueur vise avec sa tête. La même grille dessine les modules de HUD, les lignes de dialogue et les choix.
Le dossier source de cette extension porte le nom de l'ancienne extension HUD ; le nom de l'extension est UiCore. Elle fonctionne sur la version BTC de TypeWriter, a besoin de CraftEngine pour héberger le resource pack, et est marquée alpha (0.1.0-alpha).
Fonctionnalités
- Vues — écrans complets avec panneaux, boutons, listes, onglets, sous-écrans, infobulles, jauges et saisie de texte.
- États et animations — les composants changent selon des facts ou des permissions, et une vue peut arriver avec un balayage, une floraison ou un fondu.
- Modules de HUD — éléments permanents ancrés à un coin ou au centre, masqués pendant que le joueur lit un autre écran.
- Dialogues — répliques parlées et choix auxquels on répond avec la molette ou le curseur, avec une entrée de style partagée.
- Dialogue de cinématique — la même réplique parlée sur une timeline de cinématique.
- Minicarte et carte du monde — carte du terrain avec points d'intérêt, waypoints et un mode de relevé.
- Nameplates — nameplates 3D pour les mobs et les joueurs, avec bannières, badges de niveau et indicateurs de statut des PNJ.
- Bannières et contrôle du chat — une annonce d'une ligne en haut de l'écran, et une action pour couper le chat à un endroit.
- Triggers d'objet — ouvrez une vue par un clic droit avec un matériau.
- Intégrations — affiche des données issues des quêtes, du codex, du battle pass, des cosmétiques, des familiers, du social, du wiki et de RPG Core lorsque ces extensions sont présentes.
Installation
- Installez CraftEngine : il héberge le resource pack qui contient le shader, les polices et les images. Installez PacketEvents s'il n'est pas déjà fourni par votre build ; il sert à la suppression du chat ainsi qu'à la molette et aux touches de déplacement.
- Installez les extensions TypeWriter Entity et Quest ainsi que l'extension BTCMobs : ce sont des dépendances déclarées.
- Installez éventuellement les extensions dont UiCore peut lire les données : Ghost, Codex, BattlePass, TinyEssentials, Cosmetics, NumericalStorage, Permissions, Pets, Friend, Party et Guild. L'extension GUI est également facultative : lorsqu'elle est présente, UiCore lit les états de menu qu'elle publie.
- Placez le JAR d'UiCore dans
plugins/Typewriter/extensions/et redémarrez le serveur. - Déployez le fragment de resource pack d'UiCore dans le pack CraftEngine. Le pack est généré par l'outillage propre à l'extension (
generate-gui-pack, puisvalidate-gui-pack) et doit être déployé avant le JAR correspondant, faute de quoi chaque icône d'objet se décale d'une position sans aucune erreur.
Un identifiant de ressource Minecraft n'accepte que [a-z0-9._-/]. Un fournisseur de police contenant tout autre caractère est rejeté silencieusement par le client, et le glyphe apparaît comme un rectangle noir en haut de l'écran. Le générateur de pack refuse d'écrire un tel chemin.
Premiers pas
Ouvrez un petit menu depuis une boussole.
- Dans le panneau web de TypeWriter, ouvrez une page statique et ajoutez une entrée UI View. Définissez
viewIdsurhello_menu. - Ajoutez une couche (
layerIdmain) et un premier composant :placement.kindCELL,column4,row6,width7,height3,paletteSURFACE,hoverPaletteBLUE_LIGHT,textHello,tooltipClick me. - Dans
onLeftClick, liez une action telle qu'une commande ou un message. Ajoutez un second composant avecnavigateToou Close UI View pour quitter. - Ajoutez une action Open UI View avec
viewIdhello_menu, ou associez un objet : ajoutez un UI Item Trigger avecmaterialCOMPASSetviewIdhello_menu. - Publiez. Faites un clic droit avec une boussole : l'écran apparaît, visez le bouton avec la tête et cliquez.
Fonctionnement
Une vue est une liste de couches (de l'arrière vers l'avant) ; une couche contient des composants ; un composant indique où il se place, comment il est peint, ce qu'il affiche et ce que déclenche un clic. Trois limites proviennent de l'encodage, pas du code :
- Une teinte est un index. La couleur d'une cellule porte sa colonne, sa ligne et l'index de palette ; les teintes proviennent donc d'une palette nommée fixe (
SURFACE,BLUE_LIGHT,GOLD...), et non de valeurs hexadécimales libres. - Les images sont peu coûteuses, les polices sont rares. Un composant peut être peint avec une image de panneau ; un nombre quelconque d'images partage une même police. La teinte du texte vient de la police, et le pack fournit 16 teintes de texte : une 17e retombe donc sur le blanc.
- Rien ne glisse et le texte ne s'estompe pas. Une animation révèle des cellules dans un certain ordre. Le texte arrive avec son panneau.
Les vues ouvertes refusent de démarrer pendant que le joueur chute (le joueur reçoit un message). Une chaîne de moteurs de rendu (rendererOrder de UI Configuration) décide quel moteur de rendu sert une vue : GUI (ce shader), DIALOG, SPATIAL ou CHEST.
Menus
Ouverture
Une vue peut être ouverte par :
- l'action Open UI View (
viewId) ; - la commande
/ui open <viewId>d'une entrée UI View Commands ; - un UI Item Trigger, qui ouvre une vue lorsque le joueur fait un clic droit avec un matériau donné (deux vues revendiquant le même matériau sont consignées comme un avertissement et seule la dernière s'ouvre) ;
- le
openMaterialde la minicarte, qui ouvre la carte du monde.
Close UI View ou /ui close la ferme.
Disposition et composants
La grille fait 15 colonnes sur 15 lignes pour les menus. placement.kind vaut CELL (une cellule de la grille : column, row, width, height), MARKER (une position de 0 à 1 sur la zone d'affichage, x et y, bornée) ou SCRIM (un voile plein écran). Un bouton a besoin de plusieurs cellules pour être facile à viser.
| Champ de composant | Effet |
|---|---|
palette, hoverPalette, disabledPalette | Teinte au repos, sous le curseur, et tant que les criteria ne correspondent pas. |
background | Une image de panneau du pack (nine-slice) à la place d'une teinte unie ; backgroundBinding choisit l'image à partir d'un placeholder. |
text, textPalette, textAlign, textEffect | Texte dessiné sur le composant. |
icon, lineIcon | L'image d'un matériau dessinée devant le texte ou fermant la ligne. |
image, imageBinding | Une image du pack ajustée à l'intérieur du composant en conservant son rapport d'aspect. |
label, tooltip | Texte affiché à côté de l'écran, ou à l'ancre de l'infobulle, tant que le curseur repose sur le composant. |
gauge | Dessine une barre à partir d'un placeholder valant de 0 à 100 (par exemple btcui_health_percent). |
binding | Un placeholder dont le composant tire sa valeur. |
criteria, onLeftClick, onRightClick | Conditions pour cliquer et entrées déclenchées. |
navigateTo | Ouvre un autre écran de la même vue. |
input | Demande au joueur de saisir une valeur ; onInputCommands s'exécutent depuis la console avec {input} et %player% remplacés. |
Écrans, listes et états
- Nœuds (
nodes,rootNodeId) déclarent des onglets et des sous-écrans, chacun choisissant quelle couche remplit quelle région nommée. Les titres alimentent le fil d'Ariane. - Répétitions (
repeatssur une couche) dessinent une fenêtre sur des sources numérotées : l'élémentnlit le binding<source>.<n>.stepModePAGEfait tourner une fenêtre entière par geste,ITEMavance d'un élément. - États (
states) modifient des composants tant qu'une condition est vraie : une teinte, un texte, une infobulle, une icône, un panneau ou la visibilité. L'état de plus haute priorité dont les conditions sont remplies est celui qui est actif, un état peut affiner unparentId, et un composant est adressé par son identifiant ou parcolumn:row. Les états sont réévalués à chaque redessin. - Arrivée (
opening,openingMillis,openingFade) :WIPE_DOWN,WIPE_UP,WIPE_RIGHT,WIPE_LEFT,BLOOMouFADE. Elle ne se joue qu'à l'entrée dans l'interface, pas entre deux écrans.
Palette
FRAME, SURFACE, SURFACE_LIGHT, MUTED, BLUE, BLUE_LIGHT, CYAN, TEAL, GREEN, GREEN_LIGHT, YELLOW, ORANGE, RED_DARK, RED, PURPLE, WHITE, BLACK, INK, SLATE, STEEL, STEEL_LIGHT, MIST, PAPER, FOREST, MINT, GOLD, AMBER, WINE, CORAL, VIOLET. NONE ne dessine rien.
Interaction
Le curseur suit la tête du joueur : le lacet (yaw) et le tangage (pitch) sont projetés sur la grille et alignés sur une cellule. Les joueurs changent sa vitesse avec /ui sensitivity <degrees> : un angle plus grand signifie un curseur plus lent.
- Les clics gauche et droit déclenchent
onLeftClicketonRightClick; la molette fait défiler les listes et les onglets ; la touche de furtivité est un raccourci qui ferme la vue (sauf pendant qu'une liste d'arbre de recherche a le focus). - La vue s'efface devant le monde : s'éloigner, une téléportation, subir des dégâts ou ouvrir un inventaire la ferme.
- Tant qu'une vue est ouverte, le chat des autres joueurs est tenu hors de l'écran, et les messages du serveur sont redessinés par le chat de l'UI au lieu du chat vanilla.
Modules de HUD
Les entrées UI HUD utilisent les mêmes couches et composants qu'une vue, ancrés à un corner (TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT, CENTRE) ; les décalages se comptent vers l'intérieur à partir de celui-ci. priority décide lequel de deux groupes qui se chevauchent est dessiné au-dessus et visibility conditionne le groupe. Les modules de HUD sont suspendus automatiquement tant qu'une vue, un dialogue, une cinématique ou la carte du monde occupe l'écran.
Dialogues
UI Spoken Dialogue affiche une réplique avec le nom de l'interlocuteur, un portrait facultatif, une duration de frappe (zéro l'affiche d'un coup) et un sound. UI Option Dialogue ajoute des choix (options) : navigation vaut KEYS (molette et touche de confirmation), CURSOR ou les deux (la valeur par défaut) ; un timer annule le dialogue et déclenche cancelTriggers ; chaque choix possède des criteria (il est dessiné verrouillé, ou masqué avec hideWhenLocked), un lockedReason affiché à la place de son infobulle tant qu'il est verrouillé, des modifiers et des triggers. Les deux prennent une entrée style ; laissez-la vide pour utiliser celle du serveur.
UI Dialogue Style définit l'apparence en cellules de grille : speech (cadre, zone de texte, bandeau de l'interlocuteur, portrait), options (fenêtre, panneau, teintes des choix sélectionnés et verrouillés, curseur et flèches de défilement, seconde colonne facultative) et chrome (image de la touche de confirmation, ligne de compte à rebours, lignes de bandes noires de format cinéma). UI Spoken Cinematic place des répliques sur une page de cinématique avec des segments startFrame et endFrame.
Cartes et nameplates
La minicarte permanente se configure avec Minimap Settings (worlds et excludeListedWorlds, size, blocksPerCell, borderThickness, openMaterial, maxWaypoints, worldMapAreas) et ses points avec Minimap Points of Interest. Sa position à l'écran est définie dans le resource pack, pas ici, car le serveur ne connaît ni la résolution ni l'échelle de l'interface. La carte du monde s'ouvre par un clic droit avec openMaterial ou avec /worldmap ; en jeu normal, elle se remplit à partir de ce que lit la minicarte, et le mode de relevé cartographie volontairement un rayon plus large.
Les nameplates sont en trois dimensions et propres à chaque spectateur. Global Nameplate dessine des lignes au-dessus des mobs (entityTypes, btcMobsOnly, lines, viewDistance, requireLineOfSight...). Player Nameplate Banner définit des arrière-plans de bannière sélectionnables (un préfixe d'image CraftEngine avec des tranches _left, _middle et _right), et le choix du joueur est stocké dans un artifact de sélection. Nameplate Settings définit les distances, les budgets et l'unité de santé ; Level Badge Settings définit le mot écrit avant un niveau (préfixe par défaut, peut être un placeholder de traduction). NPC Status Override place un modèle d'indicateur (disponible, actif, interaction...) au-dessus d'un PNJ.
Commandes
| Commande | Description |
|---|---|
/ui open <viewId> | Ouvre une vue. |
/ui close | Ferme la vue ouverte. |
/ui sensitivity [degrees] | Affiche ou définit l'amplitude de votre curseur en degrés. |
/ui icons [materials] | Affiche des icônes d'objets dans le chat pour vérifier la police de sprites. |
/ui chat vanilla | Réservée aux opérateurs : vous rend le chat vanilla jusqu'à votre déconnexion ou jusqu'à ce que vous l'exécutiez à nouveau. |
/worldmap | Ouvre ou ferme la carte du monde. |
/worldmap survey, forget, stats, minimap, waypoint <name>, waypoint clear, save, debug | Mode de relevé, oublier votre carte, afficher sa taille, activer/désactiver la minicarte, renommer ou effacer des waypoints, sauvegarder, et afficher un diagnostic. |
/nameplates (alias /nameplate, /btcnameplates) | equip <id>, unequip, preview [id], list, toggle [on|off], et les formes d'administration force-equip, force-unequip, force-preview, admin-toggle. |
Les noms de /ui et de /worldmap proviennent des champs commandName de leurs entrées. Leur champ permission est un nœud de permission de votre choix : vide signifie tout le monde. /worldmap survey, forget, save et l'interrupteur de relevé utilisent surveyPermission.
Permissions
| Permission | Autorise |
|---|---|
permission de UI View Commands | Les sous-commandes de /ui (vide : tout le monde). |
permission et surveyPermission de World Map Command | /worldmap, ainsi que le relevé et l'oubli (vide : tout le monde). |
btcnameplates.command.equip, .unequip, .preview, .list, .toggle | Les sous-commandes /nameplates correspondantes pour les joueurs. |
btcnameplates.command.admin.force_equip, .force_unequip, .force_preview, .toggle | Les sous-commandes d'administration de /nameplates. |
visibility.permission sur les composants et les groupes | Affiche ou masque un élément pour les joueurs sans le nœud. |
Placeholders
Expansion MiniPlaceholders btcui, pour les composants, les jauges et le texte.
| Placeholder | Renvoie |
|---|---|
<btcui_level_glyph:37> | N'importe quel nombre écrit avec les chiffres de niveau colorés du pack. |
<btcui_global_level_glyph>, <btcui_global_level>, <btcui_global_level_badge> | Le niveau global sous forme de glyphes, de chiffres, ou avec le préfixe configuré. |
<btcui_global_percent>, <btcui_global_detail>, <btcui_xp_detail> | Progression vers le prochain niveau global et ses valeurs. |
<btcui_health>, <btcui_health_max>, <btcui_health_percent>, <btcui_absorption> | Santé et absorption. |
<btcui_food>, <btcui_food_max>, <btcui_food_percent>, <btcui_saturation> | Faim. |
<btcui_air>, <btcui_air_max>, <btcui_air_percent>, <btcui_air_gauge> | Réserve d'air ; la jauge est vide tant que le joueur ne manque pas d'air. |
<btcui_xp_level>, <btcui_xp_progress>, <btcui_xp_percent> | La barre d'expérience vanilla (utilisée pour l'enchantement). |
<btcui_riding>, <btcui_mount_name>, <btcui_mount_health>, <btcui_mount_health_max>, <btcui_mount_health_percent>, <btcui_mount_gauge> | La monture. |
<btcui_underwater>, <btcui_swimming>, <btcui_burning>, <btcui_freezing> | États du joueur. |
<btcui_x>, <btcui_y>, <btcui_z>, <btcui_world_time>, <btcui_world_day> | Position et heure. |
<btcui_banner>, <btcui_actionbar>, <btcui_chat:...> | Bannière actuelle, action bar et lignes de chat dessinées par l'UI. |
Entrées
26 entrées, générées depuis la source de l'extension.
Actions5
- Close UI ViewClose UI View
- Mute UI ChatMute UI Chat
- Open UI ViewOpen UI View
- UI BannerUI Banner
- Unmute UI ChatUnmute UI Chat
Audiences2
- NPC Status OverrideNPC Status Override
- UI Look AudienceLooking At A Position
Cinématiques1
- UI Spoken CinematicUI Spoken Cinematic
Données d'entité1
- BTC Nameplate DataConfigure native text lines and an optional 3D attachment
Commandes2
- UI View CommandUI View Commands
- World Map CommandWorld Map Command
Artefacts1
- BTC Player Nameplate Selection ArtifactStores each player's selected nameplate banner
Manifestes12
- BTC Global NameplateGlobal mob nameplate
- BTC Player Nameplate BannerPlayer nameplate banner
- Minimap PoiMinimap Points of Interest
- Minimap SettingsMinimap Settings
- UI ConfigurationUI Configuration
- UI Dialogue StyleUI Dialogue Style
- UI HUDUI HUD
- UI Item TriggerUI Item Trigger
- UI Level Badge SettingsPrefix written before every level badge
- UI Nameplate SettingsShared nameplate visibility and health units
- UI Token ShopToken Shop Catalogue
- UI ViewUI View
Dépannage
Rectangles noirs ou carrés vides (tofu) là où devraient se trouver du texte et des cellules. Le fragment de resource pack est manquant, obsolète ou déployé après le JAR, ou un chemin de police contient un caractère en dehors de [a-z0-9._-/]. Redéployez d'abord le pack, puis le JAR correspondant, et vérifiez que CraftEngine l'a rechargé.
Les icônes d'objets affichent le mauvais objet. Le pack et le JAR ne correspondent pas : le caractère d'une icône est son rang dans la table, donc un pack généré après le JAR décale chaque icône. Régénérez et validez le pack, puis redéployez les deux.
Un objet ouvre un menu vide. Deux associations UI Item Trigger revendiquent le même matériau ; le journal indique est reclame par ... avec le nombre de composants de chacune. Retirez l'association en trop.
names view '<id>', which no page defines. Le viewId donné à l'action, à la commande ou à l'objet ne correspond à aucune UI View publiée. Une vue declared but incomplete n'a aucune couche ni aucun composant pouvant être résolu.
Le menu ne s'ouvre pas en plein air. UiCore refuse d'ouvrir un écran pendant que le joueur chute. Réessayez au sol.
Le chat a disparu. UiCore dessine lui-même le chat : une vue est ouverte, un Mute UI Chat est actif, ou le joueur l'a désactivé. Utilisez Unmute UI Chat en quittant l'endroit où vous l'avez coupé ; les opérateurs peuvent utiliser /ui chat vanilla pour vérifier le chat vanilla.
Les gestes cessent de fonctionner. Gesture decoding unavailable dans le journal signifie que PacketEvents n'a pas pu démarrer : la molette et les touches de déplacement sont perdues mais les clics fonctionnent toujours.
Extensions associées
- TinyEssentials — données de wiki, de home et de tab affichées par les vues.
- RPG Core — les panneaux de progression, de stockage et de garde-robe utilisent UiCore.
- Codex, BattlePass, Cosmetics, Pets — écrans de données.
- Party, Friend, Guild — panneaux sociaux.
- GUI — menus en coffre ; UiCore partage les états de menu qu'elle publie.