GUI

A extensão GUI é o sistema de menus central do Typewriter. Ela fornece 9 motores de layout configuráveis (além de componentes apenas de API), 23 tipos de inventário, interações de teclado/mouse, armazenamento de itens persistente e formatação MiniMessage completa. Quase todas as demais extensões dependem dela para seus menus.

Em breve: um editor web WYSIWYG com arrastar e soltar, pré-visualização ao vivo fiel ao jogo, layout automático com flexbox CSS, estados de menu, tilemaps e suporte a resource packs de múltiplos provedores.

• Código-fonte — Ver as fontes no GitHub.
  • Baixar releases — Obter os JARs mais recentes.

Recursos

• 9 motores de layout — Simple, Composite, Scrollable, Paginated, Frame, Flex, Storage, Book, Merchant — além de Iterator, Slider e ReactiveSlot pela API Kotlin.
  • 23 tipos de inventário — Baú, fornalha, bigorna, mesa de encantamentos, mesa de forja, mercador, livro e mais.
  • Rolagem e navegação — Layouts roláveis com botões cima/baixo/esquerda/direita configuráveis. Os botões de rolagem ficam ancorados ao viewport. Multiframe com zonas independentes.
  • Armazenamento persistente — Armazenamento de itens apoiado por artefatos — por jogador ou por grupo. Modo de acumulação para acompanhamento de progresso. Ações de clique configuráveis.
  • Placeholders de armazenamento — Placeholders dinâmicos {stored_name}, {stored_amount}, {stored_max} nos nomes e lore dos slots.
  • MiniMessage — Suporte completo a MiniMessage para títulos, nomes de itens e lore. Cores, gradientes, eventos hover/click.
  • Interações de clique — LEFT, RIGHT, SHIFT, DOUBLE_CLICK, DROP, SWAP_OFFHAND, NUMBER_KEY, SCROLL — por slot ou global.
  • Animações — Transições suaves de slot com easing configurável (linear, ease-in, ease-out).
  • Diálogos de entrada — Solicitações de entrada de texto durante a interação com o menu, pela API de diálogo do Paper.

Arquitetura

Biblioteca de entradas

Ações

• Open GUI — O ponto de entrada principal. Define uma GUI de inventário com título, layout, itens, interações e armazenamento.

Configuração

• GUI Settings — Valores padrão globais: configuração de áudio, mapeamento do comportamento de clique sobre o armazenamento, nós da árvore de habilidades.

Guias

• Introdução — Como o sistema funciona, o vocabulário e seu primeiro menu passo a passo.
  • Tipos de layout — Cada motor de layout com exemplos completos e quando usar cada um.
  • Comandos e interações — Tipos de clique, ações internas gui:, recargas, diálogos de entrada.
  • Cookbook — Receitas prontas para adaptar: lista rolável, loja, confirmação, depósito por cota.

Artefatos

• GUI Storage — Artefato de armazenamento persistente. Persistência de itens por jogador ou por grupo, com suporte a acumulação.

Início rápido

• 1. Criar uma entrada Open GUI — Crie uma entrada de ação Open GUI. Essa única entrada define tudo sobre um menu: Configuração básica: - title — Título do inventário (MiniMessage + PlaceholderAPI) - guiType — Tipo de inventário: CUSTOM, CHEST, MERCHANT, BOOK, ANVIL etc. (23 tipos) - size — Para o tipo CUSTOM: SIZE_9 a SIZE_54 Layout (escolha um): - simple — Coordenadas x,y explícitas, com count/direction/gap/repeatY para padrões em grade - scrollable — Viewport com botões de rolagem, o layout interno rola - frame — Várias zonas independentes, cada uma com seu próprio layout filho - paginated — Páginas discretas com navegação próxima/anterior - composite — Filhos empilhados na ordem Z - book — Páginas MiniMessage como livro escrito - merchant — Trocas de aldeão com itens personalizados Itens e interações: - Defina slots com item, displayName, lore — use x/y/count/direction para posicionamento - Anexe interactionList por slot: LEFT, RIGHT, SHIFT_LEFT, SHIFT_RIGHT, DOUBLE_CLICK, DROP etc. - Anexe triggers para disparar ações do Typewriter ao clicar Armazenamento (opcional): - Adicione storage a qualquer slot para persistir itens - Use os placeholders {stored_name}, {stored_amount}, {stored_max} → Referência da entrada Open GUI

• 2. Vincular a partir de outras extensões — Uma vez que sua entrada GUI exista, referencie-a de qualquer outra extensão que precise de um menu: - QuestCodex — quest_codex_settings usa o layout GUI para navegar por missões - Shops — Os menus de loja usam layouts GUI para exibir itens - BattlePass, Crates, Pets, Party, Profiles, Cosmetics, Dungeon, BTCSky... — Todos usam a extensão GUI para seus menus Basta referenciar o ID da entrada de ação Open GUI na config de menu da outra extensão. > A extensão GUI é uma dependência obrigatória de mais de 20 outras extensões.

Tipos de layout

SimpleLayout

Itens colocados em coordenadas (x, y) explícitas em uma grade virtual. Ideal para menus estáticos, decorações e planos de fundo. Suporta count, direction, gap e repeatY para padrões em grade.

ScrollableLayout

Envolve um layout filho com suporte a rolagem. Os botões de rolagem personalizados (UP/DOWN/LEFT/RIGHT) ficam ancorados ao viewport — não se movem quando o conteúdo rola. Ideal para listas longas de itens.

FrameLayout

Divide a tela em zonas independentes. Cada frame tem sua própria posição, tamanho e layout filho (geralmente rolável). Ideal para painéis, barras laterais e painéis de vários compartimentos. Cada zona rolável deve ter um ID único para o isolamento correto da rolagem.

PaginatedLayout

Páginas discretas com botões de navegação próxima/anterior. Ideal para menus de várias páginas e grandes coleções.

CompositeLayout

Sobrepõe vários layouts filhos na ordem Z. Ideal para sobreposições e interfaces complexas.

BookLayout

Renderiza páginas MiniMessage como um livro escrito. Ideal para lore, guias e diálogos.

MerchantLayout

Define trocas de aldeão com itens de entrada e um resultado. Ideal para lojas e comércio.

Referência de interações

Todas as interações suportadas

Interação	Gatilho
LEFT	Botão esquerdo do mouse
RIGHT	Botão direito do mouse
SHIFT_LEFT	Shift + clique esquerdo
SHIFT_RIGHT	Shift + clique direito
MIDDLE	Botão do meio do mouse
DOUBLE_CLICK	Clique duplo
NUMBER_KEY_1..9	Teclas da barra rápida 1-9
DROP	Tecla Q
DROP_ALL	Ctrl+Q
SWAP_OFFHAND	Tecla F

Uso: interactionList por slot para as ações de clique, globalInteractions para atalhos de todo o menu.

Referência dos tipos de GUI

Todos os 23 tipos de inventário suportados

Tipo	Descrição
CUSTOM	Baú configurável (1-6 linhas)
CHEST	Baú padrão
FURNACE	Fornalha
BLAST_FURNACE	Alto-forno
SMOKER	Defumador
BEACON	Sinalizador
ENCHANTING_TABLE	Mesa de encantamentos
GRINDSTONE	Reparo na rebolo
CARTOGRAPHY_TABLE	Modificação de mapa
ANVIL	Reparo/renomeação na bigorna
LOOM	Tear (padrões de estandarte)
SMITHING_TABLE	Mesa de forja
STONECUTTER	Cortador de pedra
CRAFTING_TABLE	Bancada de trabalho
BREWING_STAND	Suporte de poções
HOPPER	Funil
DROPPER	Dropper
DISPENSER	Dispensador
BARREL	Barril
SHULKER_BOX	Caixa de shulker
ENDER_CHEST	Baú do End
MERCHANT	Comércio com mercador
BOOK	Livro escrito

Armazenamento e acumulação

• Armazenamento padrão: clique para depositar/retirar itens. Todos os comportamentos de clique são configuráveis globalmente por GUI Settings.
• Placeholders de armazenamento: {stored_name}, {stored_amount}, {stored_max} são resolvidos dinamicamente no displayName e no lore do slot
• forceStorage: true (padrão): itens não empilháveis (espadas, ferramentas, armaduras) podem ser armazenados
• Modo de acumulação: defina requiredItem + requiredAmount — os itens são consumidos, os gatilhos onReachRequired disparam no limite
• Armazenamento de grupo: compartilhe o armazenamento entre jogadores (ex.: equipe de ilha) pela entrada group
• Slots temporários: itens removidos após fechar (temporary = true)
• Gatilhos onFill / onEmpty: disparam ações do Typewriter nas mudanças de estado do slot

Consulte GUI Storage Artifact para todos os detalhes.

Placeholders

Placeholders de armazenamento

Resolvidos no displayName e no lore de um slot de armazenamento:

Placeholder	Descrição
{stored_name}	Nome de exibição do item armazenado
{stored_amount}	Quantidade atual de itens no slot
{stored_max}	Capacidade máxima do slot

Placeholders do motor

Os títulos de GUI e o lore dos itens também suportam os placeholders do motor Typewriter e o PlaceholderAPI por meio dos campos @Placeholder.

Comandos

Esta extensão não fornece comandos independentes. Todas as interações de menu passam pelas entradas do Typewriter.

Permissões

Sem permissões personalizadas. O acesso à GUI é controlado pelas entradas que referenciam as ações Open GUI.

Dependências

Extension	Obrigatório	Uso
(nenhuma)	-	Esta é uma extensão fundamental. Mais de 20 extensões dependem dela.
PlaceholderAPI	Opcional	Para os campos @Placeholder em títulos, nomes e lore.