DiscordSRV fuer SMP: erweiterte Konfiguration, Role Sync und Event-Automatisierung

Eine einfache Chat-Bruecke mit DiscordSRV ist in zehn Minuten eingerichtet, und dort hoeren die meisten Admins auf. In diesem Guide gehen wir weiter: Role Sync mit LuckPerms, Account Linking via /link, eigene Channels fuer Tode und Achievements, Console-Channel, Voice-Integration und Tuning fuer 200+ Spieler gleichzeitig.

Was wir voraussetzen

Vor dem Advanced-Teil setzen wir voraus, dass die Basis-Bruecke laeuft. Falls nicht, kurz: erstellt eine Discord-Application im Developer Portal, aktiviert die drei privileged Intents (PRESENCE, SERVER MEMBERS, MESSAGE CONTENT), traegt das Token in plugins/DiscordSRV/config.yml unter BotToken ein und ladet den Bot fuers Testen mit Administrator-Rechten ein. Nach einem Restart sollte /discord im Chat die Verbindung bestaetigen.

Dieser Guide bezieht sich auf DiscordSRV 1.27.x unter Paper 1.20-1.21, LuckPerms 5.4+ und Java 21. Folia wird nur teilweise unterstuetzt, dazu mehr im FAQ.

Group Sync: LuckPerms-Gruppen mit Discord-Rollen verbinden

Ziel: ein Spieler spendet ueber Discord, der Bot fuegt ihn automatisch der Gruppe vip auf dem Server hinzu. Oder umgekehrt: der Admin vergibt einen Rang in LuckPerms, Discord setzt automatisch die passende Rolle.

Datei plugins/DiscordSRV/synchronization.yml:

GroupRoleSynchronizationGroupsAndRolesToSync:
  "vip": "987654321098765432"
  "donator": "987654321098765433"
  "moderator": "987654321098765434"
  "admin": "987654321098765435"
  "default": "987654321098765436"

GroupRoleSynchronizationCycleTime: 5
GroupRoleSynchronizationOnLink: true
GroupRoleSynchronizationOneWay: false
GroupRoleSynchronizationMinecraftIsAuthoritative: true
GroupRoleSynchronizationPrimaryGroupOnly: false
GroupRoleSynchronizationEnableDenyPermission: true

Numerische Rollen-IDs holt ihr per Rechtsklick auf die Rolle in Discord, sofern Developer Mode aktiviert ist. Der Name links in Anfuehrungszeichen muss exakt der LuckPerms-Gruppe entsprechen, wie sie in /lp group <name> info erscheint.

Wichtige Felder. GroupRoleSynchronizationCycleTime ist das Auto-Sync-Intervall in Minuten, 5 ist ein vernuenftiger Default. OneWay: false aktiviert die bidirektionale Synchronisation: Rolle in Discord vergeben, LP-Gruppe wird ergaenzt, und umgekehrt. MinecraftIsAuthoritative entscheidet bei Konflikten: fehlt die LP-Gruppe und die Discord-Rolle ist gesetzt, entfernt der Bot die Rolle (weil Minecraft autoritativ ist).

Bei einem Donation-Server stellt man oft OneWay: true und MinecraftIsAuthoritative: false ein, weil Kaeufe ueber einen Discord-Bot wie Tebex oder MineStore laufen und die Rolle dort zuerst ankommt.

Damit Sync funktioniert, braucht der Bot die Berechtigung Manage Roles, und seine eigene Rolle muss in der Hierarchie ueber allen Rollen liegen, die er verwaltet. Das ist der haeufigste Fehler: der Bot vergibt @Admin nicht, weil @DiscordSRV unterhalb von @Admin in der Rollenliste steht.

Account Linking: /link aus dem Spiel

Ohne Account Linking kann Role Sync nichts ausrichten, der Bot weiss nicht, welcher Spieler welchem Discord-User entspricht. Standardmaessig schreibt der Spieler /discord link im Chat, der Bot schickt per DM einen sechsstelligen Code, der Spieler fuegt ihn in einen #verification-Channel ein oder schickt ihn an den Bot per DM.

Channels-Block in config.yml:

Channels:
  global: "987654321111111111"
  verification: "987654321222222222"
  console: "987654321333333333"
  deaths: "987654321444444444"
  achievements: "987654321555555555"

Anschliessend in linking.yml die Anforderungen anpassen:

RequireLinkedAccountToPlay: true
RequireLinkedAccountToPlayMessage: "&cVerlinke zuerst Discord: /discord link"
DiscordRequiredRoleToJoin: "987654321666666666"
SendCodeAsDirectMessage: true
ConfirmCodeInPublicChannel: false

Auf einem Donation-SMP oder Whitelist-Server sperrt RequireLinkedAccountToPlay: true Alts effektiv aus: jeder Minecraft-Account muss mit einem Discord-Account verbunden sein, ein Discord-User entspricht in der Regel einem Link. DiscordRequiredRoleToJoin geht weiter: nur Discord-User mit einer bestimmten Rolle koennen ueberhaupt joinen, etwa nur jene, die im Rules-Channel bestaetigt haben.

Channel Routing: Welten in eigene Channels

Auf einem SMP mit Welten wie world, world_resource, creative_plots wird ein einziger Discord-Channel fuer alles schnell unleserlich. Out of the box routet DiscordSRV alles in global. In Verbindung mit VentureChat oder ChatControl lassen sich Channels an einzelne Welten oder Chat-Praefixe binden.

Beispiel mit VentureChat. In plugins/VentureChat/channels.yml existieren die Channels Global, Local, Resources. In plugins/DiscordSRV/config.yml:

Channels:
  global: "987654321111111111"
  resources: "987654321777777777"
  local: "987654321888888888"

DiscordChatChannelVentureChatNeedsToBeSetForChat: true

VentureChat gibt jede Nachricht mit Channel-Tag aus, DiscordSRV faengt das ueber den Hook ab und routet sie in den passenden Text-Channel. Mit CarbonChat und CMI funktioniert das Prinzip identisch.

Ohne externen Chat-Plugin gibt es das DiscordSRV Channel Linking plus eigene Format-Filter, das ist aber eher ein Hack.

Death- und Achievement-Channel

Tod-Spam im Hauptchat nervt nach einer Stunde. Ab in einen eigenen Channel.

In messages.yml das Format anpassen:

MinecraftPlayerDeathMessage:
  Channel: "deaths"
  Embed:
    Color: "#ef4444"
    Author:
      Name: "%player%"
      ImageUrl: "https://crafatar.com/avatars/%uuid%?size=64"
    Description: "%death_message%"
    Footer:
      Text: "%world%"

MinecraftPlayerAchievementMessage:
  Channel: "achievements"
  Embed:
    Color: "#fbbf24"
    Author:
      Name: "%player%"
      ImageUrl: "https://crafatar.com/avatars/%uuid%?size=64"
    Description: ":trophy: erhielt **%achievement_name%**"

Crafatar liefert Skins als PNG nach UUID, das Embed zeigt also den Kopf-Avatar des passenden Spielers. Alternativen sind MineSkin (https://api.mineskin.org/render/head?uuid=...) oder mc-heads.net (https://mc-heads.net/avatar/%uuid%/64).

Channel: referenziert einen Schluessel aus dem Channels:-Block in config.yml. Fehlt der Schluessel, faellt die Nachricht auf global zurueck.

Console-Channel: sicheres privates Logging

Die Konsole nach Discord zu spiegeln ist praktisch, aber eine ernste Sicherheitsluecke, wenn der Channel nicht abgesichert ist. Jeder Spieler mit Lesezugriff sieht Tokens, IPs, Stacktraces mit Configpfaden.

Basis-Setup in config.yml:

DiscordConsoleChannelId: "987654321333333333"
DiscordConsoleChannelUsable: true
DiscordConsoleChannelBlacklistActsAsWhitelist: false
DiscordConsoleChannelBlacklistedCommands:
  - "?"
  - "op"
  - "deop"
  - "whitelist"
  - "stop"
  - "save-all"
  - "luckperms user * permission set *"
DiscordConsoleChannelDoNotSendCommandsList:
  - "lp user * info"
DiscordConsoleChannelTruncateLength: 1900

#server-console gehoert in eine Admin-Kategorie, sichtbar nur fuer Admin-Rollen, bei @everyone alle Rechte entzogen. Der Bot braucht View Channel, Send Messages, Read Message History.

DiscordConsoleChannelBlacklistedCommands blockt gefaehrliche Befehle aus Discord: selbst wenn jemand Channel-Zugriff bekommt, laufen /op oder /stop nicht durch. Wer eine engere Whitelist will, dreht BlacklistActsAsWhitelist: true und listet nur die erlaubten Befehle auf.

Ich wuerde zusaetzlich 2FA fuer alle Admin-Discord-Accounts erzwingen und dem Bot nach der Einrichtung das Administrator-Recht entziehen. Funktional reicht: View Channels, Manage Roles, Send Messages, Embed Links, Manage Webhooks, Read Message History, Mention @everyone (nur falls ihr Broadcasts in den globalen Channel schickt).

Custom Commands: Ausfuehrung aus Discord

Ueber die Bruecke koennen Server-Befehle aus einem Discord-Channel abgesetzt werden. Praktisch fuer Mods, wenn sie nicht im Spiel sind: /tempban Player1 1d Spam, /broadcast Restart in 5 Minuten.

Slash-Commands sind sicherer als Plain-Text, weil Discord die Argumente validiert und die Rolle pruefen kann:

DiscordCommandsExecutableViaConsoleChannel: true

DiscordCommandRolesRequiredToExecute:
  "tempban":
    - "987654321moderator"
    - "987654321admin"
  "broadcast":
    - "987654321admin"
  "kick":
    - "987654321moderator"

DiscordCommandConfirmation: true
DiscordCommandConfirmationTimeout: 10

DiscordCommandConfirmation haengt eine Reaction-Bestaetigung an, damit niemand versehentlich den Server mit /stop killt. Fuer /op und Aehnliches empfehle ich, die Ausfuehrung gar nicht erst zu erlauben und sie in der Blacklist zu lassen.

Webhooks: Saison-Teaser und Ankuendigungen

DiscordSRV kann eigene Nachrichten ueber Webhook-URLs schicken. Praktisch fuer Skripte, die ein Saison-Update, einen Patreon-Link oder ein Map-Preview posten.

Erstellt einen Webhook in den Channel-Einstellungen (Edit Channel -> Integrations -> Webhooks -> New Webhook), kopiert die URL.

Senden aus einem Plugin oder einem externen Skript:

curl -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "username": "Season 4 Announcer",
    "avatar_url": "https://i.imgur.com/your.png",
    "embeds": [{
      "title": "Saison 4 startet am 1. Mai",
      "description": "Neue Welt, neue Events, x2 XP in der ersten Woche",
      "color": 1099334,
      "image": {"url": "https://example.com/season4.png"}
    }]
  }' \
  "https://discord.com/api/webhooks/123456789/abcdef..."

Laesst sich problemlos in einen Cron-Job oder in eine Laravel-Task aus dem Admin-Panel haengen.

Mention Parsing und Formatierung

Standardmaessig kommen Discord-Mentions (@admin) im Minecraft-Chat als rohe ID an. Aktiviert das saubere Format:

DiscordChatChannelTranslateMentions: true
DiscordChatChannelMinecraftMentionFormat: "&9@%name%"
DiscordChatChannelEmojiBehavior: "name"
DiscordChatChannelDiscordToMinecraft:
  - "&7&o[DISCORD] &r%name%&7: &f%message%"

TranslateMentions: true parst <@123456> zu @nickname. EmojiBehavior: name macht aus :diamond: ein [diamond], damit Clients ohne Emoji-Font keine Muellzeichen sehen. Andere Werte sind unicode (roh, bricht auf alten Clients) und hide (entfernen).

In die Gegenrichtung Minecraft to Discord laesst sich der Template DiscordChatChannelMinecraftToDiscord anpassen.

DiscordSRV-Voice und Proximity Voice

Sprach-Chat ueber Discord laeuft entweder ueber das Addon DiscordSRV-Voice oder ueber die Kombination DiscordSRV plus Plasmo Voice. Das Addon erstellt temporaere Voice-Channels, die an Zonen in der Welt gebunden sind: rueckst du naeher heran, hoerst du den Spieler, gehst du weg, nicht mehr.

Setup kurz: DiscordSRV-Voice.jar nach plugins/, eine Kategorie Voice Proximity in Discord anlegen, der Bot erstellt Channels nach Bedarf. Die Kategorie referenzieren:

Voice:
  Enabled: true
  CategoryId: "987654321999999999"
  LobbyChannelId: "987654321aaaaaaaaa"
  HorizontalRadius: 50
  VerticalRadius: 30
  AllowVoiceCrossWorlds: false

Alternative ist Plasmo Voice mit eigenem Server, ohne Discord-Abhaengigkeit fuer Voice. Empfohlen, wenn ihr niedrigen Ping, Radio-Modelle oder echte Verschluesselung braucht. DiscordSRV bleibt fuer Text-Chat und Role Sync, Voice laeuft ueber Plasmo.

Performance ab 200+ Spielern

Auf grossen SMPs stoesst DiscordSRV gegen Discord-Rate-Limits: 5 Nachrichten pro 5 Sekunden pro Channel, 50 Requests pro Sekunde pro Bot. Basis-Tuning:

ChatChannelHookTimeout: 1500
DiscordChatChannelMessageBatching: true
DiscordChatChannelMessageBatchSize: 8
DiscordChatChannelMessageBatchDelay: 1500
RestActionAsyncSubmit: true

MessageBatching: true fasst mehrere Chat-Zeilen alle 1.5 Sekunden zu einer Discord-Nachricht zusammen, was die RPS um Faktor 5 bis 10 senkt. Sichtbar als kleine Verzoegerung, im allgemeinen Chat-Rauschen aber kaum zu bemerken.

RestActionAsyncSubmit: true ist Pflicht: sonst blockieren synchrone Calls zur Discord-API den Server-Mainthread und reissen die TPS bei Netzwerk-Hickups in den Keller.

Metriken kontrolliert ihr mit /discord debug: der Bot zeigt Ping zu Discord, Queue-Laenge, JDA-Task-Anzahl. Liegt der Ping dauerhaft ueber 300 ms, prueft die Netzwerkroute zu den europaeischen Discord-Rechenzentren.

Backup von Config und Links

Alle Spieler-Discord-Verbindungen liegen in plugins/DiscordSRV/linkedaccounts.json (oder in MySQL, falls aktiviert). Das sind kritische Daten: ein Verlust bedeutet, dass 200 Spieler erneut linken muessen und Role Sync von vorne anfaengt.

Mindestens ein taegliches Cron-Archiv:

#!/bin/bash
DATE=$(date +%Y-%m-%d)
tar czf /backup/discordsrv-$DATE.tar.gz \
  /opt/minecraft/plugins/DiscordSRV/linkedaccounts.json \
  /opt/minecraft/plugins/DiscordSRV/config.yml \
  /opt/minecraft/plugins/DiscordSRV/synchronization.yml \
  /opt/minecraft/plugins/DiscordSRV/messages.yml
find /backup -name "discordsrv-*.tar.gz" -mtime +30 -delete

Wer auf MySQL umgestellt hat, fuegt einen Dump der Tabelle discordsrv_accountlinks zum Haupt-mysqldump hinzu. Und nicht das BotToken vergessen: legt ihr die Config als Beispiel auf GitHub hoch, leakt das Token und jemand uebernimmt den Bot.

FAQ

Funktioniert DiscordSRV auf Folia?

Teilweise. Aktuell unterstuetzt DiscordSRV Folia nicht offiziell, weil viele Hooks die Mainthread-API nutzen. Die Chat-Bruecke laeuft, aber Events wie Tode und Achievements werden unzuverlaessig erfasst. Auf Folia lohnt sich ein Blick auf EssentialsXDiscord oder DiscordIntegration, oder ihr wartet auf einen offiziellen Patch.

Wie sichere ich den Console-Channel gegen Leaks?

Der Channel gehoert in eine Admin-Kategorie, bei @everyone werden View Channel und Read Message History entzogen. Erzwingt 2FA fuer alle Admins mit Zugriff, ein kompromittierter Account ist sonst gleichbedeutend mit Konsole-Zugriff. In DiscordSRV BlacklistedCommands mit gefaehrlichen Kommandos pflegen, damit selbst bei einem Leak /op oder /stop nicht durchgehen. Webhook-URLs nie in oeffentliche Repos pushen.

Mehrere Minecraft-Server in einem Discord?

Ja, zwei Wege. Erstens: DiscordSRV auf jedem Server, jeder bekommt einen eigenen Channel (#smp-chat, #anarchy-chat, #creative-chat), eine Discord-Guild. Zweitens: Proxy (BungeeCord/Velocity) mit globalem Chat, DiscordSRV als Proxy-Plugin via DiscordSRV-Bridge oder Velocitab plus einheitliches Chat-Plugin. Fuer ein SMP-Netzwerk ist Variante eins meist sauberer: jeder Server isoliert, Routing klar.

Was tun, wenn der Bot rate-limited wird?

MessageBatching einschalten, das deckt 90% der Faelle ab. Hilft das nicht, zeigt /discord debug, welche Requests sich stauen. Haeufiger Schuldiger ist zu haeufiger Role Sync (CycleTime: 1 bei 500 Spielern bedeutet Tausende API-Calls). Auf 10-15 Minuten erhoehen. Bei Massen-Linking-Events Auto-Sync beim Server-Start kurz deaktivieren und in Batches per /discord resync von Hand fahren.

Kann ich Message-Formate ohne Restart aendern?

messages.yml und config.yml werden mit /discord reload neu eingelesen. Aenderungen in linking.yml und synchronization.yml brauchen meist einen Plugin-Restart. /discord debug zeigt die aktiven Settings an, falls eure Aenderungen nicht greifen, ist ein Server-Restart faellig.

Der Bot vergibt keine Rollen, obwohl die Config korrekt aussieht

In neun von zehn Faellen: Rollenhierarchie. Discord -> Server Settings -> Roles. Die Bot-Rolle muss ueber allen Rollen liegen, die er verwaltet. Per Drag and Drop nach oben, kein Restart noetig. Im zehnten Fall fehlt dem Bot Manage Roles global oder in einem Channel/Kategorie. Pruefbar in Server Settings -> Roles -> euer Bot -> Permissions.

Wie zeige ich den Spieler-Skin als Discord-Avatar?

In messages.yml bei Embeds ImageUrl: "https://crafatar.com/avatars/%uuid%?size=128&overlay". Der Parameter overlay rendert die Hut-Schicht. Fuer Ganzkoerper-Render https://crafatar.com/renders/body/%uuid%?overlay. Crafatar cached die Ergebnisse, Rate Limits sind hier kein Thema.

Wie es weitergeht

Beim Start in Etappen vorgehen: erst Chat-Bruecke, dann Account Linking mit RequireLinkedAccountToPlay, danach Role Sync. Nicht alles auf einmal aufschalten, einzelne Features sauber debuggen. Und das Backup-Skript einmal in Staging durchlaufen lassen, bevor es produktiv wird: aus einem tar-Archiv sollten Links in Sekunden zurueck sein, sonst kostet euch ein Incident mehr Zeit, als ihr durchs Skript spart.

Bot-Rechte schon frueh einschraenken. Administrator reicht waehrend der Erstkonfiguration, danach lasst nur das absolute Minimum stehen. Plus 2FA auf jedem Discord-Account mit Zugriff auf Admin-Channels. Genau die fuenf Extra-Minuten Setup, die euch eine halbe Nacht Wiederherstellung nach einem Vorfall ersparen.