LuckPerms: kompletny przewodnik po uprawnieniach na serwerze Minecraft

LuckPerms to faktyczny standard zarządzania uprawnieniami na serwerach Minecraft. Jeśli masz Paper, Spigot, Velocity, BungeeCord, Fabric lub Forge i chcesz oddzielić dostęp między graczy, moderatorów i adminów, prawdopodobnie zainstalujesz właśnie ten plugin. Jest rozwijany od 2016 roku, aktywnie utrzymywany, obsługuje miliardy sprawdzeń praw na dziesiątkach tysięcy serwerów.

Przejdziemy przez wszystko po kolei: instalacja, pierwsze komendy, grupy, dziedziczenie, prefiksy, tracki, konteksty, edytor webowy, bazy danych, synchronizacja w sieci BungeeCord, integracja z PlaceholderAPI i typowe błędy.

Dlaczego LuckPerms, a nie PEX lub GroupManager

PermissionsEx (PEX) jest martwy, oficjalnie nieutrzymywany, ma krytyczne bugi z utratą danych i słabo działa z nowoczesnym Paperem. GroupManager z EssentialsX uchodzi za przestarzały i brakuje mu połowy funkcji. LuckPerms wygrał z kilku powodów:

• Przechowywanie w dowolnej bazie: YAML, SQLite, H2, MySQL, MariaDB, PostgreSQL, MongoDB
• Edytor webowy luckperms.net/editor z wygodą panelu admina
• Konteksty (świat, serwer, tryb gry, wymiar) z pudełka
• Tracki do awansów: default do vip do moderator do admin jedną komendą
• Solidne API dla deweloperów pluginów
• Synchronizacja uprawnień w sieci BungeeCord / Velocity przez MySQL + messaging

Jeśli nadal korzystasz z PEX, teraz czas na migrację. Komenda wbudowana: /lp import pex.

Instalacja

Paper / Spigot / Purpur

1. Pobierz najnowszą wersję z luckperms.net/download, plik LuckPerms-Bukkit-5.x.x.jar
2. Wrzuć do folderu plugins/
3. Zrestartuj serwer (nie /reload, to często psuje pluginy)
4. Sprawdź:

/plugins

LuckPerms powinien być zielony. Czerwony oznacza problem: zwykle niezgodność wersji Javy albo konflikt z innym pluginem uprawnień.

Velocity (proxy)

1. Pobierz LuckPerms-Velocity-5.x.x.jar
2. Wrzuć do folderu plugins/ Velocity
3. Zrestartuj proxy

Na Velocity LuckPerms steruje uprawnieniami do komend proxy (przełączanie serwerów, komendy globalne). Serwery backendowe wymagają osobnej instalacji.

BungeeCord / Waterfall

Jak Velocity: pobierz LuckPerms-Bungee-5.x.x.jar, wrzuć do plugins/ BungeeCord, zrestartuj.

Fabric

1. Wymagany Fabric Loader i Fabric API
2. Pobierz LuckPerms-Fabric-5.x.x.jar
3. Wrzuć do mods/
4. Zrestartuj serwer

Na Fabric klient nie potrzebuje LuckPerms, tylko serwer.

Forge / NeoForge

Pobierz LuckPerms-Forge-5.x.x.jar lub LuckPerms-NeoForge-5.x.x.jar, wrzuć do mods/, zrestartuj.

Matryca wsparcia platform

Platforma	Wsparcie	Uwagi
Paper 1.16+	Tak	Zalecane
Spigot 1.8-1.20	Tak	Dla starszych serwerów
Velocity	Tak	Proxy
BungeeCord	Tak	Proxy, legacy
Fabric 1.17+	Tak	Wymaga Fabric API
Forge 1.16+	Tak
NeoForge	Tak	1.20.1+
Sponge	Tak	API 7/8
Nukkit	Tak	Serwery Bedrock

Pierwsze kroki

Po instalacji LuckPerms automatycznie tworzy grupę default. Każdy gracz bez innego przypisania trafia do niej. Nie da się jej usunąć.

Szybki test:

/lp info

Pokazuje wersję pluginu, aktywny storage backend, usługę messagingu oraz liczbę unikalnych graczy i grup w bazie.

Lista grup:

/lp listgroups

Zobaczysz tylko default z wagą 0.

Budowa podstawowej hierarchii grup

Większości serwerów wystarczy pięć grup: default, vip, moderator, admin, owner. Tworzymy je:

/lp creategroup vip
/lp creategroup moderator
/lp creategroup admin
/lp creategroup owner

Ustawiamy wagi. Waga decyduje o priorytecie w konfliktach (kto kogo mutuje, czyj prefiks wygrywa) oraz o kolejności sortowania. Wyższa waga, wyższa ranga.

/lp group default permission set weight.1 true
/lp group vip permission set weight.10 true
/lp group moderator permission set weight.50 true
/lp group admin permission set weight.100 true
/lp group owner permission set weight.1000 true

Alternatywnie przez meta:

/lp group vip meta setweight 10
/lp group moderator meta setweight 50
/lp group admin meta setweight 100
/lp group owner meta setweight 1000

Konfiguracja dziedziczenia

Aby admin automatycznie odziedziczył prawa moderatora, a moderator - vipa, ustawiamy parentów:

/lp group vip parent set default
/lp group moderator parent set vip
/lp group admin parent set moderator
/lp group owner parent set admin

Drzewko: default do vip do moderator do admin do owner. Każde prawo nadane default mają wszyscy wyżej.

Sprawdzenie:

/lp group admin info

W sekcji Parents zobaczysz moderator, w Inherited Permissions wszystkie nody z niższych grup.

Nadawanie uprawnień

Nadaj uprawnienie grupie

/lp group default permission set essentials.help true
/lp group default permission set essentials.spawn true
/lp group vip permission set essentials.fly true
/lp group vip permission set essentials.hat true
/lp group moderator permission set essentials.ban true
/lp group moderator permission set essentials.kick true

Zabierz uprawnienie

/lp group vip permission unset essentials.fly

Unset usuwa nodę całkowicie. Jeśli chcesz jawnie zabronić (np. grupa ma wildcard essentials.*, ale jedną konkretną komendę chcesz wyłączyć), ustaw false:

/lp group vip permission set essentials.nuke false

Daj uprawnienie konkretnemu graczowi

/lp user Steve permission set worldedit.limit.unrestricted true
/lp user Steve parent set vip

Pierwsza linia daje Steve'owi osobiste uprawnienie. Druga wrzuca go do grupy vip.

Tymczasowe uprawnienia

LuckPerms pozwala nadawać uprawnienia z datą wygaśnięcia:

/lp user Steve parent add vip 30d
/lp group vip permission set essentials.fly true 7d

Linia pierwsza: Steve w vip na 30 dni. Druga: grupa dostaje latanie na 7 dni.

Jednostki: s (sekundy), m (minuty), h (godziny), d (dni), w (tygodnie), mo (miesiące), y (lata).

Składnia permission nodes

Każdy plugin definiuje swoje nody. Zazwyczaj są hierarchiczne z kropkami:

essentials.fly
essentials.home
essentials.home.multiple
worldedit.region.copy
worldedit.region.paste

Wildcardy

Gwiazdka * daje wszystko z danej gałęzi:

/lp group admin permission set essentials.* true
/lp group moderator permission set worldedit.region.* true

Wygodne, ale niebezpieczne. essentials.* otwiera komendy w stylu /fly, /heal, /god, których moderatorzy być może nie powinni mieć.

Negatywne uprawnienia

False jawnie blokuje:

/lp group vip permission set essentials.* true
/lp group vip permission set essentials.nuke false
/lp group vip permission set essentials.burn false

VIP dostaje prawie wszystkie komendy EssentialsX, oprócz dwóch ryzykownych.

Globalne i root nody

Niektóre nody mają specjalne znaczenie:

• * to absolutny wildcard, daje dosłownie wszystko. Tylko dla ownera.
• luckperms.* otwiera wszystkie komendy LuckPerms. Groźne, pozwala graczowi rozdawać prawa dalej.
• -bukkit.command.plugins blokuje /plugins, żeby gracze nie widzieli listy pluginów.

Konteksty: świat, serwer, tryb gry

Konteksty pozwalają nadawać prawa tylko w określonych warunkach. Klasyka: zezwól na /fly w lobby, ale nie w survival.

/lp group vip permission set essentials.fly true world=lobby
/lp group vip permission set essentials.fly false world=survival

Konteksty działają także dla grup:

/lp user Steve parent add builder world=creative

Steve dostanie uprawnienia grupy builder tylko w świecie creative.

Konteksty serwera

Jeśli masz kilka serwerów pod jednym LuckPerms (MySQL + BungeeCord), konteksty server= rozdzielają uprawnienia:

/lp user Steve permission set essentials.fly true server=survival
/lp user Steve permission set essentials.gamemode true server=creative

Nazwa serwera w config.yml LuckPerms na każdym backendzie:

server: survival

Wbudowane konteksty

Z pudełka: world, server, dimension (Forge), gamemode. Dodatki dodają region (WorldGuard), faction (Factions) i inne.

Prefiksy i sufiksy

LuckPerms sam nie rysuje prefiksów na czacie ani w tabie, tylko je przechowuje. Wyświetlaniem zajmują się EssentialsX Chat, VentureChat, DeluxeChat lub TAB.

Ustaw prefiks dla grupy:

/lp group vip meta setprefix "&a[VIP] "
/lp group moderator meta setprefix "&9[MOD] "
/lp group admin meta setprefix "&c[ADMIN] "
/lp group owner meta setprefix "&4[OWNER] "

Sufiks:

/lp group admin meta setsuffix " &7*"

Prefiksy są dziedziczone. Jeśli gracz nie ma własnego prefiksu, brany jest prefiks grupy o najwyższej wadze.

Wiele prefiksów z priorytetami

/lp user Steve meta addprefix 100 "&6[DEV] "
/lp user Steve meta addprefix 50 "&a[VIP] "

Wyższa liczba, wyższy priorytet. Pierwszy prefiks wyświetli się jako pierwszy.

Konfiguracja EssentialsX Chat

W plugins/EssentialsChat/config.yml (w nowszych wersjach wspólny config) ustawiamy format:

chat:
  format: '{PREFIX}&f{DISPLAYNAME}&7: &f{MESSAGE}'

Format per grupa:

chat:
  format: '{PREFIX}&f{DISPLAYNAME}&7: &f{MESSAGE}'
  group-formats:
    Default: '{PREFIX}&7{DISPLAYNAME}&7: &f{MESSAGE}'
    admin: '{PREFIX}&c{DISPLAYNAME}&7: &f{MESSAGE}'

Tracki: awans i degradacja

Track to uporządkowany łańcuch grup. Przydatne w systemach rangowych.

/lp createtrack staff
/lp track staff append vip
/lp track staff append moderator
/lp track staff append admin
/lp track staff append owner

Sprawdź:

/lp track staff info

Awansuj gracza do kolejnej grupy w tracku:

/lp user Steve promote staff

Jeśli Steve był vipem, staje się moderatorem. Następny awans, admin.

Degradacja:

/lp user Steve demote staff

Tracki per serwer

Tracki działają z kontekstami. Można awansować gracza tylko na konkretnym serwerze:

/lp user Steve promote staff server=survival

Edytor webowy

Killer feature. Na serwerze:

/lp editor

Dostajesz link w stylu https://luckperms.net/editor/abc123. Otwierasz w przeglądarce i masz pełny UI: drzewo grup, lista uprawnień, konteksty, prefiksy. Edycje masowe, drag & drop, sortowanie.

Po zmianach klikasz Save, dostajesz kod. Aplikujesz na serwerze:

/lp applyedits abc123

Bezpieczne z założenia: edytor nie trzyma danych serwera, tylko snapshot, który mu wysłałeś.

Otwórz edytor dla jednej grupy:

/lp editor group vip

Dla jednego gracza:

/lp editor user Steve

Storage

Domyślnie LuckPerms używa H2, wbudowanej bazy plikowej. Dla pojedynczego serwera wystarczy. Jeśli masz sieć BungeeCord lub Velocity z kilkoma serwerami backend, potrzebujesz MySQL do synchronizacji.

Konfiguracja w plugins/LuckPerms/config.yml:

storage-method: h2

Opcje: h2, sqlite, yaml, json, hocon, mysql, mariadb, postgresql, mongodb.

MySQL dla sieci

storage-method: mysql

data:
  address: 127.0.0.1:3306
  database: luckperms
  username: luckperms
  password: TWOJE_HASLO
  pool-settings:
    maximum-pool-size: 10
    minimum-idle: 10
    maximum-lifetime: 1800000
    connection-timeout: 5000
  table-prefix: 'luckperms_'

Stworzenie bazy i usera (MySQL 8):

CREATE DATABASE luckperms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'luckperms'@'localhost' IDENTIFIED BY 'TWOJE_HASLO';
GRANT ALL PRIVILEGES ON luckperms.* TO 'luckperms'@'localhost';
FLUSH PRIVILEGES;

Tabele LuckPerms stworzy sam przy pierwszym starcie.

Messaging dla błyskawicznej synchronizacji

Sam MySQL nie wystarczy. Zmienisz prawa na serwerze A, serwer B nie wie o tym do restartu lub ręcznej synchronizacji. Rozwiązaniem jest messaging:

messaging-service: pluginmsg

Opcje:

• pluginmsg przez kanał pluginowy Minecraft, darmowo, wymaga proxy (BungeeCord/Velocity)
• redis wymaga serwera Redis
• rabbitmq wymaga RabbitMQ
• sql odpytuje MySQL, nie błyskawicznie

Większości sieci starczy pluginmsg.

Kopie zapasowe

Eksport wszystkich danych:

/lp export backup.json.gz

Plik pojawi się w plugins/LuckPerms/. Import:

/lp import backup.json.gz

Rób kopie zapasowe przed dużymi zmianami (migracje, edycje masowe).

Migracja z innych pluginów

Z PermissionsEx

/lp import pex

Komenda czyta dane PEX i tworzy odpowiednie grupy oraz uprawnienia w LuckPerms.

Z GroupManager

/lp import groupmanager

Z PermissionsBukkit

/lp import permissionsbukkit

Po imporcie sprawdź wagi grup i dziedziczenie, te dane często przenoszą się niedokładnie.

Integracja z PlaceholderAPI

Zainstaluj PlaceholderAPI, potem pobierz rozszerzenie:

/papi ecloud download luckperms
/papi reload

Dostępne placeholdery:

Placeholder	Zwraca
%luckperms_prefix%	Prefiks gracza
%luckperms_suffix%	Sufiks gracza
%luckperms_primary_group_name%	Nazwa głównej grupy
%luckperms_groups%	Lista grup oddzielona przecinkami
%luckperms_meta_<key>%	Dowolny klucz meta
%luckperms_has_permission_<node>%	true/false dla nody
%luckperms_expiry_time_<group>%	Czas wygaśnięcia tymczasowej grupy

W pluginie TAB:

tablist-name-format: '%luckperms_prefix%%player_name%%luckperms_suffix%'

W scoreboardzie:

lines:
  - '&7Grupa: %luckperms_primary_group_name%'
  - '&7Ranga: %luckperms_prefix%'

Typowe zadania

Daj VIP prawo do latania

/lp group vip permission set essentials.fly true
/lp group vip permission set essentials.fly.others false

Zabroń default odpalać TNT

/lp group default permission set worldguard.region.bypass.* false

Plus w WorldGuard na regionie mainworld:

/region flag __global__ tnt deny

Moderator może banować, ale nie oppować

/lp group moderator permission set essentials.ban true
/lp group moderator permission set essentials.kick true
/lp group moderator permission set essentials.tempban true
/lp group moderator permission set essentials.op false
/lp group moderator permission set minecraft.command.op false

Strefa tylko do budowania dla VIP-buildera

/lp creategroup builder
/lp group builder parent set vip
/lp group builder permission set worldedit.* true world=build
/lp group builder permission set worldedit.* false world=survival

Prawo AFK dla jednej grupy

/lp group afkers permission set essentials.afk true
/lp user Steve parent add afkers 1h

Debugowanie uprawnień

Tryb verbose

Nie wiesz, czemu graczowi nie działa komenda? Włącz verbose:

/lp verbose on

LuckPerms zacznie logować każde sprawdzenie uprawnień. Poproś gracza, żeby spróbował akcji, w konsoli pojawią się linie typu:

[LP] Steve - essentials.fly - true (from group.vip)
[LP] Steve - worldguard.region.bypass.spawn - undefined

Wyłączenie:

/lp verbose off

Zapis do pliku:

/lp verbose record

Log można pobrać przez edytor webowy, link pojawi się w konsoli.

/lp user info

Wszystko o graczu:

/lp user Steve info

Zobaczysz główną grupę, wagi, prefiksy, sufiksy, konteksty, pełną listę uprawnień.

/lp check

Szybki test pojedynczej nody:

/lp user Steve permission check essentials.fly
/lp user Steve permission check essentials.fly world=survival

Pokaże true albo false i skąd pochodzi uprawnienie (inherited from vip, explicit set, default node).

Częste błędy

Zmiany się nie stosują

Niemal zawsze cache. Po dużej edycji:

/lp sync

Albo z włączonym messagingiem, poczekaj kilka sekund.

Gracz przez pomyłkę w dwóch grupach

Jeśli zrobisz /lp user Steve parent set vip, a potem /lp user Steve parent add moderator, Steve ma dwóch parentów. set zastępuje, add dodaje. Kontrola przez /lp user Steve info.

Prefiks nie pokazuje się na czacie

LuckPerms tylko przechowuje. Renderowaniem zajmuje się EssentialsX Chat, VentureChat, DeluxeChat, TAB, HuskChat, ustaw format z {PREFIX} albo %luckperms_prefix%.

Wildcard nie działa

Niektóre pluginy (stare WorldEdit na przykład) nie rejestrują swoich nod w Bukkit permission API, więc worldedit.* ich nie łapie. Trzeba wtedy wpisać nody jawnie.

Konflikt z innymi pluginami uprawnień

PEX i LuckPerms razem nie działają. Usuń PermissionsEx.jar z plugins/ przed instalacją LuckPerms. Sprawdź:

/plugins

Powinien być tylko LuckPerms.

Utrata uprawnień po restarcie

Przy storage YAML crash podczas zapisu może zniszczyć dane. Dlatego poważne serwery unikają YAMLa, wybierają H2, SQLite lub MySQL.

Błąd SQLSTATE 28000 przy połączeniu z MySQL

Błędne dane logowania albo user bez praw do bazy. Sprawdź:

SELECT user, host FROM mysql.user WHERE user = 'luckperms';
SHOW GRANTS FOR 'luckperms'@'localhost';

User musi mieć ALL PRIVILEGES ON luckperms.*.

Bezpieczeństwo

Nie dawaj luckperms.* nikomu poza ownerem. Ta noda pozwala nadawać i odbierać dowolne uprawnienia, co praktycznie czyni gracza pełnym adminem. Moderatorom wystarczy luckperms.user.info i luckperms.user.parent.add bez luckperms.user.parent.set.

Zablokuj komendę op dla wszystkich poza ownerem:

/lp group default permission set minecraft.command.op false
/lp group admin permission set minecraft.command.op false
/lp group owner permission set minecraft.command.op true

W server.properties:

enable-command-block=false
op-permission-level=4

Gracze OP mają wszystkie prawa niezależnie od LuckPerms. Dlatego serwery produkcyjne nie używają /op, wszystko idzie przez grupy LuckPerms.

Wydajność

LuckPerms jest dobrze napisany i praktycznie nie wpływa na TPS. Na dużych serwerach (500+ graczy, tysiące nod) kilka optymalizacji ma sens:

• MySQL zamiast YAMLa, szybsze lookupy
• Nie zaśmiecaj uprawnień milionem negatywów, polegaj na czystym dziedziczeniu
• Cache domyślnie 60 sekund, odpowiednie dla większości workloadów

Statystyki:

/lp info

Na dole widać czas ostatniej synchronizacji i rozmiar cache.

Podsumowanie

LuckPerms to must-have dla każdego poważnego serwera Minecraft. Pięć minut instalacji, pół godziny na podstawowe grupy i dziedziczenie, potem dokładasz uprawnienia w miarę pojawiania się nowych pluginów. Edytor webowy oszczędza godziny przy masowych zmianach, konteksty pozwalają na złożone reguły per świat i per serwer, tracki czyszczą systemy rang i drabinki donatorskie.

Główna zasada: najpierw zbuduj drzewo grup z dziedziczeniem, potem dodawaj indywidualne uprawnienia graczom. Jeśli łapiesz się na tym, że nadajesz to samo prawo dziesięciu osobom ręcznie, zatrzymaj się i stwórz na to grupę. System pozostanie utrzymywalny nawet gdy serwer urośnie do setek graczy.