ProtocolLib - biblioteka pakietów na serwerze Minecraft

Co to jest ProtocolLib

ProtocolLib to open-source'owa biblioteka dla serwerów Minecraft opartych na Bukkit/Spigot/Paper, stworzona przez programistę o pseudonimie dmulloy2. Projekt istnieje od 2012 roku i przez ponad dekadę stał się de facto standardowym narzędziem do pracy z protokołem sieciowym Minecrafta po stronie serwera.

Biblioteka działa na poziomie, do którego standardowe Bukkit API nie daje dostępu: bezpośrednio przy przesyłaniu danych między serwerem a klientem. Każde zdarzenie w grze — ruch gracza, zmiana bloku, pojawienie się encji, efekt cząsteczkowy, wiadomość na czacie — jest kodowane jako pakiet sieciowy wysyłany w obie strony. ProtocolLib pozwala pluginom "wejść" w ten strumień danych i modyfikować go zanim pakiet dotrze do gracza lub zanim serwer go przetworzy.

Sama biblioteka nie dodaje żadnych komend, bloków, mechnik ani zmian widocznych dla graczy. Jest to czysto techniczne narzędzie przeznaczone dla twórców pluginów, a jej obecność w katalogu plugins/ jest wymagana tylko dlatego, że inne pluginy na niej polegają.

Kod źródłowy dostępny jest na GitHubie, a oficjalne wydania pobierzesz ze strony na SpigotMC.

Dlaczego jest potrzebny

Bukkit API — standardowy interfejs programistyczny dla pluginów Minecraft — daje dostęp do wielu aspektów gry, ale nie do wszystkiego. Wiele rzeczy, które wyglądają jak proste operacje, wymagają bezpośredniego operowania na pakietach protokołu, ponieważ Bukkit API ich nie obsługuje lub obsługuje tylko częściowo.

Przykłady zastosowań, które są niemożliwe lub bardzo trudne bez ProtocolLib:

• Hologramy — wyświetlanie tekstu w powietrzu wymaga wysłania klientowi fałszywej encji (zazwyczaj Armor Standu lub pływającego tekstu), której serwer "oficjalnie" nie zna. Pakiet wysyła się bezpośrednio do klienta z pominięciem normalnego rejestru encji.
• NPC — podobnie jak hologramy, postacie NPC często są tworzone jako fałszywe pakiety gracza, nieistniejące w rzeczywistości gry. Citizens i podobne pluginy używają ProtocolLib do wysyłania i zarządzania takimi wirtualnymi bytami.
• Przebrania (disguises) — zamiana wyglądu gracza lub moba w oczach innych graczy wymaga nadpisania pakietów definicji encji. Lib's Disguises wysyła każdemu obserwatorowi inne dane o tej samej encji.
• Anti-cheaty — wykrywanie cheaterów często opiera się na analizie pakietów ruchu, interakcji i akcji gracza zanim Bukkit je przetworzy. Surowe pakiety zawierają więcej informacji i są trudniejsze do ukrycia przez klienty cheatujące.
• Obsługa wielu wersji klientów — ViaVersion i ProtocolSupport tłumaczą pakiety między różnymi wersjami protokołu w locie, co wymaga głębokiej integracji z warstwą sieciową.
• Niestandardowe tablice wyników i nagłówki — TAB i podobne pluginy personalizują liste graczy (Tab list) modyfikując pakiety, których Bukkit nie udostępnia przez swoje API.

Krótko mówiąc: jeśli plugin robi coś, czego normalne API nie pozwala, bardzo prawdopodobne, że używa ProtocolLib.

Instalacja

Instalacja ProtocolLib jest identyczna jak każdego innego pluginu — plik .jar wrzucasz do katalogu plugins/ i restartujesz serwer. Nie ma żadnej konfiguracji ani uprawnień do ustawienia.

1. Przejdź na stronę SpigotMC ProtocolLib lub pobierz bezpośrednio z GitHub Releases.
2. Upewnij się, że wybierasz wersję zgodną z Twoją wersją Minecrafta. Strona SpigotMC wymaga zalogowania do pobierania — GitHub Releases nie wymaga konta.
3. Wrzuć plik ProtocolLib.jar do katalogu plugins/.
4. Zrestartuj serwer. W logach powinieneś zobaczyć linię podobną do: [ProtocolLib] Loading ProtocolLib vX.X.X.

ProtocolLib nie wymaga żadnych zewnętrznych zależności. Po instalacji nie pojawi się żadna nowa komenda ani zmiana w rozgrywce — biblioteka działa w tle. Możesz sprawdzić jej status komendą /plugins (powinna świecić się na zielono) lub /pl.

Jeśli używasz managera pluginów takiego jak Pterodactyl, możesz też zainstalować ProtocolLib bezpośrednio przez jego Marketplace lub wbudowany menedżer pluginów Paper — wyszukaj "ProtocolLib" i zainstaluj jednym kliknięciem.

Pluginy wymagające ProtocolLib

Poniżej znajdują się najpopularniejsze pluginy, które wymagają lub mogą korzystać z ProtocolLib. Bez zainstalowanej biblioteki te pluginy nie uruchomią się lub będą działać z poważnymi ograniczeniami.

Lista pluginów korzystających z ProtocolLib jest znacznie dłuższa. Wiele pluginów mini-gier, systemów rankingowych i efektów wizualnych używa tej biblioteki. Jeśli plugin przy uruchomieniu wyrzuca błąd Could not load plugin: Caused by: java.lang.ClassNotFoundException i w stosie błędów widzisz ProtocolLib — to znak, że musisz go zainstalować.

Pełny katalog pluginów znajdziesz w katalogu pluginów.

Jak działa - przechwytywanie pakietów

Komunikacja między klientem Minecraft a serwerem odbywa się przez protokół sieciowy oparty na TCP. Każde zdarzenie — logowanie, ruch gracza, interakcja z blokiem, pojawienie się encji, zmiana stanu świata — jest kodowane jako numerowany pakiet zawierający określone pola danych.

ProtocolLib wstrzykuje się w warstwę sieciową serwera (Netty pipeline) i rejestruje listenery pakietów. Pluginy mogą się zarejestrować do nasłuchu konkretnych typów pakietów, zarówno przychodzących (od klienta do serwera), jak i wychodzących (od serwera do klienta).

Listener otrzymuje pakiet zanim zostanie przetworzony lub wysłany, może go:

• Odczytać — analiza wartości pól pakietu (np. pozycja gracza, prędkość, kliknięty blok)
• Zmodyfikować — zmiana wartości pól przed dostarczeniem (np. zmiana wyświetlanej nazwy encji)
• Anulować — całkowite zablokowanie pakietu tak, że odbiorca go nie zobaczy
• Wysłać nowy — wstrzyknięcie własnego pakietu niezwiązanego z żadnym zdarzeniem gry

Dzięki temu HolographicDisplays może wysyłać klientowi pakiet "spawn entity" z encją, która nie istnieje w normalnym rejestrze serwera. Lib's Disguises może wysłać graczowi A informację, że encja X wygląda jak krowa, a graczowi B, że ta sama encja X wygląda jak creeper — wszystko przez selektywną modyfikację pakietów wychodzących. Vulcan może przechwycić pakiet ruchu klienta i porównać go z oczekiwanym zachowaniem fizyki, zanim silnik gry go zaakceptuje.

ProtocolLib dostarcza warstwę abstrakcji nad surowym Netty — programiści pluginów nie muszą znać szczegółów kodowania pakietów Minecrafta ani zajmować się zmianami protokołu między wersjami. Biblioteka obsługuje to automatycznie.

Wersje Minecraft

ProtocolLib jest aktywnie utrzymywany i na bieżąco aktualizowany przy każdej nowej wersji Minecrafta. Każda duża aktualizacja gry zmienia protokół sieciowy (numery pakietów, ich pola, kodowanie), co wymaga aktualizacji biblioteki.

Aktualne wsparcie wersji (stan na kwiecień 2026):

• Minecraft 1.21.x — pełne wsparcie, stabilna wersja ProtocolLib 5.x
• Minecraft 1.20.x — pełne wsparcie
• Minecraft 1.19.x — pełne wsparcie
• Minecraft 1.18.x i starsze — wsparcie przez starsze wersje ProtocolLib (pobierz konkretną wersję z GitHub Releases)
• Minecraft 1.8 - 1.17 — obsługiwane przez ProtocolLib 4.x i starsze gałęzie

Zawsze sprawdzaj stronę wydania na SpigotMC lub GitHubie, która weryfikuje zgodność z Twoją wersją serwera. Używanie nieodpowiedniej wersji ProtocolLib powoduje błędy i może uniemożliwić uruchomienie serwera lub zależnych pluginów.

Ważna zasada: przy aktualizacji serwera do nowej wersji Minecrafta, zaktualizuj ProtocolLib jako pierwszy — przed innymi pluginami które go wymagają. Nieaktualna biblioteka spowoduje błędy kaskadowo we wszystkich zależnych pluginach.

Problemy i rozwiązywanie

ProtocolLib jest zazwyczaj bezproblemowy, ale kilka typowych sytuacji może powodować trudności:

Plugin wymagający ProtocolLib się nie ładuje

Sprawdź w logach serwera, czy ProtocolLib w ogóle się załadował. Jeśli widzisz błąd Could not load ProtocolLib lub biblioteka jest oznaczona na czerwono w /plugins, problem leży w samym ProtocolLib — sprawdź wersję względem Twojego serwera.

Błąd "PacketType X not found" lub "Unknown packet"

Zazwyczaj oznacza to, że używasz wersji ProtocolLib niezgodnej z aktualną wersją Minecrafta. Po aktualizacji serwera zawsze pobierz najnowszy ProtocolLib.

Wyjątki NullPointerException w logach przy przechwytywaniu pakietów

To problem w pluginie korzystającym z ProtocolLib, nie w samej bibliotece. Sprawdź tracker błędów danego pluginu. Tymczasowe obejście: wyłącz plugin powodujący błędy i poczekaj na jego aktualizację.

Serwer zwalnia przy dużej liczbie graczy

ProtocolLib dodaje narzut procesowania dla każdego pakietu, zwłaszcza jeśli wiele pluginów zarejestrowało listenery. Na serwerach z 50+ graczami i wieloma pluginami korzystającymi z ProtocolLib monitoruj użycie CPU. Upewnij się, że pluginy prawidłowo wyrejestrowują listenery, gdy nie są potrzebne.

Hologramy lub NPC nie wyświetlają się prawidłowo

Często przyczyną jest konflikt wersji między ProtocolLib a pluginem go używającym. Sprawdź, czy obie biblioteki są w wersjach zalecanych do użytku ze swoją wersją Minecrafta.

Aktualizacja w locie (hot reload)

ProtocolLib nie obsługuje przeładowania przez /reload. Zawsze restartuj serwer po aktualizacji lub zmianie konfiguracji pluginów zależnych.

Kompatybilność

ProtocolLib jest kompatybilny z następującymi platformami serwerowymi:

• Paper — rekomendowana platforma, najlepsza wydajność i kompatybilność
• Purpur — pochodna Paper, pełna kompatybilność
• Spigot — pełna kompatybilność, choć Paper jest rekomendowany
• CraftBukkit — technicznie kompatybilny, ale CraftBukkit nie jest zalecany do użytku produkcyjnego

ProtocolLib nie działa z następującymi platformami:

• Fabric — zupełnie inne API i architektura modów
• Forge — podobnie, osobny ekosystem niezgodny z Bukkit
• Velocity / BungeeCord (proxy) — proxy nie uruchamia pluginów Bukkit, ProtocolLib działa tylko na serwerach "backend"
• Vanilla — brak jakiegokolwiek API pluginów

Jeśli prowadzisz sieć serwerów z BungeeCord lub Velocity jako proxy, ProtocolLib instalujesz na każdym serwerze backend osobno — nie na samym proxy. Każdy serwer w sieci (np. Survival, Skyblock, PvP) będzie wymagał własnej kopii biblioteki, jeśli jego pluginy jej potrzebują.

ProtocolLib współpracuje bezproblemowo z innymi popularnymi bibliotekami jak Vault (ekonomia), LuckPerms (uprawnienia) czy PlaceholderAPI — nie ma między nimi żadnych znanych konfliktów. W razie wątpliwości sprawdź katalog pluginów, aby upewnić się, że Twój zestaw narzędzi jest ze sobą zgodny.

Często zadawane pytania

Czy ProtocolLib jest potrzebny na każdym serwerze?

ProtocolLib jest potrzebny tylko wtedy, gdy korzystasz z pluginów, które go wymagają. Sam w sobie nic nie robi i nie wpływa na rozgrywkę — jest wyłącznie biblioteką techniczną. Jeśli żaden Twój plugin go nie wymaga, nie musisz go instalować.

Co się stanie, jeśli ProtocolLib jest nieaktualny?

Nieaktualny ProtocolLib może powodować błędy lub całkowity brak działania pluginów, które go wymagają. Przy aktualizacji serwera do nowej wersji Minecrafta zawsze aktualizuj ProtocolLib jako pierwszy — zanim zaktualizujesz zależne pluginy.

Czy ProtocolLib działa z Paper i Purpur?

Tak, ProtocolLib działa z Paper, Purpur, Spigot i wszystkimi pochodnymi opartymi na Bukkit API. Nie działa z Fabric ani Forge — jest dedykowany wyłącznie dla serwerów opartych na Bukkit/Spigot.