dmulloy2/ProtocolLib
Fornece acesso de leitura e escrita ao protocolo Minecraft com Bukkit.
Ver no GitHub ↗Já tentou criar um plugin de servidor Minecraft que faça algo que a API Bukkit padrão não permite? Sim, é aí que a maioria dos desenvolvedores bate numa parede. Você ou faz engenharia reversa de código Minecraft ofuscado (que quebra a cada atualização), faz hook em classes internas do CraftBukkit (e reza para nenhum outro plugin fazer a mesma coisa), ou simplesmente desiste. ProtocolLib é o projeto que existe especificamente para você não ter que fazer isso.
O Que Este Projeto Resolve
ProtocolLib é uma biblioteca Java que oferece acesso limpo e seguro ao protocolo de rede Minecraft. Em vez de lutar com bytecode ofuscado ou hacks duvidosos de reflection, você consegue uma API de eventos adequada que permite ouvir, modificar ou cancelar pacotes enviados entre o servidor e os clientes. Pense nisso como eventos Bukkit, mas para a camada de protocolo.
A grande vantagem: você não faz referência ao CraftBukkit. Sem importações específicas de versão que quebrem na 1.21. Sem suposições frágeis sobre estruturas de classe internas. Apenas listeners de pacotes que se mantêm estáveis entre atualizações.
Casos de Uso Reais do Minecraft
Filtragem e moderação de chat é a aplicação mais óbvia. Ouça pacotes de chat do lado do cliente, leia o conteúdo da mensagem através da API ProtocolLib, e cancele o pacote se o jogador tentar algo que você bloqueou. A mensagem nunca sequer chega ao servidor. Limpo, simples, e funciona em cada atualização.
Recursos de rede personalizados são onde as coisas ficam interessantes. Você poderia criar efeitos de partículas invisíveis, modificar a aparência do jogador sem mudanças de skin, ou enviar dados para o servidor que o protocolo vanilla não suporta oficialmente. Um sistema de duelos com visuais personalizados? Uma interface de votação que responde a pacotes de movimento do jogador? Essas são as coisas que ProtocolLib torna possíveis.
Mas a razão real pela qual a maioria das pessoas usa é a compatibilidade de plugins. Quando vários plugins fazem hook das mesmas classes internas, tudo fica bagunçado. Plugins quebram. Dados se corrompem silenciosamente. ProtocolLib centraliza o tratamento de pacotes para que diferentes plugins possam realmente coexistir sem pisar nos pés um do outro. Isso não é glamoroso, mas é o que mantém os servidores funcionando sem problemas.
Instalação e Configuração
Se você estiver criando um plugin Bukkit, a configuração é direta. Adicione a dependência ao seu arquivo de compilação primeiro.
Para Maven:
<dependencies>
<dependency>
<groupId>net.dmulloy2</groupId>
<artifactId>ProtocolLib</artifactId>
<version>5.4.0</version>
<scope>provided</scope>
</dependency>
</dependencies>Observe que a versão 5.4.0 requer Java 17 ou superior, então certifique-se de que seu ambiente de compilação está atualizado. Se você estiver em um servidor mais antigo, pegue uma versão anterior.
Usuários do Gradle devem adicionar assim:
repositories {
mavenCentral()
}
dependencies {
compileOnly 'net.dmulloy2:ProtocolLib:5.4.0'
}Em seguida, adicione ProtocolLib como uma dependência em seu plugin.yml:
depend: [ ProtocolLib ]Isso diz ao servidor que seu plugin não iniciará a menos que ProtocolLib carregue primeiro. Crítico para evitar exceções de null pointer na inicialização. Em seguida, pegue uma referência ao ProtocolManager no método onLoad() do seu plugin:
private ProtocolManager protocolManager;
public void onLoad() {
protocolManager = ProtocolLibrary.getProtocolManager();
}É isso. Você está pronto para começar a ouvir pacotes.
Como Funcionam os Listeners de Pacotes
O listener mais simples apenas desativa algo. Digamos que você queira silenciar todos os efeitos sonoros em todo o servidor:
protocolManager.addPacketListener(new PacketAdapter(
this,
ListenerPriority.NORMAL,
PacketType.Play.Server.NAMED_SOUND_EFFECT
) {
@Override
public void onPacketSending(PacketEvent event) {
event.setCancelled(true);
}
});A maior parte da complexidade está ali. Você cria um PacketAdapter, especifica qual tipo de pacote está ouvindo, substitui o callback e modifica o evento.
Onde fica útil é na leitura e mudança do conteúdo do pacote. Aqui está um filtro de chat global:
protocolManager.addPacketListener(new PacketAdapter(
this,
ListenerPriority.NORMAL,
PacketType.Play.Client.CHAT
) {
@Override
public void onPacketReceiving(PacketEvent event) {
PacketContainer packet = event.getPacket();
String message = packet.getStrings().read(0);
if (message.contains("badword")) {
event.setCancelled(true);
}
}
});A chamada getPacket() oferece os dados do pacote. Você lê campos por tipo (strings, inteiros, bytes) usando seu índice. Sem nomes de campo, apenas posições. É abstrato no início, mas significa que você nunca depende da nomenclatura interna do Minecraft, que muda constantemente com ofuscação.
Você também pode modificar pacotes. Os dados do pacote são mutáveis, então você pode escrever novos valores antes de serem enviados. A prioridade do listener também é importante - se vários plugins ouvem o mesmo tipo de pacote, LOWEST executa primeiro, HIGHEST executa por último, permitindo que você controle a ordem de execução.
Recursos Principais Que Tornam Isso Vale a Pena Usar
A camada de abstração é o principal. Em vez de lidar com classes NMS ofuscadas (net.minecraft.server), ProtocolLib envolve tudo em accessores digitados. Quer ler a posição do jogador? É apenas packet.getDoubles().read(0), não caçar através de um labirinto de métodos getter em alguma classe interna que provavelmente se renomeou no último snapshot.
A compatibilidade de versão é enorme. ProtocolLib mantém definições de pacotes para cada versão principal do Minecraft. Quando você atualiza seu servidor de 1.20 para 1.21.4, seu código ProtocolLib simplesmente funciona. A biblioteca lida com mudanças de protocolo internamente. Você não recompila nada.
A injeção de pacotes é outro recurso sólido. Você pode criar pacotes do zero e enviá-los para jogadores:
PacketContainer packet = protocolManager.createPacket(PacketType.Play.Server.NAMED_SOUND_EFFECT);
// populate fields...
protocolManager.sendServerPacket(player, packet);Isso é limpo em comparação com tentar instanciar classes de pacote NMS diretamente. E novamente, isso sobrevive às atualizações sem modificação.
A biblioteca também inclui classes auxiliares como WrappedChatComponent, ChunkData e PlayerInfoData - basicamente qualquer coisa complicada de construir é envolvida com construtores convenientes. A versão recente 5.4.0 corrigiu problemas de inicialização para versões de 1.20.4 a 1.21.5, então elas são mantidas ativamente.
O Que Confunde Novos Usuários
O acesso a campos baseado em índice leva tempo para se acostumar. Você consulta o wiki de pacotes para descobrir qual índice corresponde a qual campo. Para pacotes comuns, é documentado, mas se estiver lidando com algo personalizado ou muito recente, você está por conta própria. Esse é o tradeoff de não estar vinculado a nomes de classe internos.
A segurança de thread é importante. O Minecraft executa o tratamento de pacotes no thread de rede, e seu código de listener também é executado lá. Se você fizer qualquer coisa pesada, agende-a no thread do servidor principal via Bukkit.getScheduler(). Bloquear seu listener de pacote paralisa todo o pipeline de rede.
Incompatibilidades de versão destruirão você. Se você compilar contra ProtocolLib 5.4.0 mas o servidor tiver 5.3.0 instalado, você obterá erros de class not found em tempo de execução. Combine versões exatamente. Não confie em recursos de versões mais recentes a menos que especifique uma versão mínima em seu plugin.yml.
A depuração é mais difícil do que o código regular porque tudo é baseado em listeners. Se um pacote não estiver se comportando corretamente, adicione logging em cada etapa. Verifique se seu listener está sendo chamado. Verifique se os índices de campo correspondem ao que você espera. O wiki de protocolo é seu amigo aqui.
Alternativas e Quando Considerá-las
PacketEvents existe como outra opção, embora seja mais novo e menos testado em batalha. Se você está construindo algo que precisa de acesso profundo ao protocolo com ferramentas modernas e não se importa em estar em um terreno um pouco menos estável, PacketEvents pode apelar para você. Mas ProtocolLib é a escolha estabelecida - 1.285 estrelas no GitHub, mantida ativamente, e a versão mais recente suporta Minecraft de 1.21.4 a 1.21.8.
Alguns desenvolvedores trabalham diretamente com NMS para casos de uso altamente especializados. Isso geralmente é um erro porque você se inscreve em trabalho de manutenção a cada lançamento do Minecraft. ProtocolLib lida com isso para você.
Se você precisar explorar o que os jogadores podem fazer com seu servidor, confira nossas ferramentas Minecraft Skin Creator e Minecraft Block Search.
dmulloy2/ProtocolLib - GPL-2.0, ⭐1.285


