Konzeption der Discord-Integration
Diese Seite erklärt, wie die Discord-Integration in dzbot funktioniert und was zu prüfen ist, wenn Discord-Funktionen fehlen.
Was die Discord-Integration ermöglicht
Je nach Konfiguration und Berechtigungen kann dzbot:
- Spieler mit Discord-Konten verknüpfen
- Spitznamen mit Spielernamen im Spiel synchronisieren
- das Discord-Profilbild jedes verknüpften Spielers neben seinem Namen auf deiner Website zeigen – gelesen beim Login und beim Rollen- und Spitznamen-Abgleich, nie beim Seitenaufruf
- Rollen zuweisen oder entfernen
- Direktnachrichten senden
- dedizierte Ticket-Channel erstellen, sowie pro Support-Level eine Kategorie und eine verwaltete Rolle
- für jede Fraktion und jede Allianz einen privaten Chat-Channel pflegen, siehe Fraktions- und Allianz-Chats
- Panels für Anliegensarten posten, über die Spieler Tickets öffnen, und ihnen das Aufnahmeformular als Discord-Dialog zeigen
- An Unterstützungs- oder Alarmkanäle posten
- Einen Online-Spielerlisten-Kanal pflegen
- Eine Ranglisten-Nachricht in einem Kanal aktuell halten
- Live-Zahlen — Spieler online, Kills heute und mehr — als Namen gesperrter Sprachkanäle zeigen, siehe Sprachkanal-Zähler
- Jedem Spieler mit
/playersein eigenes Profil und seine Statistiken zeigen - Spieler ihren Kontostand, ihre Bestellungen, Orte, Wetten, Kopfgelder, Fraktion, Basisalarme und Events per Slash-Befehl erledigen lassen — siehe Discord-Befehle
Grundlagen der Bot-Installation
Die Installationsaufforderung für den Bot wird als Admin-Warnung angezeigt, wenn beide folgenden Bedingungen erfüllt sind:
- ein Discord-Server aus dem verbundenen Discord-Konto des Administrators ist in den Einstellungen ausgewählt, und
- dzbot erkennt, dass der Bot auf diesem Server nicht installiert ist.
Die Warnung enthält einen Discord-OAuth-Link, um den Bot hinzuzufügen, sowie einen erneuten Überprüfungslink, sobald er installiert ist. Sie erscheint nicht für Spieler oder auf der Shop-Frontend. Nach dem Hinzufügen schickt Discord den Admin zurück in den Discord-Schritt des Setup-Assistenten, mit diesem Discord-Server bereits ausgewählt.
Verbinden kann einen Discord-Server nur, wem er gehört oder wer dort die Berechtigung Administrator hat, und die Liste der Discord-Server bietet nur Discord-Server an, auf denen der angemeldete Admin das erfüllt.
Der Installationslink bittet Discord, dem Bot Administrator zu geben, damit er private Kanäle ohne weitere Einrichtung nutzen kann. Wählst du das ab, sieht der Bot nur Kanäle, in die seine Rolle hineindarf, und ein privater Kanal, den du für die Online-Liste, die Rangliste, die Regeln oder eine Automation auswählst, taucht im Discord-Integrationsprotokoll auf, bis du der Bot-Rolle dort Kanal anzeigen und Nachrichten senden gibst. Fügst du den Bot erneut hinzu, setzt Discord seine Rolle auf die Rechte zurück, die du in diesem Dialog bestätigst; was du der Rolle von Hand gegeben hattest, ist danach weg.
Den vollständigen Setup-Ablauf findest du unter Erste Schritte: Discord-Integration verbinden.
Eine Guild für mehrere Gameserver
Mehrere dzbot-Server können denselben Discord-Server auswählen — eine Community kann so zwei Gameserver über einen Discord betreiben. Eingehende Ereignisse (KI-Companion-Erwähnungen, über Discord eröffnete Tickets) werden dann über die Kategorie des Channels per Einstellung Zugeordnete Discord-Kategorien zugeordnet. Das erfordert bewusste Konfiguration — siehe Mehrere Gameserver in einer Discord-Guild für Einrichtung und Stolperfallen.
Spielerrollen
Der Bot legt pro Gameserver drei Rollen an, sobald er sie zum ersten Mal braucht, und pflegt sie:
| Rolle | Wer sie hat |
|---|---|
| Online | Spieler, die gerade auf dem Gameserver sind |
| Connected | Spieler, die ihren Spielaccount mit Discord verknüpft haben |
| Rules accepted | Spieler, die die Regeln des Servers akzeptiert haben |
Jeder Name endet mit der Subdomain des Servers, zum Beispiel Online (meinserver). So bleiben die Rollen
mehrerer Gameserver auf einem Discord unterscheidbar. Fraktionsrollen tragen nur den Fraktionsnamen, außer du
setzt einen Präfix für Fraktionsrollen. dzbot erkennt seine Rollen an der ID, nicht am Namen — du
kannst sie beliebig umbenennen. Rollen, die vor der Subdomain angelegt wurden, werden einmalig umbenannt; eine
Rolle, die du schon selbst umbenannt hast, bleibt, wie sie ist.
Ticket-Support-Level
Jedes Support-Level eines Servers besitzt zwei Discord-Objekte, die der Bot anlegt und pflegt:
- eine Kategorie, in der die Ticket-Channel dieses Levels liegen, damit Mitarbeiter eines Levels nur an einer Stelle nachsehen müssen. Sie wird beim Anlegen des Levels erstellt und ist später unter Server Admin -> Tickets -> Level austauschbar; beim Wechsel wandern die bestehenden Channel des Levels mit.
- eine Rolle, deren Mitgliedschaft dem Level-Recht in dzbot folgt. dzbot-Rechte sind hier die einzige Wahrheit, genau wie bei den Rollen Connected und Online — vergib sie nicht von Hand.
Weil die Levelsichtbarkeit kumulativ ist, erhält ein Mitarbeiter mit Level 3 auch die Rollen von Level 1 und 2, sodass die unteren Kategorien lesbar bleiben.
Beim Hochreichen wandert der Channel in die Kategorie des Ziel-Levels, und die Rollen-Overwrites werden getauscht. Das in dzbot gespeicherte Level ist maßgeblich: Schlägt ein Discord-Aufruf fehl, verbirgt die App das Ticket trotzdem korrekt und nur der Channel liegt falsch — das repariert Discord neu synchronisieren am Ticket.
Die frühere serverweite Einstellung „Discord-Tickets-Support-Rolle" wurde entfernt — eine einzelne Rolle, die jeden Ticket-Channel liest, ist in einem levelgetrennten System eine Hintertür.
Panels für Anliegensarten
Eine Anliegensart kann ein Panel in so vielen Channels besitzen, wie du brauchst — eines pro Channel: ein Embed mit Name und Beschreibung der Art und einem „Ticket öffnen"-Button pro gepflegter Sprache. Ein Klick öffnet das Aufnahmeformular dieser Art als Discord-Dialog, und aus den Antworten entsteht das Ticket — der Spieler verlässt Discord nie. Alle Panels einer Art sind austauschbar: ein Ticket aus dem Gäste-Channel ist dasselbe Ticket wie eines aus dem Mitglieder-Channel.
Was das für dein Discord-Setup bedeutet:
- der Bot braucht Postrechte in jedem Panel-Channel; fehlen sie, schlägt das Veröffentlichen dort mit einer Warnung fehl und sonst passiert nichts, denn die Ticketerstellung hängt nicht an den Panels. Ein Speichervorgang, der einen Channel nicht erreicht, aktualisiert die übrigen Panels der Art trotzdem
- jedes Panel wird bei jeder Änderung der Art an seiner Stelle bearbeitet, damit die Buttons immer zum aktuellen Formular passen. Löscht jemand eine Panel-Nachricht, merkt das der nächste Speichervorgang und bietet an, sie erneut zu veröffentlichen
- Discord kann Nachrichten nicht verschieben, deshalb sortiert das Umsortieren der Anliegensarten die Panels nicht mit — die Aktion Panels neu aufbauen im Editor postet die Panels eines Channels neu
- ein Discord-Dialog nimmt höchstens fünf Eingaben und kann keinen zweiten nach sich ziehen; deshalb ist ein Aufnahmeformular auf beiden Oberflächen auf fünf Felder begrenzt
- auf einer geteilten Guild entsteht das Ticket auf dem Server, zu dem die Anliegensart gehört, egal wo ihr Panel steht — siehe Mehrere Gameserver in einer Discord-Guild
Spieler brauchen dafür nicht einmal ein Panel: /ticket, für jedes Mitglied sichtbar, bietet dieselben
Anliegensarten an — bei einer Art öffnet sich direkt ihr Formular, bei mehreren zuerst eine private
Auswahlliste. Details im Ticket-Konzept.
Veröffentlicht und neu aufgebaut werden Panels unter Server-Admin → Tickets → Anliegensarten; die Mechanik hinter dem Formular selbst steht im Ticket-Konzept.
Anforderungen an die Rollenhierarchie
Discord erlaubt es einem Bot nur, Rollen zu verwalten, die unterhalb der Bot-Rolle liegen. Wenn die Rollensynchronisierung nicht funktioniert, verschiebe die Bot-Rolle über die Rollen, die sie verwalten muss. Um sicherzustellen, dass der Bot alles tun kann, was er muss, stelle sicher, dass er die höchste Rolle im System hat.
Referenzen: https://docs.discord.com/developers/topics/permissions https://support.discord.com/hc/de/articles/214836687-Discord-Rollen-und-Berechtigungen
Berechtigungen für Spitznamen
Um seinen eigenen Spitznamen zu aktualisieren, benötigt ein Bot Spitznamen ändern. Um Spitznamen anderer Mitglieder zu aktualisieren, benötigt er Spitznamen verwalten.
Referenzen: https://support.discord.com/hc/de/articles/219070107-Server-Spitznamen https://docs.discord.com/developers/topics/permissions
Opt-in- und Opt-out-Verhalten
Wenn ein Benutzer sich abmeldet, werden Discord-basierte Benachrichtigungen für dieses Konto gestoppt. Es gibt zwei Möglichkeiten, wie Spieler den Erhalt von Discord-Nachrichten deaktivieren können:
Automatische Abmeldung bei Bot-Blockierung
Wenn der Spieler den Bot in Discord blockiert, wird er automatisch abgemeldet.
Explizite Abmeldung
Wir stellen einen expliziten Abmeldeendpunkt bereit, der in allen Nachrichten verlinkt ist, die der Bot direkt an Spieler sendet (per DM, nicht in Kanälen). Dies ermöglicht es Spielern, den Erhalt von Discord-Benachrichtigungen bei Bedarf einfach zu beenden.
Fehlerbehebung bei Abmeldungen
Oftmals erfolgen Abmeldungen ohne Kenntnis der Konsequenzen (oder unbewusst durch Bot-Blockierungen). Wenn Spieler sich über fehlende Benachrichtigungen (wie Basisalarme) beschweren, überprüfe stets den Abmeldestatus des betreffenden Spielers, indem du die Impersonationsfunktion verwendest. Abgemeldete Spieler erhalten auf allen Shop-Seiten eine deutliche Warnung, sich erneut anzumelden.
Von Discord aus auf einen Spieler zugreifen
Für Routinearbeit muss niemand das Panel öffnen. Drei Einstiege führen auf dieselbe Karte:
- Rechtsklick auf ein Mitglied → Apps → Spieler nachschlagen
- Rechtsklick auf eine Nachricht → Apps → Spieler nachschlagen — löst den Verfasser auf
/player <benutzername>— für Spieler, die nie ein Discord-Konto verknüpft haben und die man deshalb nicht anklicken kann. Passen mehrere Spieler auf den Namen, bietet der Bot eine Auswahl an, statt zu raten. Ohne Namen zeigt/playerdas eigene Profil des Moderators (siehe unten).
Die Karte ist privat: Nur der Moderator, der sie geöffnet hat, sieht sie. Sie zeigt Status (Whitelist, Bann und bis wann, Claim-Sperre), Guthaben, letzte Sichtung, die Anzahl der Notizen und — je nach Konfiguration — Position, Gruppen, Fraktionen und letzte Bestellungen. Ein Link öffnet denselben Spieler im Panel.
Die Knöpfe darauf sind die Aktionen, für die der Moderator tatsächlich Rechte hat; der Rest wird gar nicht erst gezeichnet statt ausgegraut:
| Knopf | Recht |
|---|---|
| Whitelist / Whitelist entfernen | admin.players.whitelist |
| Claim-Sperre aufheben — nur solange der Spieler gesperrt ist | admin.players.unblock |
| Notizen | admin.players.view |
| Notiz hinzufügen | admin.players.edit |
| Verwarnen | admin.players.warn |
| DM senden — nur wenn der Spieler ein Discord-Konto verknüpft hat, das DMs annimmt | admin.players.send_discord_dm |
| Geld geben / Geld abziehen | admin.players.change_money |
| Gratis-Artikel | admin.players.give_free_items |
| Bestellungen | admin.orders.view |
| Bannen | admin.restrictions.create |
| Entbannen | admin.restrictions.edit |
Die Karte überhaupt zu öffnen braucht admin.players.view auf diesem Server. Notiz, Verwarnen, Geld, Bann, Entbannen und DM öffnen ein kleines Formular. Anders als im Browser braucht ein Bann aus Discord immer eine Begründung; die Auswahl Grund markiert einen Bann wegen Cheating, wie Grund: Cheating auf der Website. Entbannen fragt, warum der Bann aufgehoben wird, und nimmt optional einen Ticket-Code zum Verknüpfen; in einem Ticket-Kanal wird dieses Ticket automatisch verknüpft.
- Claim-Sperre aufheben hebt die 24-Stunden-Sperre auf, die ein Spieler bekommt, wenn er beim Verknüpfen seines Kontos die falsche Position rät. Er kann es dann sofort noch einmal versuchen.
- DM senden schreibt dem Spieler im Namen des Support-Teams: Der Bot setzt eine Zeile mit dem Servernamen über den Text, genau wie bei der DM von der Spielerseite in der App. Der Text (bis 1.500 Zeichen) geht los, sobald du das Formular abschickst, und landet im Audit-Trail.
- Gratis-Artikel legt eins der Artikelsets des Servers gratis in den Warenkorb des Spielers, wie Gratis-Artikel auf der Spielerseite. Tipp einen Teil des Set-Namens oder einen Klassennamen ein (oder nichts, dann siehst du alle Sets), wähl das Set aus der Liste und bestätige. Der Spieler bekommt es mit seiner nächsten Bestellung. Einzelne Artikel von Hand zusammenstellen geht nur in der App.
- Bestellungen zeigt die 20 letzten Bestellungen des Spielers — siehe
/orders. - Verwarnen erteilt eine Verwarnung: wofür, wann sie abläuft (
30d,7d, … oder leer für nie), ein optionaler Discord-Timeout (1 Minute bis 1 Woche) und ob der Spieler per DM informiert wird (standardmäßig ja). Die Antwort nennt die Zahl seiner aktiven Verwarnungen, ob DM und Timeout geklappt haben und ob eine Verwarnungsstufe den Spieler gebannt hat. Das Feld Notizen auf der Karte zeigt die aktiven Verwarnungen, die Notizliste markiert Verwarnungen und abgelaufene Notizen. Der Timeout braucht die Bot-Berechtigung Mitglieder moderieren; fehlt sie, steht das auf der Seite Discord-Prüfung.
/player für Spieler: das eigene Profil
/player ist für alle sichtbar. Wer admin.players.view nicht hat, bekommt sein eigenes Profil, nie das eines anderen: Ein eingetippter Name wird ignoriert, und die Karte sagt das. Sie entspricht der Profilseite im Web — Name, Kontostand, Spielzeit, zuletzt gesehen, Fraktionen und die Statistikgruppen Kampf, Aktivität, Bauen und Casino, umschaltbar per Buttons. Gezählt wird wie im Web ab dem Stats-Reset-Datum, und nichts von der Moderatorenkarte erscheint (keine Notizen, Position, Whitelist- oder Bannstatus, keine Aktionsbuttons).
Wessen Discord-Konto auf diesem Server mit keinem Spieler verknüpft ist, bekommt den Hinweis, zuerst /link mit dem Ingame-Namen zu nutzen. Die Karte braucht dasselbe Recht wie das Web-Profil (player.shop_profile.access), gebannte Spieler bekommen sie also auch nicht. Auch die beiden Kontextmenü-Einträge Spieler nachschlagen sieht jeder, und sie verhalten sich genauso: Ohne admin.players.view öffnen sie das eigene Profil.
Die Kontextmenü-Einträge und Slash-Befehle sind globale Discord-Befehle. Jedes Deployment registriert sie automatisch neu, ein neuer oder geänderter Befehl taucht also ohne dein Zutun auf — Discord braucht dafür manchmal ein paar Minuten oder ein Neuladen des Clients.
Sprachkanal-Zähler
dzbot kann Live-Zahlen deines Servers als Namen von Sprachkanälen zeigen, zum Beispiel 🟢 Online: 34/60 oder ⚔️ Kills heute: 112. Du schaltest sie unter Server Admin → Einstellungen → Discord → Sprachkanal-Zähler ein.
| Zähler | Zeigt |
|---|---|
| Online / Slots | Spieler, die gerade online sind, und die Slots des Servers |
| Kills heute | PvP-Kills seit Mitternacht — die Kills, die für die Ranglisten zählen (ohne ausgeschlossene Kills und Spawn-Kills) |
| Tode heute | jeden Tod eines Spielers seit Mitternacht |
| Weitester Kill heute | den weitesten Kill von heute, in Metern |
| Beste Kill-Serie heute | die meisten Kills, die jemand heute gemacht hat, ohne selbst getötet zu werden |
| Offene Kopfgelder | wie viele Kopfgelder gerade offen sind |
| Meiste Spieler gleichzeitig heute | die höchste Zahl gleichzeitig online gewesener Spieler heute |
| Spieler heute | wie viele verschiedene Spieler heute auf dem Server waren |
„Heute“ beginnt um Mitternacht in der Zeitzone deines Servers (Einstellungen → Server → Zeitzone).
So verhalten sie sich:
- dzbot legt die Kanäle an. Mit dem ersten Zähler, den du einschaltest, legt dzbot eine Kategorie
📊 Server-Statistikmit einem Sprachkanal pro Zähler an. Die Kanäle sind sichtbar wie deine anderen Kanäle, aber niemand kann ihnen beitreten. - Namen ändern sich höchstens alle sechs Minuten. Discord erlaubt zwei Umbenennungen pro Kanal in zehn Minuten. Deshalb prüft dzbot alle sechs Minuten und benennt nur Kanäle um, deren Zahl sich geändert hat. Eine Zahl kann so lange hinterherhinken.
- Der Name gehört dir. Jeder Zähler hat einen Namen mit
{value}an der Stelle der Zahl. Lässt du ihn leer, nimmt dzbot den Standard in der Sprache deines Servers. - Ein ausgeschalteter Zähler verliert seinen Kanal. Sind alle Zähler aus, löscht dzbot auch seine Kategorie, außer du hast andere Kanäle hineingelegt.
- Einen Kanal von Hand zu löschen hält nicht. Solange sein Zähler an ist, legt dzbot ihn beim nächsten Durchlauf wieder an — schalte stattdessen den Zähler aus.
- Du kannst die Kanäle verschieben und umsortieren. dzbot lässt verschobene Kanäle, wo sie sind, und benennt sie nur um. Eine neue Kategorie legt es nur an, wenn es einen Kanal anlegen muss und seine eigene Kategorie weg ist.
- Mehrere Gameserver auf einem Discord bekommen je eine eigene Kategorie mit dem Namen des Servers —
📊 <Servername>. Die Zähler müssen nie unter Zugeordnete Discord-Kategorien beansprucht werden, weil niemand mit ihnen interagieren kann.
Der Bot braucht Kanäle verwalten und Rollen verwalten sowie das Recht Verbinden, das er allen anderen in diesen Kanälen entzieht. Fehlt ihm etwas davon, bleiben die Zähler, wie sie sind, und die Seite Discord-Audit sagt, was du freigeben musst.
Kanalnamen und was sie verraten
Standardmäßig heißt ein Ticket-Kanal nach dem Betreff des Tickets und ein Basisalarm-Kanal nach der Fraktion oder dem Spieler, zu dem er gehört. Jeder, der die Kanalliste sieht, kann diese Namen also mitlesen.
Die Einstellung Discord-Kanalnamen anonymisieren ersetzt sie durch den Code des Eintrags: ticket-7kqm und base-alarm-7kqm. Einmal aus- und wieder einschalten benennt bestehende Kanäle um. Sie betrifft Ticket- und Basisalarm-Kanäle; andere Kanalarten bleiben unberührt.
Zwei Details sind wichtig:
- Neue Server haben sie an. Bestehende Server wurden bei der Einführung bewusst so gelassen, wie sie waren — sie behalten die sprechenden Namen, bis jemand die Einstellung einschaltet.
- Das Umschalten benennt auch bestehende Kanäle um, in beide Richtungen. Es ist also nicht nur eine Regel für die Zukunft.
Allgemeine Überprüfungen bei fehlenden Discord-Funktionen
- Discord-Server ist in Server-Admin → Einstellungen aus dem verbundenen Discord-Konto des Administrators ausgewählt
- die Channel-/Kategorie-Dropdowns wurden nach dem Wechsel des Discord-Servers aktualisiert
- Bot ist auf der richtigen Gilde installiert
- Bot-Rolle steht über den von ihr verwalteten Rollen
- Erforderliche Berechtigungen sind erteilt
- Spieler ist nicht abgemeldet