DiscordSRV: konfiguracja bota Discord dla serwera Minecraft

Discord dawno stał się drugim domem dla większości społeczności growych. Gracze siedzą tam nawet, gdy nie grają, więc sensowne jest, żeby chat serwera był dostępny z tego samego miejsca. DiscordSRV to najpopularniejszy plugin do połączenia Minecrafta z Discordem. Robi dwukierunkowy most czatu, kopiuje konsolę do kanału, synchronizuje role, wiąże konta i wysyła alerty o zdarzeniach serwera.

Ten przewodnik pokrywa całość: od stworzenia bota w Developer Portal po dostrajanie group sync i wiadomości webhook. Instrukcja dla Paper/Spigot/Purpur, ale większość stosuje się też do innych forków.

Co potrafi DiscordSRV

Główne funkcje, dla których się go instaluje:

• Most czatu: wiadomości z gry trafiają do kanału Discord i odwrotnie
• Kanał konsoli: konsola serwera jest kopiowana do prywatnego kanału, można uruchamiać polecenia z Discord
• Alerty: join/leave graczy, śmierć, osiągnięcia, start/stop serwera
• Powiązanie kont: połączenie nicku Minecraft z kontem Discord przez kod
• Group sync: grupy LuckPerms automatycznie mapują się na role Discord i z powrotem
• Wiadomości webhook: wiadomości z gry pojawiają się w Discord z avatarem głowy gracza, nie jako bot
• Addon API: wiele pluginów rozszerza DiscordSRV (reakcje jako emoji, chat per kanał, moderacja)

Alternatywy

Krótko o konkurentach, żebyś nie zgadywał.

• DiscordIntegrator - prostszy, lżejszy, bez group sync i konsoli. Ok, jeśli potrzebujesz tylko podstawowego mostu czatu
• EssentialsDiscord - część EssentialsX, podłączone do jej ekosystemu. Brak group sync, ograniczone funkcje
• DiscordChat - minimalny, tylko czat
• UltimateChat z dodatkiem Discord - płatny, dopracowany, dla większości overkill

DiscordSRV jest faktycznym standardem. Żywa społeczność, regularne aktualizacje, obsługuje wszystkie aktualne wersje Minecraft od 1.8 do 1.21+. Reszta tego przewodnika ustawia właśnie jego.

Instalacja pluginu

1. Otwórz stronę pluginu na SpigotMC lub GitHub Releases
2. Pobierz najnowszy .jar pod twoją wersję Minecraft
3. Wrzuć plik do folderu plugins/ serwera
4. Zrestartuj serwer (pełny restart, nie reload)

Po starcie pojawi się plugins/DiscordSRV/ z configami: config.yml, messages.yml, alerts.yml, synchronization.yml, linking.yml. Na razie nie ruszaj, najpierw bot.

Sprawdź, czy plugin się załadował:

/plugins

DiscordSRV powinien być zielony. Czerwony to znak, żeby zajrzeć do konsoli. Zwykle niezgodność wersji Javy lub Minecraft.

Tworzenie bota Discord

Krok 1: aplikacja

1. Otwórz Discord Developer Portal
2. Kliknij New Application w prawym górnym rogu
3. Wpisz nazwę (np. MyServer Bot) i zaakceptuj warunki
4. W zakładce General Information możesz ustawić ikonę i opis. To zobaczą gracze w Discord

Krok 2: utwórz bota

1. W lewym menu wybierz Bot
2. Kliknij Add Bot -> Yes, do it!
3. Ustaw nick i avatar bota (niezależne od nazwy aplikacji)

Krok 3: pobierz token

Na tej samej stronie Bot kliknij Reset Token -> Yes, do it!. Zobaczysz coś takiego:

MTIzNDU2Nzg5MDEyMzQ1Njc4.Xy7Z_A.abcdefghijklmnopqrstuvwxyz

Skopiuj go od razu. Discord nie pokazuje tokenu ponownie, tylko pozwala zresetować. Nie publikuj tokenu, nie wrzucaj do gita, nie pokazuj na screenshotach. Jeśli wyciekł, natychmiast zresetuj na tej samej stronie.

Krok 4: privileged intents

Krytyczny krok. Bez niego bot nie widzi wiadomości użytkowników.

Na stronie Bot znajdź Privileged Gateway Intents i włącz:

• PRESENCE INTENT (opcjonalnie, dla statusów)
• SERVER MEMBERS INTENT (wymagane dla group sync)
• MESSAGE CONTENT INTENT (wymagane dla czatu)

Kliknij Save Changes.

Krok 5: zaproś bota

1. Przejdź do OAuth2 -> URL Generator
2. W Scopes zaznacz: bot, applications.commands
3. W Bot Permissions minimum:
   • View Channels
   • Send Messages
   • Embed Links
   • Attach Files
   • Read Message History
   • Manage Messages (dla edycji/usuwania)
   • Manage Roles (dla group sync)
   • Manage Webhooks (dla wiadomości z avatarami)
   • Add Reactions
4. Skopiuj wygenerowany URL na dole
5. Otwórz URL w przeglądarce, wybierz swój serwer Discord, potwierdź

Bot pojawi się na liście członków, ale jeszcze offline.

Pobieranie ID kanałów i guild

DiscordSRV pracuje z numerycznymi ID, nie nazwami. Żeby je dostać, włącz Developer Mode w kliencie Discord:

1. User Settings -> Advanced -> Developer Mode: On
2. Prawy klik na serwer (guild) -> Copy Server ID - to ID guildu
3. Prawy klik na kanał -> Copy Channel ID - to ID kanału

ID wyglądają tak: 948273194820394820. Zapisz ID kanałów, których użyjesz: #minecraft-chat (globalny chat), #console (jeśli kopiujesz konsolę), #server-events (dla alertów).

Konfiguracja DiscordSRV

Otwórz plugins/DiscordSRV/config.yml. Najważniejsze parametry:

BotToken

BotToken: "MTIzNDU2Nzg5MDEyMzQ1Njc4.Xy7Z_A.abcdefghijklmnopqrstuvwxyz"

Wklej token z Developer Portal. Bez niego bot się nie uruchomi.

Channels

Tu mapujesz kanały in-game DiscordSRV na kanały Discord. global to domyślny dla ogólnego czatu.

Channels:
  global: "948273194820394820"
  staff: "948273194820394821"

Lewa wartość (global, staff) to nazwa kanału w DiscordSRV, prawa to ID kanału Discord. Kilka kanałów pozwala rozdzielić chat staff od publicznego.

Kanał konsoli

Osobna sekcja na kopiowanie konsoli:

DiscordConsoleChannelId: "948273194820394822"
DiscordConsoleChannelUsageLog: true
DiscordConsoleChannelBlacklistedCommands:
  - "?"
  - "op"
  - "deop"
  - "stop"

Kanał musi być prywatny i dostępny tylko dla adminów. Każdy, kto może pisać w kanale, może wykonywać polecenia na serwerze.

MinecraftChatToDiscordMessageFormat

Format wiadomości z Minecrafta do Discord, edytujesz w messages.yml:

MinecraftChatToDiscordMessage:
  Content: "%message%"
  Webhook:
    Enable: true
    AvatarUrl: "https://mc-heads.net/avatar/%uuid%/128"
    Username: "%username%"

Tryb webhook sprawia, że wiadomości wyglądają jak normalne wiadomości Discord: z avatarem głowy gracza i jego nickiem, zamiast postowania jako bot. Polecany.

DiscordChatChannelMinecraftMessage

Format dla odwrotnego kierunku: z Discord do Minecrafta.

DiscordToMinecraftChatMessageFormat: "&b[Discord] &r<%username%> %message%"
DiscordToMinecraftChatMessageFormatNoPrimaryGroup: "&b[Discord] &r<%username%> %message%"

Kolory przez &-kody. %username% to nick Discord, %message% to treść wiadomości.

Minimalny działający config.yml:

BotToken: "YOUR_TOKEN_HERE"

Channels:
  global: "948273194820394820"

DiscordConsoleChannelId: "948273194820394822"
DiscordConsoleChannelUsageLog: true

DiscordChatChannelPrefixRequiredToProcessMessage: ""

MinecraftDiscordAccountLinkedConsoleCommands:
  - "lp user %player% parent add verified"

MinecraftDiscordAccountUnlinkedConsoleCommands:
  - "lp user %player% parent remove verified"

Zapisz, w grze wykonaj /discord reload, plugin podchwyci zmiany bez restartu serwera.

Powiązanie kont

Żeby DiscordSRV wiedział, który użytkownik Discord to który gracz, potrzebuje powiązania. Bez tego group sync i osobiste avatary nie działają.

Proces powiązania

1. Gracz wpisuje /discord link w Minecraft
2. Plugin zwraca 4-cyfrowy kod, np. 4829
3. Gracz wysyła botowi w Discord przez DM: link 4829
4. Bot odpowiada potwierdzeniem, powiązanie zapisane

Kod jednorazowy, wygasa (15 minut domyślnie). Rozłączenie: /discord unlink w grze lub unlink przez DM.

Auto-rola przy powiązaniu

linking.yml konfiguruje auto-nadawanie ról:

MinecraftDiscordAccountLinkedRoleNameToAddUserTo: "Verified"
MinecraftDiscordAccountLinkedConsoleCommands:
  - "lp user %player% parent add verified"
  - "say %player% powiazal Discord!"

Gracz dostanie rolę Verified w Discord i grupę verified w LuckPerms zaraz po powiązaniu. Wygodne, żeby oddzielić zweryfikowanych od losowych.

Wymuszenie powiązania

Można zablokować wejście na serwer dla niepowiązanych. W config.yml:

Require linked account to play:
  Enabled: true
  Subtract from online count: true
  Kick message: "Powiaz Discord: /discord link | Invite: discord.gg/twojserwer"
  Whitelisted players bypass check: true

Tylko powiązani wchodzą. Gracze z whitelisty mogą omijać.

Group sync

Jedna z najużyteczniejszych funkcji. Konfigurowana w synchronization.yml.

GroupRoleSynchronizationGroupsAndRolesToSync:
  "admin": "948273194820394830"
  "moderator": "948273194820394831"
  "vip": "948273194820394832"
  "donator": "948273194820394833"
  "member": "948273194820394834"

GroupRoleSynchronizationOneWay: false
GroupRoleSynchronizationCycleTime: 10

Po lewej grupa LuckPerms (lub permission), po prawej ID roli Discord. Domyślnie sync jest dwukierunkowy: dostałeś admina w LuckPerms, dostałeś @Admin w Discord i odwrotnie.

OneWay: true każe DiscordSRV tylko czytać z Minecrafta i pisać do Discord, bez dotykania LuckPerms w drugą stronę. Bezpieczniej, jeśli nie chcesz, żeby ktoś z uprawnieniami Discord przypadkiem dostał uprawnienia na serwerze.

CycleTime: 10 to interwał w minutach dla przeliczania sync. Dodatkowo triggeruje się na zdarzenia (join, zmiana roli).

Hierarchia ról

Bot może nadawać tylko role, które są pod jego własną w hierarchii Discord. W ustawieniach serwera Discord przeciągnij rolę bota ponad wszystkie synchronizowane role. Inaczej dostaniesz Missing Permissions w konsoli.

Alerty

Plik alerts.yml. Pozwala wysłać dowolne zdarzenie serwera jako custom wiadomość do kanału.

Alerts:
  - Trigger: "PlayerJoinEvent"
    Async: true
    Channel: "server-events"
    Content: ":green_circle: **%player%** dolaczyl do serwera"

  - Trigger: "PlayerDeathEvent"
    Async: true
    Channel: "server-events"
    Content: ":skull: %player% zginal: `%event.deathMessage%`"

  - Trigger: "PlayerAdvancementDoneEvent"
    Async: true
    Conditions:
      - "event.advancement.display != null"
    Channel: "server-events"
    Content: ":trophy: **%player%** zdobyl **%event.advancement.display.title%**"

Triggery to dowolne zdarzenia Bukkit. Conditions pozwalają filtrować, np. pomijać ukryte osiągnięcia.

Dla zdarzeń serwera (start, stop, crash) są wbudowane w config.yml:

DiscordChatChannelServerStartupMessage: ":green_circle: Serwer uruchomiony"
DiscordChatChannelServerShutdownMessage: ":red_circle: Serwer zatrzymany"

Wiadomości webhook dla lepszego wyglądu

Jeśli włączysz w messages.yml:

MinecraftChatToDiscordMessage:
  Webhook:
    Enable: true
    AvatarUrl: "https://mc-heads.net/avatar/%uuid%/128"
    Username: "%username%"

Wiadomości z gry pokażą się jako osobni "użytkownicy" w Discord, każdy z własnym avatarem, głową Minecraft gracza. Wizualnie dużo lepiej niż bot wrzucający wszystko pod jednym imieniem.

Ważne: bot potrzebuje Manage Webhooks w kanale, inaczej nic nie działa. Discord ogranicza też liczbę wiadomości webhook na minutę. Na małym serwerze ok, przy 100+ online można trafić na limity. Wtedy wyłącz webhook lub rób batching.

Whitelist przez Discord

Można powiązać wejście na serwer z rolą Discord. Np. rola @Member ma dawać whitelist.

Przez group sync: mapuj @Member na grupę whitelisted w LuckPerms, która ma essentials.whitelist.bypass, albo dodawaj do whitelist.json przez custom polecenia:

MinecraftDiscordAccountLinkedConsoleCommands:
  - "whitelist add %player%"

MinecraftDiscordAccountUnlinkedConsoleCommands:
  - "whitelist remove %player%"

Albo napisz własny alert na RoleAddEvent DiscordSRV API przez plugin-dodatek. Dla większości serwerów starczy prosta kombinacja group sync.

Troubleshooting

"No such channel" przy starcie

Plugin loguje Could not find Discord channel by ID.... Przyczyny:

• ID kanału skopiowane źle (spacje, litery zamiast cyfr)
• Bot nie zaproszony na serwer, na którym jest kanał
• Bot nie ma uprawnienia View Channel
• Kanał to kategoria lub voice, a DiscordSRV oczekuje tekstowego

Sprawdź: ustawienia kanału Discord -> Permissions, znajdź rolę bota, włącz View Channel.

"Missing Permissions" przy nadawaniu ról

WARN: Tried to assign role but lacks permissions

Dwie przyczyny:

1. Rola bota w hierarchii Discord niższa niż rola nadawana. Fix: przeciągnij rolę bota w Server -> Roles
2. Bot nie ma Manage Roles. Fix: Server Settings -> Roles -> rola bota -> włącz Manage Roles

Wiadomości nie idą z Minecrafta do Discord

• Sprawdź, czy global w Channels: ma właściwe ID
• Sprawdź, czy bot jest online (/discord w grze pokazuje status)
• Zajrzyj do konsoli serwera na błędy JDA (biblioteka używana przez DiscordSRV)

Wiadomości nie idą z Discord do Minecrafta

Prawie zawsze: Message Content Intent nie jest włączone w Developer Portal. Polityka Discord od 2022, bez tego intentu bot nie widzi treści. Włącz, zrestartuj serwer, sprawdź ponownie.

Webhook-i nie działają

• Bot nie ma Manage Webhooks w kanale
• Osiągnięty limit Discord (10 webhooków na kanał)
• Proxy/CDN blokuje wychodzące zapytania webhook z serwera Minecraft

Bot utknął na "Connecting..."

• Token zły lub zresetowany, wygeneruj nowy
• Token ma spacje lub nową linię
• Hosting blokuje połączenia wychodzące do gateway.discord.gg

Group sync działa tylko w jedną stronę

Sprawdź GroupRoleSynchronizationOneWay. Przy true sync idzie tylko MC -> Discord. Ustaw false dla dwukierunkowego.

Sprawdź też, czy grupy LuckPerms istnieją (/lp group <name> info).

Bezpieczeństwo i dobre praktyki

1. Kanał konsoli tylko dla adminów. Każdy, kto może tam pisać, może wykonywać polecenia na serwerze. Dawaj dostęp tylko zaufanym
2. Backup tokenu w menedżerze haseł. Przy wycieku natychmiast resetuj
3. Osobne kanały według roli: #minecraft-chat publiczny, #staff-chat prywatny do moderacji, #server-events na alerty, #console dla adminów
4. Unikaj webhook dla czatu przy 200+ online. Limity webhook Discorda zaczynają zawodzić
5. Rola bota nad rolami sync. Oszczędza godziny debugowania
6. Alerty z umiarem. Kanał z 100 alertów na minutę nikt nie czyta
7. Aktualizuj DiscordSRV. Discord zmienia API regularnie, stare wersje dryfują

Lista kontrolna na koniec

• Plugin DiscordSRV w plugins/, serwer uruchomiony, plugin zielony
• Bot utworzony w Developer Portal, token zapisany
• Trzy privileged intents aktywne (SERVER_MEMBERS, MESSAGE_CONTENT, PRESENCE)
• Bot zaproszony przez URL OAuth2 z odpowiednimi uprawnieniami
• Developer Mode włączony, ID kanałów skopiowane
• config.yml ma BotToken, Channels, DiscordConsoleChannelId wypełnione
• synchronization.yml ustawione dla group sync (jeśli trzeba)
• Rola bota nad wszystkimi rolami sync w hierarchii Discord
• Kanał konsoli prywatny
• Powiązanie konta przetestowane przez /discord link
• Wiadomości idą w obie strony

Jeśli wszystkie punkty są zaznaczone, DiscordSRV jest gotowy na produkcję. Dalej można dokładać dodatki: DiscordSRV-Reactions na emoji w grze, DiscordSRV-Voice na wyświetlanie kanałów głosowych, SRVLinker na rozszerzone wiązanie, i zamienić serwer w pełny ekosystem.