dmulloy2/ProtocolLib
Proporciona acceso de lectura y escritura al protocolo Minecraft con Bukkit.
Ver en GitHub ↗¿Alguna vez intentaste crear un plugin de servidor Minecraft que hiciera algo que la API estándar de Bukkit no permite? Sí, ese es donde la mayoría de desarrolladores chocan. O haces ingeniería inversa del código Minecraft ofuscado (que se rompe en cada actualización), accedes a clases internas de CraftBukkit (y esperas que ningún otro plugin haga lo mismo), o simplemente te rindes. ProtocolLib es el proyecto que existe específicamente para que no tengas que hacerlo.
Lo que Este Proyecto Resuelve
ProtocolLib es una librería Java que te proporciona acceso limpio y seguro al protocolo de red de Minecraft. En lugar de luchar con bytecode ofuscado o trucos de reflexión cuestionables, obtienes una API de eventos adecuada que te permite escuchar, modificar o cancelar paquetes enviados entre el servidor y los clientes. Piénsalo como eventos de Bukkit, pero para la capa de protocolo.
La gran ventaja: no haces referencia a CraftBukkit en absoluto. Sin importaciones específicas de versión que se rompan en 1.21. Sin suposiciones frágiles sobre estructuras de clases internas. Solo escuchadores de paquetes que permanecen estables entre actualizaciones.
Casos de Uso Reales de Minecraft
El filtrado y moderación de chat es la aplicación más evidente. Escucha paquetes de chat del lado del cliente, lee el contenido del mensaje a través de la API de ProtocolLib, y cancela el paquete si el jugador intenta algo bloqueado. El mensaje nunca llega al servidor. Limpio, simple, y funciona en cada actualización.
Las características de red personalizadas son donde las cosas se ponen interesantes. Podrías construir efectos de partículas invisibles, modificar la apariencia del jugador sin cambios de skin, o enviar datos al servidor que el protocolo vanilla no soporta oficialmente. ¿Un sistema de duelos con gráficos personalizados? ¿Una interfaz de votación que responda a paquetes de movimiento del jugador? Estos son los tipos de cosas que ProtocolLib hace posible.
Pero la razón real por la que la mayoría de personas la usan es la compatibilidad entre plugins. Cuando varios plugins se conectan a las mismas clases internas, todo se vuelve caótico. Los plugins se cuelgan. Los datos se corrompen silenciosamente. ProtocolLib centraliza el manejo de paquetes para que plugins diferentes puedan coexistir sin pisarse. Eso no es glamoroso, pero es lo que mantiene los servidores funcionando sin problemas.
Instalación y Configuración
Si estás construyendo un plugin de Bukkit, la configuración es sencilla. Primero agrega la dependencia a tu archivo de compilación.
Para Maven:
<dependencies>
<dependency>
<groupId>net.dmulloy2</groupId>
<artifactId>ProtocolLib</artifactId>
<version>5.4.0</version>
<scope>provided</scope>
</dependency>
</dependencies>Ten en cuenta que la versión 5.4.0 requiere Java 17 o superior, así que asegúrate de que tu entorno de compilación esté actualizado. Si estás en un servidor más antiguo, obtén una versión anterior.
Los usuarios de Gradle deberían agregarlo así:
repositories {
mavenCentral()
}
dependencies {
compileOnly 'net.dmulloy2:ProtocolLib:5.4.0'
}A continuación, agrega ProtocolLib como una dependencia en tu plugin.yml:
depend: [ ProtocolLib ]Esto le dice al servidor que tu plugin no se iniciará a menos que ProtocolLib se cargue primero. Crítico para evitar excepciones de puntero nulo al iniciar. Luego obtén una referencia a ProtocolManager en el método onLoad() de tu plugin:
private ProtocolManager protocolManager;
public void onLoad() {
protocolManager = ProtocolLibrary.getProtocolManager();
}Eso es todo. Estás listo para comenzar a escuchar paquetes.
Cómo Funcionan los Escuchadores de Paquetes
El escuchador más simple simplemente desactiva algo. Supongamos que quieres silenciar todos los efectos de sonido en todo el servidor:
protocolManager.addPacketListener(new PacketAdapter(
this,
ListenerPriority.NORMAL,
PacketType.Play.Server.NAMED_SOUND_EFFECT
) {
@Override
public void onPacketSending(PacketEvent event) {
event.setCancelled(true);
}
});La mayoría de la complejidad está ahí. Creas un PacketAdapter, especificas qué tipo de paquete estás escuchando, anulas el callback y modificas el evento.
Donde se vuelve útil es leyendo y cambiando el contenido del paquete. Aquí hay un 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);
}
}
});La llamada getPacket() te proporciona los datos del paquete. Lees campos por tipo (strings, enteros, bytes) usando su índice. Sin nombres de campo, solo posiciones. Es abstracto al principio, pero significa que nunca dependen de la nomenclatura interna de Minecraft, que cambia constantemente con la ofuscación.
También puedes modificar paquetes. Los datos del paquete son mutables, así que puedes escribir nuevos valores antes de que se envíen. La prioridad del escuchador también importa - si múltiples plugins escuchan el mismo tipo de paquete, LOWEST se ejecuta primero, HIGHEST se ejecuta último, permitiéndote controlar el orden de ejecución.
Características Clave que Hacen que Valga la Pena
La capa de abstracción es lo principal. En lugar de tratar con clases NMS ofuscadas (net.minecraft.server), ProtocolLib envuelve todo en accesores tipados. ¿Quieres leer la posición del jugador? Es solo packet.getDoubles().read(0), no buscando a través de un laberinto de métodos getter en alguna clase interna que probablemente se renombró en la última versión.
La compatibilidad de versión es enorme. ProtocolLib mantiene definiciones de paquetes para cada lanzamiento importante de Minecraft. Cuando actualizas tu servidor de 1.20 a 1.21.4, tu código de ProtocolLib simplemente funciona. La librería maneja cambios de protocolo internamente. No tienes que recompilar nada.
La inyección de paquetes es otra característica sólida. Puedes crear paquetes desde cero y enviarlos a jugadores:
PacketContainer packet = protocolManager.createPacket(PacketType.Play.Server.NAMED_SOUND_EFFECT);
// populate fields...
protocolManager.sendServerPacket(player, packet);Eso es limpio comparado con intentar instanciar clases de paquetes NMS directamente. Y de nuevo, sobrevive a las actualizaciones sin modificación.
La librería también incluye clases auxiliares como WrappedChatComponent, ChunkData y PlayerInfoData - básicamente cualquier cosa complicada de construir se envuelve con constructores convenientes. El lanzamiento reciente de 5.4.0 corrigió problemas de inicialización para las versiones 1.20.4 a 1.21.5, por lo que están siendo activamente mantenidas.
Lo que Confunde a los Usuarios Nuevos
El acceso basado en índice requiere acostumbrarse. Consultas el wiki de paquetes para averiguar qué índice corresponde a qué campo. Para paquetes comunes está documentado, pero si estás tratando algo personalizado o muy reciente, estás por tu cuenta. Ese es el equilibrio por no estar vinculado a nombres de clases internas.
La seguridad de hilos importa. Minecraft ejecuta el manejo de paquetes en el hilo de red, y tu código de escuchador también se ejecuta allí. Si haces algo pesado, programa lo en el hilo principal del servidor a través de Bukkit.getScheduler(). Bloquear tu escuchador de paquetes detiene toda la canalización de red.
Los desajustes de versión te arruinarán. Si compilas contra ProtocolLib 5.4.0 pero el servidor tiene 5.3.0 instalado, obtienes errores de clase no encontrada en tiempo de ejecución. Haz coincidir las versiones exactamente. No confíes en características de versiones más nuevas a menos que especifiques una versión mínima en tu plugin.yml.
La depuración es más difícil que el código regular porque todo está basado en escuchadores. Si un paquete no se comporta correctamente, agrega registros en cada paso. Verifica que tu escuchador se esté llamando. Comprueba que los índices de campo coincidan con lo que esperas. El wiki del protocolo es tu amigo aquí.
Alternativas y Cuándo Considerarlas
PacketEvents existe como otra opción, aunque es más nuevo y menos probado en combate. Si estás construyendo algo que necesita acceso profundo al protocolo con herramientas modernas y no te importa estar en terreno ligeramente menos estable, PacketEvents podría interesarte. Pero ProtocolLib es la opción establecida - 1.285 estrellas en GitHub, activamente mantenido, y el lanzamiento más reciente soporta Minecraft 1.21.4 a 1.21.8.
Algunos desarrolladores simplemente trabajan directamente con NMS para casos de uso muy especializados. Eso generalmente es un error porque estás inscribiéndote para trabajo de mantenimiento en cada lanzamiento de Minecraft. ProtocolLib lo maneja por ti.
Si necesitas explorar qué pueden hacer los jugadores con tu servidor, consulta nuestras herramientas Minecraft Skin Creator y Minecraft Block Search.
dmulloy2/ProtocolLib - GPL-2.0, ⭐1.285


