DiscordSRV - integracja Discord z serwerem Minecraft

Co to jest DiscordSRV

DiscordSRV to darmowy plugin open-source, który tworzy dwukierunkowy most między serwerem Minecraft a serwerem Discord. Napisany przez Scarsza i rozwijany od 2016 roku, zdobył ponad 130 000 pobrań na SpigotMC i jest de facto standardem integracji Minecraft-Discord w polskiej i globalnej społeczności serwerowej.

Główne możliwości pluginu:

• Synchronizacja czatu w czasie rzeczywistym - wiadomości z gry pojawiają się na Discordzie i odwrotnie
• Łączenie kont - gracze łączą konto Minecraft z kontem Discord jedną komendą
• Powiadomienia o zdarzeniach - dołączenie, wyjście, śmierć, zdobycie achievementu, awans
• Kanał konsoli - admini mogą wysyłać komendy na serwer bezpośrednio z Discorda
• Synchronizacja rang - role Discord synchronizują się z grupami LuckPerms w obie strony
• Webhooki z avatarami - wiadomości wyglądają jak prawdziwe profile graczy na Discordzie
• Kanały głosowe (DiscordSRV-Addon-VoiceModule) - gracze w kanale głosowym widzą się na minimapie

Plugin jest dostępny na SpigotMC i GitHubie. Oficjalna dokumentacja znajduje się pod adresem docs.discordsrv.com. DiscordSRV obsługuje wersje Minecraft od 1.7.10 do 1.21.x.

Tworzenie bota Discord

Zanim zainstalujesz plugin, musisz mieć własnego bota Discord. DiscordSRV nie korzysta ze wspólnego, publicznego bota - każdy serwer musi stworzyć własną aplikację. Zajmuje to ok. 5 minut.

1. Wejdź na discord.com/developers/applications i zaloguj się.
2. Kliknij New Application, nadaj botowi nazwę (np. nazwa twojego serwera MC) i potwierdź.
3. Przejdź do zakładki Bot, kliknij Add Bot, potwierdź.
4. Pod sekcją Privileged Gateway Intents włącz Server Members Intent i Message Content Intent. Bez nich bot nie odczyta wiadomości ani listy członków.
5. Kliknij Reset Token, skopiuj token i zapisz go w bezpiecznym miejscu - będziesz go potrzebować w konfiguracji pluginu.
6. Przejdź do zakładki OAuth2 → URL Generator. Zaznacz scope bot, a w uprawnieniach bota zaznacz co najmniej: Send Messages, Manage Messages, Read Message History, View Channels, Manage Webhooks.
7. Skopiuj wygenerowany URL, otwórz go w przeglądarce i zaproś bota na swój serwer Discord.

Zapamiętaj też ID kanałów, których będzie używał bot (czat, konsola). ID kanału kopiujesz prawym klikiem na kanał → Kopiuj ID (musisz mieć włączony tryb deweloperski w ustawieniach Discorda: Ustawienia → Zaawansowane → Tryb dewelopera).

Instalacja i pierwsza konfiguracja

Pobierz plik DiscordSRV-Build-X.XX.jar ze SpigotMC lub GitHuba i wrzuć go do folderu plugins/ na serwerze. Uruchom serwer - plugin wygeneruje domyślne pliki konfiguracyjne w plugins/DiscordSRV/.

Zatrzymaj serwer i otwórz plik plugins/DiscordSRV/config.yml. Pierwsze kroki konfiguracji:

# Token bota Discord - wklej ten, który skopiowałeś z panelu deweloperskiego
BotToken: "TUTAJ_WKLEJ_TOKEN_BOTA"

# ID kanału Discord, na który trafia chat z serwera
Channels:
  global: "123456789012345678"

# ID kanału konsoli (opcjonalne, ale bardzo przydatne dla adminów)
DiscordConsoleChannelId: "123456789012345679"

Po uzupełnieniu tokenu i ID kanałów uruchom serwer. W logach zobaczysz komunikat [DiscordSRV] Successfully logged in as BotName#1234 jeśli połączenie zadziałało. Jeśli pojawi się błąd Invalid token, sprawdź czy token nie zawiera spacji i czy nie zresetowałeś go ponownie po skopiowaniu.

Pliki konfiguracyjne DiscordSRV:

• config.yml - główna konfiguracja: token, kanały, synchronizacja rang, opcje chatu
• messages.yml - treść wszystkich wiadomości wysyłanych przez bota (join, quit, death itp.)
• linking.yml - ustawienia systemu łączenia kont
• synchronization.yml - mapowanie grup LuckPerms na role Discord
• voice.yml - konfiguracja modułu głosowego (jeśli zainstalowany)

Synchronizacja czatu (MC ↔ Discord)

To podstawowa i najczęściej używana funkcja DiscordSRV. Każda wiadomość napisana na serwerze pojawia się na wyznaczonym kanale Discord i odwrotnie - wiadomości z Discorda trafiają do chatu w grze.

Domyślny format wiadomości z Minecraft na Discord (w trybie webhook):

# Wiadomość z MC na Discord
MinecraftToDiscordMessageFormat: "%displayname%: %message%"

# Wiadomość z Discord na MC (widoczna dla graczy w grze)
DiscordToMinecraftChatChannelGameMessage: "[Discord] %toprolecolor%%toprolealias%&r %name%&r » %message%"

W placeholderach możesz użyć:

• %displayname% - wyświetlana nazwa gracza (z prefixem rangi jeśli zainstalowany EssentialsX Chat lub CMI)
• %username% - czysta nazwa gracza bez formatowania
• %message% - treść wiadomości
• %world% - nazwa świata, w którym znajduje się gracz
• %toprolecolor% - kolor najwyższej roli Discord gracza
• %toprolealias% - alias (skrót) najwyższej roli Discord

Możesz skonfigurować wiele kanałów czatu - na przykład osobny kanał globalny i osobny dla świata PvP:

Channels:
  global: "ID_KANALU_GLOBALNEGO"
  pvp: "ID_KANALU_PVP"

Kanały mapuje się na światy lub pluginy czatu w sekcji ChannelTopicUpdaterChatChannelTopicFormat. DiscordSRV obsługuje też PlaceholderAPI - możesz użyć dowolnego placeholdera w formatach wiadomości, o ile masz zainstalowany PAPI i odpowiednie rozszerzenie.

Łączenie kont (Account Linking)

Account Linking to funkcja pozwalająca graczom powiązać swoje konto Minecraft z kontem Discord. Po połączeniu DiscordSRV może synchronizować rangi, wyświetlać awatary w webhookach i weryfikować graczy na Discordzie.

Proces łączenia kont z perspektywy gracza:

1. Gracz wpisuje na serwerze komendę /discord link.
2. Serwer generuje unikalny kod (np. 15A3F2) i wysyła go graczowi w wiadomości prywatnej.
3. Gracz otwiera DM z botem Discord i wysyła ten kod.
4. Bot potwierdza połączenie i opcjonalnie nadaje rolę weryfikacji na Discordzie.

Konfiguracja Account Linking w config.yml:

# Wymagaj połączenia konta przed wejściem na serwer
MinecraftDiscordAccountLinkedConsoleCommandsOnLink: ""

# Czy niezweryfikowani gracze mogą pisać na czacie
DiscordToMinecraftAllowedLinks: true

# Rola nadawana po połączeniu konta
MinecraftDiscordAccountLinkedRoleNameToAddUserTo: "Zweryfikowany"

# Wyrzucenie z Discorda przy banie na serwerze (opcjonalne)
BanSyncKickFromDiscord: false

Możesz wymagać weryfikacji jako obowiązkowy krok przed dołączeniem na serwer. W tym przypadku niezweryfikowani gracze dostają się na specjalny lobby-świat z informacją jak się zweryfikować. To popularne rozwiązanie na serwerach z aktywną społecznością Discord - eliminuje boty i zwiększa zaangażowanie.

Powiązane konta są zapisywane w bazie danych H2 (domyślnie plik linkedaccounts.json). DiscordSRV obsługuje też MySQL/MariaDB dla środowisk wieloserwerowych (sieć BungeeCord/Velocity).

Komendy z Discorda

Admini mogą wykonywać komendy serwera bezpośrednio z kanału konsoli na Discordzie. To ogromna wygoda - nie musisz się logować na SSH ani otwierać panelu serwera, żeby na przykład ukarać gracza czy zmienić czas w grze.

Konfiguracja kanału konsoli:

# ID kanału, który pełni rolę konsoli
DiscordConsoleChannelId: "TWOJE_ID_KANALU_KONSOLI"

# Czy zezwolić na wykonywanie komend z Discorda
DiscordConsoleChannelCommandsEnabled: true

# Lista dozwolonych komend (puste = wszystkie)
DiscordConsoleChannelBlacklist: []

# Lista zablokowanych komend (dla bezpieczeństwa)
DiscordConsoleChannelBlacklist:
  - "stop"
  - "restart"

Dostęp do kanału konsoli powinien być ograniczony wyłącznie do administratorów serwera Discord. Jeśli nieupoważniona osoba uzyska dostęp do tego kanału, może wykonać dowolną komendę na serwerze z uprawnieniami OP. Zawsze ustaw odpowiednie uprawnienia na kanale Discord.

DiscordSRV wysyła też na kanał konsoli logi serwera w czasie rzeczywistym, filtrowane przez konfigurowalny regex. Możesz wybrać, które poziomy logowania (INFO, WARN, ERROR) mają trafiać na Discord.

Komendy dla graczy dostępne w grze:

Powiadomienia (join, leave, śmierć, achievementy)

DiscordSRV automatycznie wysyła powiadomienia o kluczowych zdarzeniach na serwer Discord. Wszystkie treści wiadomości edytujesz w pliku messages.yml.

Dostępne typy powiadomień i ich domyślne formaty:

# Gracz dołączył do serwera
PlayerJoinMessage: "**%displayname%** dołączył(a) do serwera :green_circle:"

# Gracz opuścił serwer
PlayerLeaveMessage: "**%displayname%** opuścił(a) serwer :red_circle:"

# Gracz zginął
PlayerDeathMessage: "**%displayname%** %deathmessage% :skull:"

# Gracz zdobył achievement
PlayerAchievementMessage: "**%displayname%** zdobył(a) osiągnięcie **%achievement%** :trophy:"

# Serwer się uruchomił
ServerStartMessage: ":white_check_mark: Serwer uruchomiony!"

# Serwer się zatrzymał
ServerStopMessage: ":octagonal_sign: Serwer zatrzymany."

W wiadomościach możesz używać standardowego formatowania Markdownowego Discorda: **pogrubienie**, *kursywa*, ~~przekreślenie~~, `kod`. Emojis wstawiasz przez ich nazwę w dwukropkach (:sword:) lub bezpośrednio jako Unicode.

Powiadomienia możesz też wysyłać jako embed Discorda zamiast zwykłej wiadomości. Embedy wyglądają bardziej profesjonalnie i obsługują pola, kolor paska bocznego, miniaturę i footer. Konfiguracja embeda w messages.yml:

PlayerJoinMessage:
  Embed: true
  Embeds:
    - Color: "#00AA00"
      Title: ":green_circle: %displayname% dołączył(a)!"
      Thumbnail:
        Url: "https://mc-heads.net/avatar/%username%/100"

Webhook vs tryb botowy

DiscordSRV może wysyłać wiadomości czatu na dwa sposoby: jako bot lub przez webhook. Różnica jest znacząca wizualnie i funkcjonalnie.

Tryb botowy (domyślny): Wszystkie wiadomości pojawiają się jako jedna wiadomość od bota, z jego nazwą i avatarem. Prosto w konfiguracji, ale wizualnie nieeleganckie - każda wiadomość wygląda tak samo, bez rozróżnienia kto ją napisał.

Tryb webhook: Każda wiadomość pojawia się z nazwą i avatarem konkretnego gracza. Wygląda jakby gracze sami pisali na Discordzie. Dużo lepsze wrażenia dla społeczności, ale wymaga dodatkowej konfiguracji webhooka na kanale.

Włączenie trybu webhook:

# Ustaw na true aby używać webhooków zamiast bota
Experiment_WebhookChatMessageDelivery: true

# Nazwa webhooka wyświetlana jako nadawca (placeholdery działają)
Experiment_WebhookChatMessageUsernameFormat: "%displayname%"

# URL avatara gracza (mc-heads.net lub crafatar.com)
Experiment_WebhookChatMessageAvatarUrl: "https://crafatar.com/avatars/%uuid%?overlay"

Webhook tworzysz w ustawieniach kanału Discord: Edytuj kanał → Integracje → Webhooki → Nowy webhook. Skopiuj URL webhooka i wklej go do konfiguracji DiscordSRV pod kluczem Channels:

Channels:
  global:
    id: "ID_KANALU"
    webhook: "TUTAJ_WKLEJ_URL_WEBHOOKA"

Zalecam tryb webhook dla każdego serwera z aktywną społecznością. Gracze chętniej korzystają z Discorda gdy widzą własne avatary i nazwy, a nie generyczny bot.

Konfiguracja zaawansowana

Synchronizacja rang z LuckPerms

DiscordSRV potrafi synchronizować role Discord z grupami LuckPerms w obie strony. Gracz dostający rolę VIP na Discordzie automatycznie otrzymuje grupę VIP w grze i odwrotnie. Konfiguracja w synchronization.yml:

GroupSynchronizationRoles:
  # Format: "ID_ROLI_DISCORD": "NAZWA_GRUPY_LUCKPERMS"
  "123456789012345678": "vip"
  "123456789012345679": "svip"
  "123456789012345680": "admin"

# Synchronizacja z Discord do MC
GroupSynchronizationPrimaryGroupOnly: false

# Synchronizacja z MC do Discord
GroupSynchronizationSyncDirection: bidirectional

Synchronizacja rang wymaga połączonego konta gracza (Account Linking). Bez połączonego konta DiscordSRV nie wie, któremu graczowi w grze odpowiada dana osoba na Discordzie.

Temat kanału z informacjami o serwerze

DiscordSRV może automatycznie aktualizować temat kanału Discord z informacjami o serwerze w czasie rzeczywistym:

ChannelTopicUpdaterChatChannelTopicFormat: "Gracze online: %playercount%/%playermax% | TPS: %tps% | Wersja: %version%"

# Jak często aktualizować temat (w minutach)
ChannelTopicUpdaterRateInMinutes: 5

Filtrowanie wiadomości

Możesz blokować wiadomości z MC na Discord zawierające określone frazy lub pasujące do regex:

# Wiadomości zawierające te frazy NIE trafią na Discord
DiscordChatChannelGameFilters:
  - "[Vault]"
  - "Server is running"

# Regex filtr (blokuje komendy zaczynające się od /)
DiscordChatChannelGameRegexFilters:
  - "^/.*"

Obsługa wielu serwerów (BungeeCord/Velocity)

W sieci BungeeCord/Velocity instalujesz DiscordSRV na każdym serwerze-dziecku osobno. Możesz skonfigurować każdy serwer na inny kanał Discord lub na ten sam kanał z prefiksem nazwy serwera w wiadomości. Zalecane jest użycie wspólnej bazy MySQL dla Account Linking, żeby gracze nie musieli się weryfikować oddzielnie na każdym serwerze:

HikariPoolConfig:
  JdbcUrl: "jdbc:mysql://localhost:3306/discordsrv"
  Username: "minecraft"
  Password: "haslo"
  MaximumPoolSize: 20

PlaceholderAPI

DiscordSRV w pełni obsługuje PlaceholderAPI. W każdym formacie wiadomości możesz użyć dowolnego placeholdera PAPI, na przykład %luckperms_prefix% do wyświetlania prefixa rangi lub %player_health% do pokazywania HP gracza. To otwiera ogromne możliwości personalizacji wiadomości bez modyfikowania kodu pluginu.

Kompatybilność

DiscordSRV jest kompatybilny z szerokim ekosystemem pluginów:

Obsługiwane platformy serwerowe:

• Paper (zalecane) - pełna kompatybilność, najlepsza wydajność
• Spigot - pełna kompatybilność
• Purpur - pełna kompatybilność
• Mohist / Arclight (hybryd Forge+Bukkit) - działa, ale może wymagać dodatkowej konfiguracji
• Forge / Fabric standalone - NIE obsługiwane. DiscordSRV to plugin Bukkit/Spigot, nie mod

DiscordSRV wymaga Javy 11 lub nowszej. Na serwerach Paper 1.21.x wymagana jest Java 21. Plugin nie ma żadnych zależności które muszą być zainstalowane - wszystko co potrzebuje jest wbudowane w plik .jar. LuckPerms i PlaceholderAPI są opcjonalne, ale mocno zalecane dla pełnych możliwości.

Więcej informacji o pluginach serwerowych znajdziesz w katalogu pluginów.