Pular para o conteúdo principal

UiCore

Menus, HUD, diálogos, minimapa e placas de nome desenhados no espaço GUI com um shader, sem mod de cliente.

Privadasv0.1.0-alphaMenus e visuais
RequerTypeWriter0.9.0-beta-177 (BTC build)CraftEnginePacketEventsEntityQuestBTCMobsGUIopcionalCodexopcionalBattlePassopcionalTinyEssentialsopcionalCosmeticsopcionalPartyopcional

Criada para a rede BornToCraft. Esta extensão é documentada como referência e não é distribuída.

Suporte

Visão geral​

O UiCore desenha menus, cards, um HUD, diálogos, um minimapa e um mapa-múndi no espaço de GUI do cliente vanilla, sem mod no cliente. Ele faz isso com um core shader (text.vsh) transportado pelo resource pack: tudo o que é desenhado é um glifo de fonte, e o shader lê o ascent e a cor do glifo para saber onde colocá-lo em uma grade fixa de 15 por 15. O resultado é idêntico para todos os jogadores, seja qual for a escala da GUI, o campo de visão ou o tamanho da janela, e pode aparecer em qualquer lugar da tela, e não apenas onde um inventário abre.

O UiCore substitui duas ferramentas mais antigas: o AdvancedMenus (menus de baú) e o BetterHud. Um menu deixa de ser um inventário de baú: é uma view, uma pilha de camadas de componentes que você cria no painel web e para a qual o jogador aponta com a cabeça. A mesma grade desenha módulos de HUD, linhas de diálogo e escolhas.

A pasta de código-fonte desta extensão tem o nome da antiga extensão de HUD; o nome da extensão é UiCore. Ela roda no build BTC do TypeWriter, precisa do CraftEngine para hospedar o resource pack e está marcada como alpha (0.1.0-alpha).

Recursos​

  • Views — telas inteiras com painéis, botões, listas, abas, subtelas, tooltips, medidores e entrada de texto.
  • Estados e animações — os componentes mudam com facts ou permissões, e uma view pode chegar com um wipe, um bloom ou um fade.
  • Módulos de HUD — elementos permanentes ancorados a um canto ou ao centro, ocultados enquanto o jogador lê outra tela.
  • Diálogo — falas e escolhas respondidas com a roda do mouse ou o cursor, com uma única entry de estilo compartilhada.
  • Diálogo de cinemática — a mesma fala em uma linha do tempo de cinemática.
  • Minimapa e mapa-múndi — mapa do terreno com pontos de interesse, waypoints e um modo de levantamento.
  • Nameplates — nameplates 3D para mobs e jogadores, com banners, selos de nível e indicadores de status de NPC.
  • Banners e controle do chat — um anúncio de uma linha no topo da tela e uma ação para silenciar o chat em um lugar.
  • Triggers por item — abra uma view clicando com o botão direito em um material.
  • Integrações — mostra dados de quests, codex, battle pass, cosméticos, pets, social, wiki e RPG Core quando essas extensões estão presentes.

Instalação​

  1. Instale o CraftEngine: ele hospeda o resource pack que carrega o shader, as fontes e as imagens. Instale o PacketEvents se ele ainda não for fornecido pelo seu build; ele é usado para a supressão do chat e para a roda do mouse e as teclas de movimento.
  2. Instale as extensões Entity e Quest do TypeWriter e a extensão BTCMobs: elas são dependências declaradas.
  3. Opcionalmente, instale as extensões das quais o UiCore pode ler dados: Ghost, Codex, BattlePass, TinyEssentials, Cosmetics, NumericalStorage, Permissions, Pets, Friend, Party e Guild. A extensão GUI também é opcional: quando presente, o UiCore lê os estados de menu que ela publica.
  4. Coloque o JAR do UiCore em plugins/Typewriter/extensions/ e reinicie o servidor.
  5. Implante o fragmento de resource pack do UiCore no pack do CraftEngine. O pack é gerado pela ferramenta da própria extensão (generate-gui-pack, depois validate-gui-pack) e deve ser implantado antes do JAR correspondente; caso contrário, todo ícone de item se desloca uma posição sem nenhum erro.
Identificadores do resource pack

Um identificador de recurso do Minecraft só aceita [a-z0-9._-/]. Um provider de fonte com qualquer outro caractere é rejeitado silenciosamente pelo cliente, e o glifo aparece como um retângulo preto no topo da tela. O gerador do pack se recusa a gravar um caminho assim.

Primeiros passos​

Abra um pequeno menu a partir de uma bússola.

  1. No painel web do TypeWriter, abra uma page static e adicione uma entry UI View. Defina viewId como hello_menu.
  2. Adicione uma camada (layerId main) e um primeiro componente: placement.kind CELL, column 4, row 6, width 7, height 3, palette SURFACE, hoverPalette BLUE_LIGHT, text Hello, tooltip Click me.
  3. Em onLeftClick, ligue uma ação como um comando ou uma mensagem. Adicione um segundo componente com navigateTo ou Close UI View para sair.
  4. Adicione uma ação Open UI View com viewId hello_menu, ou vincule um item: adicione um UI Item Trigger com material COMPASS e viewId hello_menu.
  5. Publique. Clique com o botão direito em uma bússola: a tela aparece, aponte para o botão com a cabeça e clique.

Como funciona​

Uma view é uma lista de camadas (de trás para a frente); uma camada contém componentes; um componente diz onde fica, como é pintado, o que mostra e o que um clique dispara. Três limites vêm da codificação, não do código:

  • Uma cor é um índice. A cor de uma célula carrega sua coluna, linha e índice de paleta, então as cores vêm de uma paleta nomeada fixa (SURFACE, BLUE_LIGHT, GOLD...), e não de valores hexadecimais livres.
  • Imagens são baratas, fontes são escassas. Um componente pode ser pintado com uma imagem de painel; qualquer número de imagens compartilha uma fonte. A cor do texto vem da fonte, e o pack inclui 16 cores de texto, então uma 17ª volta para o branco.
  • Nada desliza e o texto não esmaece. Uma animação revela as células em uma ordem. O texto chega junto com o seu painel.

As views abertas se recusam a iniciar enquanto o jogador está caindo (o jogador recebe uma mensagem). Uma cadeia de renderizadores (rendererOrder de UI Configuration) decide qual renderizador atende uma view: GUI (este shader), DIALOG, SPATIAL ou CHEST.

Abertura​

Uma view pode ser aberta por:

  • a ação Open UI View (viewId);
  • o comando /ui open <viewId> de uma entry UI View Commands;
  • um UI Item Trigger, que abre uma view quando o jogador clica com o botão direito com um dado material (duas views que reivindicam o mesmo material geram um aviso no log e apenas a última abre);
  • o openMaterial do minimapa, que abre o mapa-múndi.

Close UI View ou /ui close a fecha.

Layout e componentes​

A grade é de 15 colunas por 15 linhas para menus. placement.kind é CELL (uma célula na grade: column, row, width, height), MARKER (uma posição de 0 a 1 ao longo da viewport, x e y, limitada) ou SCRIM (um véu de tela cheia). Um botão precisa de várias células para ser fácil de mirar.

Campo do componenteEfeito
palette, hoverPalette, disabledPaletteCor em repouso, sob o cursor e enquanto os criteria não correspondem.
backgroundUma imagem de painel do pack (nine-slice) em vez de uma cor lisa; backgroundBinding escolhe a imagem a partir de um placeholder.
text, textPalette, textAlign, textEffectTexto desenhado ao longo do componente.
icon, lineIconA imagem de um material desenhada diante do texto ou fechando a linha.
image, imageBindingUma imagem do pack ajustada dentro do componente mantendo sua proporção.
label, tooltipTexto exibido ao lado da tela, ou na âncora do tooltip, enquanto o cursor repousa sobre o componente.
gaugeDesenha uma barra a partir de um placeholder com valor de 0 a 100 (por exemplo btcui_health_percent).
bindingUm placeholder de onde o componente tira seu valor.
criteria, onLeftClick, onRightClickCondições para clicar e as entries disparadas.
navigateToAbre outra tela da mesma view.
inputPede ao jogador que digite um valor; onInputCommands são executados pelo console com {input} e %player% substituídos.

Telas, listas e estados​

  • Nodes (nodes, rootNodeId) declaram abas e subtelas, cada uma escolhendo qual camada preenche qual região nomeada. Os títulos alimentam o breadcrumb.
  • Repeats (repeats em uma camada) desenham uma janela sobre fontes numeradas: o item n lê o binding <source>.<n>. stepMode PAGE vira uma janela inteira por gesto, ITEM move de um em um.
  • States (states) alteram componentes enquanto uma condição vale: uma cor, texto, tooltip, ícone, painel ou visibilidade. O estado de maior prioridade cujas condições valem é o ativo, um estado pode refinar um parentId, e um componente é endereçado por id ou por column:row. Os estados são reavaliados a cada repintura.
  • Chegada (opening, openingMillis, openingFade): WIPE_DOWN, WIPE_UP, WIPE_RIGHT, WIPE_LEFT, BLOOM ou FADE. Ela só toca ao entrar na interface, não entre duas telas.

Paleta​

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 não desenha nada.

Interação​

O cursor segue a cabeça do jogador: o yaw e o pitch são projetados na grade e encaixados em uma célula. Os jogadores mudam a velocidade dele com /ui sensitivity <degrees>: um ângulo maior significa um cursor mais lento.

  • Os cliques esquerdo e direito disparam onLeftClick e onRightClick; a roda do mouse rola listas e abas; Sneak é um atalho que fecha a view (exceto enquanto uma lista de árvore de pesquisa está em foco).
  • A view cede ao mundo: afastar-se, um teletransporte, sofrer dano ou abrir um inventário a fecha.
  • Enquanto uma view está aberta, o chat dos outros jogadores é mantido fora da tela, e as mensagens do servidor são redesenhadas pelo chat da UI em vez do chat vanilla.

Módulos de HUD​

As entries UI HUD usam as mesmas camadas e componentes de uma view, ancoradas a um corner (TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT, CENTRE); os deslocamentos contam para dentro a partir dele. priority decide qual de dois grupos sobrepostos é desenhado por cima e visibility controla o grupo. Os módulos de HUD são suspensos automaticamente enquanto uma view, um diálogo, uma cinemática ou o mapa-múndi ocupa a tela.

UI Spoken Dialogue mostra uma fala com o nome do falante, um portrait opcional, uma duration de digitação (zero a exibe de uma vez) e um sound. UI Option Dialogue adiciona escolhas (options): navigation é KEYS (roda do mouse e tecla de confirmação), CURSOR ou ambos (o padrão); um timer cancela o diálogo e dispara cancelTriggers; cada escolha tem criteria (é desenhada bloqueada, ou oculta com hideWhenLocked), um lockedReason exibido no lugar do tooltip enquanto bloqueada, modifiers e triggers. Ambos recebem uma entry style; deixe-a vazia para usar a do próprio servidor.

UI Dialogue Style define a aparência em células da grade: speech (moldura, área de texto, faixa do falante, retrato), options (janela, painel, cores para escolhas selecionadas e bloqueadas, cursor e setas de rolagem, segunda coluna opcional) e chrome (imagem da tecla de confirmação, linha de contagem regressiva, linhas de letterbox). UI Spoken Cinematic coloca falas em uma page de cinemática com segmentos startFrame e endFrame.

Mapas e nameplates​

O minimapa permanente é configurado por Minimap Settings (worlds e excludeListedWorlds, size, blocksPerCell, borderThickness, openMaterial, maxWaypoints, worldMapAreas) e seus pontos por Minimap Points of Interest. Sua posição na tela é definida no resource pack, não aqui, porque o servidor não conhece nem a resolução nem a escala da GUI. O mapa-múndi abre clicando com o botão direito em openMaterial ou com /worldmap; durante o jogo normal, ele é preenchido com o que o minimapa lê, e o modo de levantamento mapeia deliberadamente um raio maior.

As nameplates são tridimensionais e por espectador. Global Nameplate desenha linhas acima dos mobs (entityTypes, btcMobsOnly, lines, viewDistance, requireLineOfSight...). Player Nameplate Banner define fundos de banner selecionáveis (um prefixo de imagem do CraftEngine com as partes _left, _middle e _right), e a escolha do jogador é armazenada em um selection artifact. Nameplate Settings define distâncias, orçamentos e a unidade de vida; Level Badge Settings define a palavra escrita antes de um nível (prefixo padrão, pode ser um placeholder de tradução). NPC Status Override coloca um modelo indicador (disponível, ativo, interação...) acima de um NPC.

Comandos​

ComandoDescrição
/ui open <viewId>Abre uma view.
/ui closeFecha a view aberta.
/ui sensitivity [degrees]Mostra ou define a amplitude do seu cursor em graus.
/ui icons [materials]Imprime ícones de itens no chat para verificar a fonte de sprites.
/ui chat vanillaApenas operadores: entrega a você o chat vanilla até você se desconectar ou executá-lo novamente.
/worldmapAbre ou fecha o mapa-múndi.
/worldmap survey, forget, stats, minimap, waypoint <name>, waypoint clear, save, debugModo de levantamento, esquecer o seu mapa, mostrar seu tamanho, alternar o minimapa, renomear ou limpar waypoints, salvar e imprimir um diagnóstico.
/nameplates (aliases /nameplate, /btcnameplates)equip <id>, unequip, preview [id], list, toggle [on|off] e as formas de admin force-equip, force-unequip, force-preview, admin-toggle.

Os nomes de /ui e /worldmap vêm dos campos commandName de suas entries. O campo permission delas é um nó de permissão que você escolhe: vazio significa todos. /worldmap survey, forget, save e a alternância do levantamento usam surveyPermission.

Permissões​

PermissãoConcede
permission de UI View CommandsSubcomandos de /ui (vazio: todos).
permission e surveyPermission de World Map Command/worldmap, e levantamento e esquecer (vazio: todos).
btcnameplates.command.equip, .unequip, .preview, .list, .toggleOs subcomandos /nameplates correspondentes para jogadores.
btcnameplates.command.admin.force_equip, .force_unequip, .force_preview, .toggleOs subcomandos de admin de /nameplates.
visibility.permission em componentes e gruposMostra ou oculta um elemento para jogadores sem o nó.

Placeholders​

Expansão btcui do MiniPlaceholders, para componentes, medidores e texto.

PlaceholderRetorna
<btcui_level_glyph:37>Qualquer número escrito como os dígitos de nível coloridos do pack.
<btcui_global_level_glyph>, <btcui_global_level>, <btcui_global_level_badge>O nível global como glifos, dígitos ou com o prefixo configurado.
<btcui_global_percent>, <btcui_global_detail>, <btcui_xp_detail>Progresso até o próximo nível global e seus números.
<btcui_health>, <btcui_health_max>, <btcui_health_percent>, <btcui_absorption>Vida e absorção.
<btcui_food>, <btcui_food_max>, <btcui_food_percent>, <btcui_saturation>Fome.
<btcui_air>, <btcui_air_max>, <btcui_air_percent>, <btcui_air_gauge>Suprimento de ar; o medidor fica vazio enquanto o jogador não está com falta de ar.
<btcui_xp_level>, <btcui_xp_progress>, <btcui_xp_percent>A barra de experiência vanilla (usada para encantar).
<btcui_riding>, <btcui_mount_name>, <btcui_mount_health>, <btcui_mount_health_max>, <btcui_mount_health_percent>, <btcui_mount_gauge>A montaria.
<btcui_underwater>, <btcui_swimming>, <btcui_burning>, <btcui_freezing>Estados do jogador.
<btcui_x>, <btcui_y>, <btcui_z>, <btcui_world_time>, <btcui_world_day>Posição e horário.
<btcui_banner>, <btcui_actionbar>, <btcui_chat:...>Banner atual, action bar e linhas de chat desenhadas pela UI.

Entries​

26 entradas, geradas a partir do código-fonte da extensão.

Ações5
Audiências2
Diálogos2
Cinemáticas1
Dados de entidade1
Comandos2
Artefatos1
Manifestos12

Solução de problemas​

Retângulos pretos ou tofu onde deveriam estar texto e células. O fragmento do resource pack está ausente, desatualizado ou foi implantado depois do JAR, ou um caminho de fonte contém um caractere fora de [a-z0-9._-/]. Reimplante primeiro o pack e depois o JAR correspondente e verifique se o CraftEngine o recarregou.

Os ícones de itens mostram o item errado. O pack e o JAR não correspondem: o caractere de um ícone é a sua posição na tabela, então um pack gerado depois do JAR desloca todos os ícones. Regenere e valide o pack e depois reimplante ambos.

Um item abre um menu vazio. Dois vínculos UI Item Trigger reivindicam o mesmo material; o log diz est reclame par ... com a contagem de componentes de cada um. Remova o vínculo extra.

names view '<id>', which no page defines. O viewId passado à ação, ao comando ou ao item não corresponde a nenhuma UI View publicada. Uma view declared but incomplete não tem nenhuma camada ou componente que pudesse ser resolvido.

O menu não abre no ar. O UiCore se recusa a abrir uma tela enquanto o jogador está caindo. Tente de novo no chão.

O chat desapareceu. O UiCore desenha o chat por conta própria: uma view está aberta, um Mute UI Chat está ativo ou o jogador o desligou. Use Unmute UI Chat ao sair do lugar onde você o silenciou; os operadores podem usar /ui chat vanilla para conferir o chat vanilla.

Os gestos param de funcionar. Gesture decoding unavailable no log significa que o PacketEvents não conseguiu iniciar: a roda do mouse e as teclas de movimento são perdidas, mas os cliques ainda funcionam.

Extensões relacionadas​