Configurando Adventure-Platform para Texto Formatado em Serv

Se você construiu plugins ou software de servidor para Minecraft, provavelmente sentiu a dor da formatação de texto. Cores, estilos, eventos de clique, texto de flutuação - tudo é específico da plataforma. Paper lida de uma forma, BungeeCord de outra, Sponge de mais outra. Adventure-Platform resolve isso fornecendo uma API unificada para componentes de texto que funciona em todas elas.

O Que Adventure-Platform Faz

Adventure-Platform é um conjunto de implementações que se situam sobre a biblioteca Adventure, uma biblioteca de componentes de texto criada por Kyori. Pense em Adventure como a linguagem comum, e Adventure-Platform como o tradutor para diferentes plataformas Minecraft.

Por si só, Adventure é agnóstica de plataforma - não sabe sobre o formato NBT do Paper ou arrays de bytes do BungeeCord. Apenas fornece APIs Java limpas. Mas seu software de servidor? Precisa de componentes de texto nativos. É aí que Adventure-Platform entra. Envolve implementações específicas de plataforma em uma única interface limpa.

Suporta Paper, Spigot e Bukkit no lado do servidor. Lida com proxies BungeeCord. Até cobre Sponge se você estiver interessado nisso. A versão mais recente adicionou suporte para Minecraft 1.21.6 e 1.21.7.

Por Que Desenvolvedores de Servidor Usam Isso

Digamos que você está escrevendo um plugin que precisa de uma mensagem de entrada personalizada com cores, eventos de clique e dicas de flutuação. Sem Adventure-Platform, você escreveria uma versão para Bukkit, outra para Sponge, talvez uma terceira para Velocity. Nada divertido.

Com Adventure-Platform, você escreve uma vez. A biblioteca descobre em qual plataforma você está e traduz seus componentes automaticamente. Cores, gradientes, ofuscação, tachado - tudo tratado. Eventos de clique (abrir URL, executar comando, copiar para área de transferência, mostrar texto) funcionam em todas as plataformas.

Exemplo do mundo real: você está construindo um MOTD (mensagem do dia) do servidor. Usando Adventure, você cria um componente de texto com cores e texto de flutuação. Adventure-Platform converte isso para qualquer formato que seu servidor entenda. Se você mudar de Paper para BungeeCord depois, seu código permanece o mesmo.

Isso é genuinamente útil se você estiver mantendo um plugin ou software de servidor que visa múltiplas plataformas.

Colocando Adventure-Platform no Seu Projeto

Primeiro, você precisará adicionar a dependência. Os artefatos do Adventure-Platform vivem no Maven Central. Aqui está como você o configuraria em um arquivo de build do Gradle:

repositories {
 mavenCentral()
}

dependencies {
 // Para servidores baseados em Bukkit (Paper, Spigot, Craftbukkit)
 implementation "net.kyori:adventure-platform-bukkit:4.4.1"

 // Para BungeeCord
 // implementation "net.kyori:adventure-platform-bungeecord:4.4.1"

 // Para Sponge API 7
 // implementation "net.kyori:adventure-platform-sponge7:4.4.1"
}

Escolha o artefato correto para sua plataforma. Se você está usando Maven em vez disso, as coordenadas são as mesmas, apenas em sintaxe XML do Maven.

Depois de adicionar a dependência, você precisa obter uma Adventure Audience para seu servidor:

import net.kyori.adventure.audience.Audience;
import net.kyori.adventure.platform.bukkit.BukkitAudiences;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;

public class MyPlugin extends JavaPlugin {
 private BukkitAudiences audiences;

 @Override
 public void onEnable() {
 this.audiences = BukkitAudiences.create(this);
 }

 @Override
 public void onDisable() {
 if (this.audiences!= null) {
 this.audiences.close();
 }
 }

 public void sendMessage(Player player) {
 Audience audience = this.audiences.player(player);
 Component message = Component.text("Olá, ", NamedTextColor.GOLD).append(Component.text(player.getName(), NamedTextColor.YELLOW));
 audience.sendMessage(message);
 }
}

Esse é o padrão básico. Crie seu objeto Audiences uma vez em onEnable(), feche-o em onDisable(), depois use-o para enviar componentes para jogadores.

O Que Você Pode Fazer Com Isso

Cores de texto em todas as 16 cores legadas mais suporte RGB completo. Minecraft 1.16+ permite usar qualquer valor de cor que você quiser, e Adventure lida com a conversão em versões antigas.

Estilos de texto funcionam da forma que você esperaria: negrito, itálico, sublinhado, tachado, ofuscado. Combine-os de qualquer forma. Construa texto com gradiente, onde cores mudam ao longo da mensagem.

Eventos de clique tornam suas mensagens interativas. Os jogadores podem clicar para abrir URLs, executar comandos, copiar para área de transferência ou mostrar uma mensagem de dica. Eventos de flutuação exibem texto quando os jogadores passam o mouse sobre um componente - perfeito para dicas ou explicações. Se você está criando algo como um MOTD personalizado, você pode adicionar funcionalidade de clique para entrar ou texto de flutuação decorativo.

Traduções são integradas. Adventure possui um tipo de componente traduzível que trata as chaves de tradução integradas do Minecraft mais as personalizadas. O servidor trata a negociação de idioma automaticamente.

A serialização JSON funciona se você precisar armazenar componentes ou enviá-los pela rede. Veja, a biblioteca pode converter componentes para e a partir de JSON, seguindo o formato nativo do Minecraft.

Armadilhas e O Que Pode Prender Você

O maior erro: não fechar seu objeto Audiences. Ele mantém recursos. Se você criar uma BukkitAudiences ou similar e não fechá-la quando seu plugin se desativa, você está vazando memória. Sempre feche em onDisable().

A serialização de componentes varia entre versões. Na verdade, isso não é bem preciso - a própria serialização é estável, mas o formato NBT interno que o Minecraft usa mudou em 1.21.6. A versão mais recente do Adventure-Platform lida com isso, mas se você estiver em uma versão mais antiga e pular para 1.21.6, você pode ver comportamento estranho com componentes armazenados existentes. Isso importa se você estiver armazenando componentes em cache ou armazenando-os em bancos de dados.

Não assuma que todas as plataformas suportam todos os recursos igualmente. Por exemplo, algumas implementações mais antigas do Sponge podem ter suporte limitado para recursos de texto mais novos. Verifique a documentação específica da plataforma no site de documentação do Adventure antes de contar com formatação de caso extremo.

Cores RGB precisam de 1.16+. Se você está visando servidores mais antigos, fique com as cores nomeadas ou use amostragem de cores para baixo (que Adventure pode fazer, mas você precisa tratar adequadamente).

O Que Mais Existe Por Aí

MiniMessage é uma linguagem de componentes baseada em string que funciona junto com Adventure. Em vez de construir componentes em código, você pode escrevê-los em um formato legível para humanos: "Olá!". É mais leve se você estiver construindo texto de arquivos de configuração ou entrada do usuário. MiniMessage e Adventure funcionam bem juntos.

Se você não está pronto para uma biblioteca completa como Adventure, LegacyChat ou outras alternativas mais simples existem. Eles lidam com o básico (cores, formatação) sem a complexidade. A compensação é que você não obtém eventos de clique, flutuações, traduções ou abstração de plataforma. Bom para pequenos projetos. Não é bom se você precisa de recursos além de cores simples.

Algumas plataformas agrupam suas próprias APIs de texto. Sponge tem sua própria implementação de texto que é próxima a Adventure mas não idêntica. Waterfall (o proxy sucessor do Velocity) incentiva o uso do Adventure. Se você está construindo para uma plataforma específica e não planejando suportar múltiplos servidores, você pode pular Adventure completamente e usar a API nativa. Mas se houver qualquer chance de você precisar reutilizar código ou suportar múltiplas plataformas depois, Adventure-Platform vale o investimento inicial.

Vale a Pena Configurar Isso?

Sim, se você está escrevendo um plugin ou software de servidor que pode acabar em múltiplos tipos de plataforma ou se você quer que seu código seja reutilizável. A configuração é direta, a API é limpa, e você evita um monte de dores de cabeça no caminho.

Se você está desenvolvendo sozinho um pequeno plugin para uma versão de servidor específica e plataforma, você pode não precisar disso. Mas no momento em que você pensa "e se eu quiser usar isso em um tipo de servidor diferente?" ou "e se alguém me pedir para executar isso em seu servidor Sponge?" Adventure-Platform o poupa de uma reescrita.

A biblioteca existe há anos e é ativamente mantida (no momento desta escrita, atualizações recentes adicionaram suporte 1.21.6 / 1.21.7). É usada por software de servidor e plugins principais. Não é uma aposta arriscada.