GUI

La extensión GUI es el sistema de menús central de Typewriter. Proporciona 9 motores de diseño configurables (más componentes solo por API), 23 tipos de inventario, interacciones de teclado/ratón, almacenamiento de objetos persistente y formato MiniMessage completo. Casi todas las demás extensiones dependen de ella para sus menús.

Próximamente: un editor web WYSIWYG con arrastrar y soltar, vista previa en vivo fiel al juego, diseño automático con flexbox CSS, estados de menú, tilemaps y soporte de resource packs de múltiples proveedores.

• Código fuente — Ver las fuentes en GitHub.
  • Descargar releases — Obtener los últimos JAR.

Características

• 9 motores de diseño — Simple, Composite, Scrollable, Paginated, Frame, Flex, Storage, Book, Merchant — más Iterator, Slider y ReactiveSlot mediante la API de Kotlin.
  • 23 tipos de inventario — Cofre, horno, yunque, mesa de encantamientos, mesa de herrería, mercader, libro y más.
  • Desplazamiento y navegación — Diseños desplazables con botones arriba/abajo/izquierda/derecha configurables. Los botones de desplazamiento están anclados al viewport. Multiframe con zonas independientes.
  • Almacenamiento persistente — Almacenamiento de objetos respaldado por artefactos — por jugador o por grupo. Modo acumulación para el seguimiento del progreso. Acciones de clic configurables.
  • Placeholders de almacenamiento — Placeholders dinámicos {stored_name}, {stored_amount}, {stored_max} en los nombres y lore de las ranuras.
  • MiniMessage — Soporte completo de MiniMessage para títulos, nombres de objetos y lore. Colores, gradientes, eventos hover/click.
  • Interacciones de clic — LEFT, RIGHT, SHIFT, DOUBLE_CLICK, DROP, SWAP_OFFHAND, NUMBER_KEY, SCROLL — por ranura o global.
  • Animaciones — Transiciones de ranura fluidas con easing configurable (linear, ease-in, ease-out).
  • Diálogos de entrada — Solicitudes de entrada de texto durante la interacción con el menú, mediante la API de diálogo de Paper.

Arquitectura

Biblioteca de entradas

Acciones

• Open GUI — El punto de entrada principal. Define una GUI de inventario con título, diseño, objetos, interacciones y almacenamiento.

Configuración

• GUI Settings — Valores por defecto globales: configuración de audio, mapeo del comportamiento de clic sobre el almacenamiento, nodos del árbol de habilidades.

Guías

• Introducción — Cómo funciona el sistema, el vocabulario y tu primer menú paso a paso.
  • Tipos de diseño — Cada motor de diseño con ejemplos completos y cuándo usar cada uno.
  • Comandos e interacciones — Tipos de clic, acciones internas gui:, tiempos de reutilización, diálogos de entrada.
  • Cookbook — Recetas listas para adaptar: lista desplazable, tienda, confirmación, depósito por cuota.

Artefactos

• GUI Storage — Artefacto de almacenamiento persistente. Persistencia de objetos por jugador o por grupo, con soporte de acumulación.

Inicio rápido

• 1. Crear una entrada Open GUI — Crea una entrada de acción Open GUI. Esta única entrada lo define todo sobre un menú: Configuración básica: - title — Título del inventario (MiniMessage + PlaceholderAPI) - guiType — Tipo de inventario: CUSTOM, CHEST, MERCHANT, BOOK, ANVIL, etc. (23 tipos) - size — Para el tipo CUSTOM: SIZE_9 a SIZE_54 Diseño (elige uno): - simple — Coordenadas x,y explícitas, con count/direction/gap/repeatY para patrones en cuadrícula - scrollable — Viewport con botones de desplazamiento, el diseño interior se desplaza - frame — Varias zonas independientes, cada una con su propio diseño hijo - paginated — Páginas discretas con navegación siguiente/anterior - composite — Hijos apilados en orden Z - book — Páginas MiniMessage como libro escrito - merchant — Intercambios de aldeano con objetos personalizados Objetos e interacciones: - Define ranuras con item, displayName, lore — usa x/y/count/direction para el posicionamiento - Adjunta interactionList por ranura: LEFT, RIGHT, SHIFT_LEFT, SHIFT_RIGHT, DOUBLE_CLICK, DROP, etc. - Adjunta triggers para disparar acciones de Typewriter al hacer clic Almacenamiento (opcional): - Añade storage a cualquier ranura para persistir objetos - Usa los placeholders {stored_name}, {stored_amount}, {stored_max} → Referencia de la entrada Open GUI

• 2. Enlazar desde otras extensiones — Una vez que exista tu entrada GUI, referénciala desde cualquier otra extensión que necesite un menú: - QuestCodex — quest_codex_settings usa el diseño GUI para explorar misiones - Shops — Los menús de tienda usan diseños GUI para mostrar objetos - BattlePass, Crates, Pets, Party, Profiles, Cosmetics, Dungeon, BTCSky... — Todas usan la extensión GUI para sus menús Simplemente referencia el ID de la entrada de acción Open GUI en la config de menú de la otra extensión. > La extensión GUI es una dependencia requerida por más de 20 extensiones.

Tipos de diseño

SimpleLayout

Objetos colocados en coordenadas (x, y) explícitas sobre una cuadrícula virtual. Ideal para menús estáticos, decoraciones y fondos. Admite count, direction, gap y repeatY para patrones en cuadrícula.

ScrollableLayout

Envuelve un diseño hijo con soporte de desplazamiento. Los botones de desplazamiento personalizados (UP/DOWN/LEFT/RIGHT) están anclados al viewport — no se mueven cuando el contenido se desplaza. Ideal para listas largas de objetos.

FrameLayout

Divide la pantalla en zonas independientes. Cada frame tiene su propia posición, tamaño y diseño hijo (normalmente desplazable). Ideal para paneles de control, barras laterales y paneles de varios compartimentos. Cada zona desplazable debe tener un ID único para un aislamiento correcto del desplazamiento.

PaginatedLayout

Páginas discretas con botones de navegación siguiente/anterior. Ideal para menús de varias páginas y grandes colecciones.

CompositeLayout

Superpone varios diseños hijos en orden Z. Ideal para superposiciones e interfaces complejas.

BookLayout

Representa páginas MiniMessage como un libro escrito. Ideal para lore, guías y diálogos.

MerchantLayout

Define intercambios de aldeano con objetos de entrada y un resultado. Ideal para tiendas y comercio.

Referencia de interacciones

Todas las interacciones admitidas

Interacción	Disparador
LEFT	Botón izquierdo del ratón
RIGHT	Botón derecho del ratón
SHIFT_LEFT	Shift + clic izquierdo
SHIFT_RIGHT	Shift + clic derecho
MIDDLE	Botón central del ratón
DOUBLE_CLICK	Doble clic
NUMBER_KEY_1..9	Teclas de barra rápida 1-9
DROP	Tecla Q
DROP_ALL	Ctrl+Q
SWAP_OFFHAND	Tecla F

Uso: interactionList por ranura para las acciones de clic, globalInteractions para atajos de todo el menú.

Referencia de tipos de GUI

Los 23 tipos de inventario admitidos

Tipo	Descripción
CUSTOM	Cofre configurable (1-6 filas)
CHEST	Cofre estándar
FURNACE	Horno
BLAST_FURNACE	Alto horno
SMOKER	Ahumador
BEACON	Faro
ENCHANTING_TABLE	Mesa de encantamientos
GRINDSTONE	Reparación con muela
CARTOGRAPHY_TABLE	Modificación de mapa
ANVIL	Reparación/renombrado con yunque
LOOM	Telar (patrones de estandarte)
SMITHING_TABLE	Mesa de herrería
STONECUTTER	Cortapiedras
CRAFTING_TABLE	Mesa de trabajo
BREWING_STAND	Soporte para pociones
HOPPER	Tolva
DROPPER	Dropper
DISPENSER	Dispensador
BARREL	Barril
SHULKER_BOX	Caja de shulker
ENDER_CHEST	Cofre del End
MERCHANT	Comercio con mercader
BOOK	Libro escrito

Almacenamiento y acumulación

• Almacenamiento estándar: haz clic para depositar/retirar objetos. Todos los comportamientos de clic son configurables globalmente mediante GUI Settings.
• Placeholders de almacenamiento: {stored_name}, {stored_amount}, {stored_max} se resuelven dinámicamente en el displayName y el lore de la ranura
• forceStorage: true (por defecto): los objetos no apilables (espadas, herramientas, armaduras) pueden almacenarse
• Modo acumulación: define requiredItem + requiredAmount — los objetos se consumen, los disparadores onReachRequired se activan en el umbral
• Almacenamiento de grupo: comparte el almacenamiento entre jugadores (p. ej. equipo de isla) mediante la entrada group
• Ranuras temporales: objetos eliminados tras cerrar (temporary = true)
• Disparadores onFill / onEmpty: activan acciones de Typewriter al cambiar el estado de la ranura

Consulta GUI Storage Artifact para todos los detalles.

Placeholders

Placeholders de almacenamiento

Resueltos en el displayName y el lore de una ranura de almacenamiento:

Placeholder	Descripción
{stored_name}	Nombre visible del objeto almacenado
{stored_amount}	Cantidad actual de objetos en la ranura
{stored_max}	Capacidad máxima de la ranura

Placeholders del motor

Los títulos de GUI y el lore de los objetos también admiten los placeholders del motor de Typewriter y de PlaceholderAPI mediante los campos @Placeholder.

Comandos

Esta extensión no proporciona comandos independientes. Todas las interacciones de menú pasan por las entradas de Typewriter.

Permisos

Sin permisos personalizados. El acceso a la GUI se controla mediante las entradas que referencian las acciones Open GUI.

Dependencias

Extension	Requerido	Uso
(ninguna)	-	Es una extensión fundamental. Más de 20 extensiones dependen de ella.
PlaceholderAPI	Opcional	Para los campos @Placeholder en títulos, nombres y lore.