GUI

Menus d'inventaire conçus dans le panneau web : dispositions, objets, actions au clic, stockage et classements.

Gratuitesv0.20Menus et visuels

NécessiteTypeWriter0.9PacketEventsCraftEnginefacultatif

TéléchargerCode sourceSupport

Vue d'ensemble

GUI transforme une simple entrée TypeWriter, Open GUI, en un menu d'inventaire complet. Vous choisissez le type de conteneur (un coffre, une enclume, une fenêtre de marchand, un livre écrit...), rédigez un titre en MiniMessage, puis décrivez le contenu sous forme d'arbre de dispositions (layouts) stocké dans le layoutPool de l'entrée. Chaque disposition place des objets : un matériau, un nom, du lore, et ce qui se passe quand un joueur clique dessus.

Tout s'édite dans le panel web : il n'y a aucun fichier de menu à écrire à la main. Un menu s'ouvre comme n'importe quelle autre action, depuis une étape de quête, un dialogue de PNJ, un événement de commande ou un autre menu. Les clics exécutent des commandes console, déclenchent d'autres entrées et modifient des facts : un menu n'est donc qu'une manière de plus de piloter vos pages TypeWriter.

GUI est aussi le socle des autres extensions de menus BTC. Shops et Quest Codex n'embarquent pas leur propre fenêtre : elles placent des objets marqueurs dans une disposition open_gui et l'extension les remplit avec des produits ou des quêtes.

Fonctionnalités

• Dix dispositions — simple, flex, paginated, scrollable, frame, composite, book, merchant, storage et leaderboard.
• 24 types de conteneurs — coffres de 9 à 54 emplacements, ainsi qu'enclume, table d'enchantement, table de forgeron, tailleur de pierre, meule, métier à tisser, table de cartographie, marchand, livre, entonnoir, fourneaux et plus encore.
• MiniMessage partout — couleurs, dégradés et placeholders PlaceholderAPI dans les titres, les noms d'objets et le lore.
• Actions de clic par type de clic — clic gauche, droit, avec Maj, du milieu, double clic, touches numériques, lâcher et échange avec la seconde main, chacun avec ses propres commandes et triggers.
• Permissions d'emplacement — masquez un emplacement avec viewPermission ou laissez-le visible mais inerte avec clickPermission.
• Répétition d'emplacements — remplissez une ligne ou un bloc avec count, direction, gap et repeatY au lieu de copier des objets.
• Vues et onglets — une seule structure de menu, plusieurs écrans, avec un titre en fil d'Ariane et des onglets qui s'allument.
• Stockage persistant — des emplacements qui conservent leurs objets par joueur ou par groupe, avec quotas, placeholders et lâcher facultatif à la fermeture.
• Classements — classez des joueurs, des mondes ou des groupes sur un ou plusieurs facts, y compris les joueurs hors ligne, ou affichez les lignes fournies par une autre extension via le champ source (les statistiques de Dungeon, par exemple).
• Inventaire étendu — transformez l'inventaire du joueur en quatre lignes de menu supplémentaires pour un canevas de dix lignes.

Installation

1. Installez TypeWriter sur un serveur Paper ou Folia. PacketEvents, que TypeWriter exige déjà, doit être présent.
2. Téléchargez le JAR depuis les versions GitHub de GUI (le bouton du panneau de résumé ci-dessus).
3. Placez-le dans plugins/Typewriter/extensions/ et redémarrez le serveur.
4. Facultatif : installez CraftEngine si vos titres utilisent les balises <image> ou <shift> pour dessiner des arrière-plans personnalisés.

Installez GUI avant les extensions qui en dépendent, comme Shops et Quest Codex.

Éditeur web

La version publique de GUI n'inclut pas d'éditeur de menus autonome ni son serveur web : les menus s'éditent dans le panel web TypeWriter. La version ne fournit qu'une vérification au démarrage qui lit vos entrées open_gui publiées et signale les menus défectueux dans la console (voir Dépannage).

Premiers pas

Construisez un petit menu à trois boutons :

1. Dans le panel web, ouvrez une page sequence et ajoutez une entrée Open GUI. Nommez-la main_menu.
2. Définissez guiType sur CUSTOM, size sur SIZE_27 et title sur <gold>Main menu.
3. Dans layoutPool, ajoutez une disposition de type simple, donnez-lui l'id main, puis saisissez main dans mainLayoutId.
4. Dans les items de la disposition, ajoutez un objet en x 4, y 1. Choisissez un DIAMOND dans item, définissez displayName sur <aqua>Rewards et ajoutez une ligne de lore <gray>Click to claim.
5. Dans interactionList, ajoutez une interaction avec type LEFT_CLICK. Ajoutez une commande console comme give %player% diamond 1 dans commands, ou reliez une entrée dans triggers. Activez closeMenu pour fermer le menu après le clic.
6. Ajoutez un second objet simple avec count 9, direction right et un panneau de verre teinté gris pour dessiner une ligne de bordure. Définissez son displayName sur un simple espace.
7. Reliez l'entrée Open GUI à quelque chose qui la déclenche, par exemple le trigger d'une option de dialogue ou un événement de commande, puis Publish (Publier).

Commencez simple

Faites fonctionner en jeu une seule disposition simple avant d'ajouter des couches frame, scrollable ou paginated. Chaque disposition est adressée par son id : un mainLayoutId mal saisi est donc la première chose à vérifier lorsqu'un menu s'ouvre vide.

Fonctionnement

Lorsque l'action se déclenche, l'extension construit l'arbre de dispositions pour ce joueur (les critères et les permissions sont évalués à ce moment), enregistre une session de menu et affiche l'inventaire. Chaque clic est résolu par rapport à l'emplacement situé à cette position, puis exécute l'interaction correspondante. La session mémorise les menus précédents : gui:back ramène donc au menu d'où le joueur vient.

Menus

Types de conteneurs

guiType sélectionne la fenêtre. CUSTOM est un inventaire simple de type coffre dont vous choisissez la hauteur avec size. size ne s'applique qu'à CUSTOM et vaut six lignes par défaut ; les autres types utilisent la taille vanilla de leur fenêtre.

guiType	Fenêtre
CUSTOM, CHEST, ENDER_CHEST, BARREL, SHULKER_BOX	Grilles de type coffre. Pour CUSTOM, size vaut SIZE_9, SIZE_18, SIZE_27, SIZE_36, SIZE_45 ou SIZE_54.
HOPPER, DISPENSER, DROPPER	Petits conteneurs de taille fixe.
FURNACE, BLAST_FURNACE, SMOKER, BREWING_STAND, BEACON	Fenêtres de machines.
CRAFTING_TABLE, ENCHANTING_TABLE, ANVIL, SMITHING_TABLE, GRINDSTONE, LOOM, CARTOGRAPHY_TABLE, STONECUTTER	Établis vanilla. Sans disposition, ils se comportent comme l'écran vanilla ; GUI ne gère que l'ouverture et la fermeture.
MERCHANT, VILLAGER_TRADE	La fenêtre d'échange des villageois, remplie par une disposition merchant.
BOOK	Un livre écrit, rempli par une disposition book.

Dispositions

Chaque disposition est une entrée nommée de layoutPool. Celle nommée dans mainLayoutId est la racine ; les autres sont atteintes par des références (enfants de composite, innerId de scrollable, layoutId de frame).

Disposition	À utiliser pour	Champs clés
simple	Boutons fixes et décoration aux positions x/y.	items
flex	Objets disposés automatiquement en lignes.	justifyContent (START, CENTER, END, SPACE_BETWEEN), alignItems, wrap, virtualHeight
paginated	Une longue liste découpée en pages.	itemsPerPage, slots, items, navigationButtons (NEXT, PREVIOUS, BACK, INDICATOR)
scrollable	Un contenu plus haut ou plus large que la fenêtre.	innerId, virtualWidth, virtualHeight, buttons (direction, step), showDefaultButtons, defaultStep
frame	Plusieurs rectangles indépendants, par exemple des onglets, du contenu et un pied de page.	frames (id, x, y, width, height, layoutId)
composite	Empiler des calques : arrière-plan, contenu, boutons.	children (identifiants de dispositions, les derniers enfants se dessinent par-dessus)
book	Les pages d'un livre écrit.	pages (MiniMessage)
merchant	Échanges de villageois avec des objets personnalisés.	trades (result, costOne, costTwo, maxUses, criteria)
storage	Emplacements persistants adossés à un artefact GUI Storage.	entry, groupKey, slots
leaderboard	Lignes de classement avec pages, à partir de facts ou de la source d'une autre extension.	leaderboard, x, y, width, height, previousButton, nextButton

Une disposition book ou merchant ne fonctionne que comme disposition principale, et guiType est remplacé par la fenêtre correspondante. Une disposition scrollable reçoit des flèches par défaut tant que showDefaultButtons est activé (valeur par défaut) : une pour chaque direction sans entrée dans buttons, voir Dispositions, cadres et emplacements.

Voir Dispositions, cadres et emplacements pour un parcours détaillé de chaque disposition.

Objets et emplacements

Chaque objet d'une disposition est une description d'emplacement avec les mêmes champs :

Champ	Rôle
item	L'objet à afficher. Laissé vide, l'emplacement affiche l'objet que le joueur tient dans sa main principale.
displayName, lore	Texte MiniMessage avec prise en charge de PlaceholderAPI. Les noms sont droits par défaut ; ajoutez <italic> si vous voulez de l'italique. Un displayName vide conserve le nom de l'objet au lieu de le remplacer par un nom vide.
x, y	Colonne de 0 à 8 et ligne à partir de 0 en haut.
rollPerSlot	Pour un objet répété sur plusieurs emplacements dont l'item est aléatoire : désactivé (défaut), le tirage est fait une fois et chaque emplacement montre ce résultat ; activé, chaque emplacement tire seul à l'ouverture du menu. Le résultat est conservé tant que le menu reste ouvert, sauf si liveItem est activé.
liveItem	Désactivé (défaut) : l'objet est tiré à l'ouverture du menu et conservé toute la session ; à l'actualisation, seuls son nom et sa description suivent. Activé : l'objet est réévalué à chaque actualisation, donc un objet aléatoire est retiré à chaque fois. Avec rollPerSlot activé, chaque emplacement répété tire seul à chaque actualisation ; sinon, tous les emplacements répétés partagent un tirage par actualisation. Un nom vide reste ignoré.
count, direction, gap, repeatY	Répétition d'emplacements, voir ci-dessous.
criteria	L'emplacement n'est pas dessiné pour les joueurs qui ne correspondent pas.
viewPermission	Permission requise pour voir l'emplacement.
clickPermission	Permission requise pour utiliser l'emplacement ; sans elle, l'emplacement est dessiné mais inerte.
allowPickup, isGhost	Indiquent si l'objet peut être sorti du menu. Tous deux désactivés par défaut ; les objets fantômes peuvent être cliqués mais jamais déplacés ni copiés.
cooldownTicks	Ticks avant que le même emplacement puisse être cliqué à nouveau.
interactionList, triggers, modifiers	Ce que fait un clic.
input	Ouvre une boîte de saisie de texte au clic.
storageId	Transforme l'emplacement en emplacement de stockage persistant issu de storagePool.
buttonType, buttonPrefix	Marque l'emplacement comme un bouton fourni par une autre extension.
animation	Déplace l'emplacement vers une position cible sur une durée en millisecondes à l'ouverture du menu.

Répétition d'emplacements. count répète un objet le long de direction (right, left, down, up). gap est un pas, et non un espacement : 1 correspond à des emplacements adjacents, 2 laisse un emplacement vide entre les copies, et 0 se comporte comme 1. repeatY répète toute la ligne sur l'axe perpendiculaire. Sans direction, count, gap et repeatY sont ignorés et un seul emplacement est placé. Ces champs comptent des emplacements, jamais la taille de pile de l'objet.

Chevauchements. Lorsque deux emplacements partagent une case, celui qui fait quelque chose (une action de clic, une balise, un emplacement de stockage) l'emporte sur un emplacement purement décoratif, quel que soit l'ordre. Entre deux emplacements de même nature, le dernier déclaré l'emporte. Un avertissement nommant la case est journalisé une fois.

Actions de clic

interactionList associe un type de clic à des commandes et des triggers. Les types disponibles sont LEFT_CLICK, RIGHT_CLICK, SHIFT_LEFT_CLICK, SHIFT_RIGHT_CLICK, MIDDLE_CLICK, DOUBLE_CLICK, NUMBER_KEY_1 à NUMBER_KEY_9, DROP, DROP_ALL et SWAP_OFFHAND.

• commands s'exécutent depuis la console. %player% est remplacé par le nom du joueur, et les placeholders PlaceholderAPI sont résolus d'abord.
• triggers déclenchent des entrées TypeWriter pour le joueur. Les triggers et modifiers propres à l'emplacement se déclenchent à chaque clic gauche ou droit, ou chaque fois qu'une interaction spécifique correspond.
• closeMenu ferme la fenêtre après l'action. executeReturn revient au menu précédent.

Les commandes commençant par gui: sont gérées par GUI lui-même :

Commande	Effet
gui:close	Ferme le menu.
gui:back	Rouvre le menu précédent de la session.
gui:open <entry_id> ou gui:action <entry_id>	Déclenche une autre entrée, généralement un autre Open GUI.
gui:view <view_id>	Bascule vers une autre vue sans fermer l'inventaire.
gui:page <delta> [layout_id]	Déplace une disposition paginée ou de classement de ce nombre de pages.
gui:scroll <dx> <dy> [layout_id]	Fait défiler une disposition scrollable.
gui:refresh	Redessine le menu immédiatement.
gui:sound <sound_key>	Joue un son au joueur.

Ouvrir, revenir et fermer

Un Open GUI ouvert depuis un autre menu est empilé dans l'historique de la session : gui:back ou executeReturn y revient donc. Fermer avec Échap met fin à la session. Ouvrir une disposition de livre met d'abord fin à la session en cours.

Définissez audio pour jouer des sons à l'ouverture, à la fermeture, au défilement et au clic. Définissez autoRefreshTicks pour redessiner le menu tous les N ticks tant qu'il est ouvert, ce qui permet aux placeholders des noms et du lore de se rafraîchir comme un compteur ou un minuteur.

Vues, onglets et héritage

Les views transforment un seul open_gui en plusieurs écrans qui partagent la même structure. Un frame dont le layoutId vaut @view est rempli avec la disposition de la vue active : d'abord la correspondance frames explicite de la vue, puis la disposition nommée <view id>_<frame id>, puis les mêmes recherches sur le parentId de la vue. Marquez un objet onglet avec buttonPrefix view: et buttonType défini sur l'identifiant de la vue : il change de vue au clic et s'allume tant qu'il est actif. Le titre de la vue accepte {breadcrumb}, {view} et {root}.

baseMenuId pointe vers un autre Open GUI et fusionne son layoutPool, ses views et son storagePool sous les vôtres : une disposition ayant le même id remplace celle héritée. Détails dans Vues, onglets et héritage.

Emplacements de stockage

Un artefact GUI Storage contient les objets, par joueur ou par groupe. Déclarez des configurations réutilisables dans le storagePool de l'entrée, puis donnez un storageId à un objet, ou utilisez une disposition storage. Les noms et le lore d'un emplacement de stockage acceptent {stored_name}, {stored_amount} et {stored_max}. {score_raw} et {value_<key>} existent aussi pour les lignes d'un classement avec source.

Associations de clics par défaut, que vous pouvez modifier dans GUI Global Settings :

Action	Clic par défaut
Placer un objet depuis le curseur	Clic gauche
Placer toute la pile du curseur	Maj + clic gauche
Prendre un objet	Clic droit
Tout prendre	Clic gauche
Prendre une pile	Maj + clic droit
Remplir depuis l'inventaire	Échange avec la seconde main (F)
Tout lâcher au sol	Lâcher (Q)

dropOnClose lâche aux pieds du joueur ce qui est encore stocké lorsque le menu se ferme réellement, avec Échap ou à la déconnexion, mais pas lorsque le joueur passe à un autre menu.

Inventaire étendu

extendToPlayerInventory affiche les 36 emplacements du joueur sous forme de quatre lignes supplémentaires, pour un canevas de dix lignes (y de 0 à 9). Cela n'agit que côté client : l'inventaire réel n'est jamais modifié et est restauré à la fermeture du menu, et les objets ne peuvent pas être ramassés depuis les lignes du bas. Cela nécessite guiType CUSTOM avec size SIZE_54. Une disposition racine dont l'id se termine par _extended l'active d'elle-même.

Configuration

GUI n'a pas de fichier de configuration. Deux entrées manifest facultatives permettent de l'ajuster :

• GUI Extension Configuration active la journalisation debug et l'option hideVanillaItemStats, activée par défaut, qui masque les lignes de dégâts d'attaque, de durabilité et d'enchantements sur les boutons de menu.
• GUI Global Settings définit les associations de clics du stockage et les objets de connecteur de l'arbre de compétences.

Placeholders

Placeholder	Renvoie
%typewriter_gui_storage_amount_<entry_id>_<slot_index>%	Nombre d'objets stockés pour le joueur dans une entrée GUI Storage, 0 si vide.
%typewriter_gui_storage_has_<entry_id>_<slot_index>%	true lorsque l'emplacement contient un objet, sinon false.

<slot_index> vaut y * 9 + x de l'emplacement de stockage. Ces placeholders lisent toujours le stockage propre au joueur, jamais un stockage de groupe partagé.

Dans les menus, les jetons suivants sont remplacés par l'extension : {stored_name}, {stored_amount}, {stored_max} (emplacements de stockage), {page}, {next_page}, {prev_page}, {total_pages} et {page_indicator} (le bouton INDICATOR d'une disposition paginée), et {rank}, {name}, {score}, {group}, {world} et {score_<fact_id>} (lignes de classement).

Entrées

6 entrées, générées depuis la source de l'extension.

Actions1

• Open GUIOpen a GUI for the player

Artefacts2

• GUI Leaderboard PopulationOffline population data for GUI leaderboards
• GUI StoragePersistent storage artifact for GUI storage slots

Manifestes3

• GUI ConfigGUI Extension Configuration
• GUI LeaderboardGUI leaderboard backed by Typewriter facts
• GUI SettingsGUI Global Settings

Dépannage

Le menu s'ouvre vide. mainLayoutId est vide, ou ne correspond à aucun id de disposition dans layoutPool (les identifiants sont sensibles à la casse). Avec baseMenuId, un mainLayoutId vide se rabat sur celui du parent. La vérification au démarrage signale dans la console une disposition principale non résolue.

Un emplacement manque et la console indique « falls outside the grid ». L'objet est tombé à un x ou y négatif, ou au-delà de la colonne 8. Cela vient généralement d'un count trop grand, qui compte des emplacements. Le journal nomme la disposition et les coordonnées rejetées.

La console indique « Slot overlap ... gap ». Deux emplacements partagent une case. gap est un pas : 1 place des emplacements adjacents et 2 laisse un emplacement vide entre chacun ; les auteurs qui lisent gap: 1 comme « un écart » obtiennent donc des copies qui se superposent aux voisines. Changez gap ou déplacez un emplacement.

Un emplacement est visible des admins mais pas des joueurs. viewPermission nomme une permission que personne d'autre que les opérateurs ne possède. Les valeurs vides sont ignorées, mais une faute de frappe crée un vrai nœud réservé aux opérateurs. La même règle s'applique au viewPermission d'une vue.

Un bouton s'affiche mais ne fait rien. Vérifiez clickPermission, puis cooldownTicks, puis criteria. Si l'emplacement a un buttonType, son buttonPrefix doit correspondre à l'extension qui le fournit ; une balise non réclamée conserve votre propre interactionList mais rien d'autre. Les commandes s'exécutent depuis la console : une commande qui nécessite un joueur comme émetteur échoue silencieusement.

Le contenu défilant ne bouge pas. Vérifiez que le contenu est plus grand que la fenêtre (virtualWidth et virtualHeight) : une flèche ne s'affiche que s'il y a quelque chose à faire défiler dans sa direction. Avec showDefaultButtons désactivé et sans buttons, il n'y a aucune flèche. Une flèche par défaut s'efface aussi quand sa case contient déjà un objet de contenu, un bouton ou une décoration : rien n'est journalisé, déplacez-la donc avec scrollArrows dans GUI Settings ou ajoutez vos propres buttons avec une direction et un step, en dehors de la zone qui défile.

Le classement ne liste que les joueurs en ligne. Reliez un artefact GUI Leaderboard Population dans le champ population du classement pour conserver les dernières valeurs connues des joueurs hors ligne.

Le menu étendu n'affiche pas dix lignes. extendToPlayerInventory nécessite guiType CUSTOM et size SIZE_54.

Extensions associées

• Shops — menus de boutique construits sur des dispositions GUI et le marqueur shop_button:.
• Quest Codex — le menu du journal de quêtes, construit sur le même châssis open_gui.