Zum Hauptinhalt springen

Discord

Kontoverknüpfung, Chat-Relay, Konsolenkanal, Fehlerberichte und Webhooks zwischen deinem Server und Discord.

Kostenlosv0.13Integrationen
BenötigtTypeWriter0.9Basic extensionPaper1.21.6+optionalShopsoptional
HerunterladenQuellcodeSupport

Überblick​

Discord verbindet deinen Minecraft-Server mit deinem Discord-Server. Alles, was an Discord geht, nutzt ein wiederverwendbares Objekt: ein Webhook-Ziel (die URL eines Discord-Kanals, dazu Name und Avatar), das einmal deklariert und von jeder Funktion referenziert wird. Um den Kanal zu wechseln, bearbeitest du einen einzigen Entry.

Die Erweiterung deckt sechs Aufgaben ab: Kontoverknüpfung mit Synchronisierung von Rängen zu Rollen, bidirektionales Chat-Relay, einen Konsolenkanal, um Serverbefehle von Discord aus auszuführen, ein Fehlerberichtssystem im Spiel, Ankündigungen von Shop-Transaktionen und Webhooks, die veröffentlicht werden, wenn sich ein TypeWriter-Fact ändert. Jede Funktion ist ein eigener Entry, du konfigurierst also nur, was du nutzt. Discord ist für den Rest von TypeWriter optional: Ohne Link-Manifest wird kein Discord-Bot gestartet.

Diese Erweiterung hieß bis Version 0.9 Community. Die Entry-Namen haben sich nicht geändert, und vor der Umbenennung erstellte Seiten werden beim ersten Start umgewandelt.

Funktionen​

  • Webhook-Ziele — ein Entry pro Discord-Kanal (URL, Benutzername, Avatar, dauerhafte Rollen-Pings), von allen Funktionen gemeinsam genutzt.
  • Kontoverknüpfung — Spieler führen einen Befehl aus, erhalten einen Code, tippen ihn in einen Discord-Kanal und ihre Konten sind verknüpft; Discord-Rollen folgen ihren Minecraft-Gruppen.
  • Chat-Synchronisierung — Minecraft-Chat sowie Beitritts- und Austrittsnachrichten gehen an Discord, und Discord-Nachrichten können zurück ins Spiel gelangen.
  • Konsolenkanal — Staff führt Serverbefehle von einem Discord-Kanal aus, mit Befehlsliste, Rollenbeschränkung und Logdatei.
  • Fehlerberichte — ein Dialogformular im Spiel, mit Statusverfolgung gespeichert, als Embed oder Forum-Thread an Discord gesendet und über Discord-Slash-Befehle verwaltbar.
  • Shop-Ankündigungen — Käufe und Verkäufe werden in den Kanal gepostet, den jeder Shop angibt (erfordert die Shops-Erweiterung).
  • Fact-Webhooks — eine Nachricht, wenn sich ein TypeWriter-Fact ändert, pro Spieler, pro Gruppe oder global.
  • Automatische Migration — Seiten vor 0.9 mit Inline-Webhooks werden in Webhook-Ziele umgewandelt.

Installation​

  1. Erstelle einen Discord-Webhook im gewünschten Kanal: in Discord Kanal bearbeiten (Channel settings), Integrationen (Integrations), Webhooks, Neuer Webhook (New Webhook), dann kopiere seine URL. Das reicht für Webhooks, Fehlerberichte und einseitigen Chat.
  2. Für die Kontoverknüpfung, das Chat-Relay von Discord zu Minecraft, den Konsolenkanal und Slash-Befehle benötigst du zusätzlich einen Discord-Bot. Erstelle ihn im Discord Developer Portal, kopiere seinen Token, lade ihn auf deinen Server ein und aktiviere unter Bot den Server Members Intent und den Message Content Intent. Die Erweiterung fordert diese Intents an und kann sich ohne sie nicht verbinden.
  3. Stelle sicher, dass die Basic-Erweiterung von TypeWriter installiert ist (siehe die TypeWriter-Dokumentation).
  4. Lege die Discord-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu. Die JAR enthält bereits die für den Bot genutzte JDA-Bibliothek.
  5. Für Shop-Ankündigungen installiere zusätzlich die Shops-Erweiterung.

Fehlerberichte verwenden die Dialogbildschirme von Paper, die Paper 1.21.6 oder neuer benötigen.

Erste Schritte​

So verknüpfst du Konten und sendest Fehlerberichte an deinen Staff-Kanal:

  1. Öffne im TypeWriter-Web-Panel eine Manifest-Seite und füge eine Webhook Definition hinzu. Füge die Kanal-URL in url ein, optional dazu username und avatarUrl.
  2. Füge auf derselben Seite ein Discord Link Storage-Artifact hinzu: Es speichert Verknüpfungen und ausstehende Codes.
  3. Füge ein Discord Link Manifest hinzu. Setze storage auf das Artifact und webhook auf dein Ziel, aktiviere bot und fülle botToken und guildId. Setze verificationChannelId auf den Discord-Kanal, in dem Spieler ihren Code eingeben.
  4. Optional: Fülle roleMappings, um Discord-Rollen nach Minecraft-Gruppe zu vergeben, zum Beispiel minecraftGroup vip und die Discord-Rollen-ID in discordRoleId.
  5. Füge ein Bug Report Sequence Storage-Artifact hinzu, dann ein Bug Report Manifest. Setze commandName (zum Beispiel bugreport), sequenceStorage, serverName und mindestens einen Eintrag in categories, mit einer Eingabe, deren key description ist. Setze in webhook den Wert destination auf dein Ziel.
  6. Veröffentliche (Publish). Ein Spieler führt /discordlink aus, um einen Code zu erhalten, tippt ihn im Verifizierungskanal ein und ist verknüpft. Mit /bugreport öffnet ein Spieler das Formular.

Um die ID eines Discord-Kanals oder einer Rolle zu erhalten, aktiviere den Entwicklermodus (Developer Mode) in den erweiterten Einstellungen von Discord, klicke dann mit der rechten Maustaste auf den Kanal oder die Rolle und wähle ID kopieren (Copy ID).

So funktioniert es​

Das Senden nutzt einen Webhook, ohne Bot. Das Empfangen von Discord benötigt den Bot, der nur im Discord Link Manifest konfiguriert wird. Ohne aktivierten Bot tun das Chat-Relay von Discord zu Minecraft, der Konsolenkanal und die Slash-Befehle für Fehlerberichte nichts.

Ein leeres oder deaktiviertes Ziel ist der normale Weg, nichts zu senden. Ein Verweis auf ein Ziel, das nicht mehr existiert, wird als Destination '…' not found; message dropped protokolliert.

Konfiguration​

Die Erweiterung wird im Web-Panel konfiguriert. Verknüpfungsdaten und Fehlerberichte werden in den von dir erstellten Artifact-Entries gespeichert. Darüber hinaus schreibt sie:

DateiInhalt
logs/discord-console.logBefehle, die vom Konsolenkanal aus ausgeführt wurden (relativ zum Serverstamm; der Pfad ist ein Feld des Entrys).
backup/community-webhook-v1/Sicherung der Seiten, die von der Migration aus Community umgeschrieben wurden, im Typewriter-Ordner.

Migration von Community​

Vor 0.9 erstellte Seiten speicherten den Webhook in jedem Manifest. Beim ersten Start erstellt die Erweiterung pro eindeutigem Ziel eine Webhook Definition, lässt die Manifeste darauf verweisen und sichert zuvor jede umgeschriebene Seite. Anschließend fordert sie dich auf, einmal /typewriter reload auszuführen.

Befehle​

Die folgenden Befehle werden von den Manifest-Entries registriert. Ihre Namen sind Felder dieser Entries; angezeigt sind die Standardwerte.

BefehlBeschreibung
/discordlinkErzeugt einen Verifizierungscode oder wiederholt den ausstehenden. Nur für Spieler.
/discordlink unlinkEntfernt die Verknüpfung und die zugeordneten Discord-Rollen.
/bugreportÖffnet die Kategorieauswahl und dann das Berichtsformular.
/bugreport mineListet deine eigenen Berichte auf.
/bugreport list [player]Listet Berichte auf, optional von einem Spieler. Erfordert die Admin-Berechtigung.
/bugreport status <reportId> <statusId>Ändert den Status eines Berichts. Erfordert die Admin-Berechtigung.
/bugreport delete <reportId>Löscht einen Bericht. Erfordert die Admin-Berechtigung.

Ist discordCommands aktiv, registriert das Bug Report Manifest außerdem einen Slash-Befehl auf deinem Discord-Server, benannt wie commandName, mit list, status und delete. Nur Discord-Administratoren oder Mitglieder mit einer Rolle aus discordAdminRoleIds können ihn nutzen.

Das Registrieren dieser Slash-Befehle ersetzt die anderen Slash-Befehle, die dieser Bot auf dem Server hat.

Berechtigungen​

Alle Berechtigungen sind Felder der Entries und können geändert werden. Standardwerte:

BerechtigungErlaubt
discordlink.notifyEine Nachricht erhalten, wenn ein Spieler ein Konto verknüpft (notifyPermission; leer deaktiviert es).
bugreport.notifyEine Nachricht erhalten, wenn ein Bericht eingereicht wird (notifyPermission).
bugreport.admin/bugreport list, status und delete verwenden (adminPermission).
group.<group>Passt zu einer Rollenzuordnung: Die erste Zuordnung, deren Gruppe zutrifft, ist die Discord-Rolle des Spielers (groupPermissionFormat).

Entries​

9 Einträge, aus dem Quellcode der Erweiterung generiert.

Ereignisse1
Befehle2
Artefakte2
Manifeste4

Fehlerbehebung​

Der Bot verbindet sich nicht. Die Konsole zeigt Failed to connect Discord Bot oder Discord Bot is disabled or token is missing. Prüfe, ob bot mit dem richtigen botToken aktiviert ist und ob die Intents Server Members und Message Content im Developer Portal eingeschaltet sind. Die guildId muss die ID des Servers sein: Ist sie falsch, siehst du guild not found.

/discordlink meldet, die Verknüpfung sei nicht konfiguriert. Auf keiner veröffentlichten Seite gibt es ein Discord Link Manifest. Die Konsole zeigt discord_link_manifest not found; Discord link is disabled.

Der in Discord eingegebene Code wird ignoriert. Spieler müssen nur den Code eingeben, genau codeLength Buchstaben oder Ziffern, in dem Kanal, der in verificationChannelId gesetzt ist. Der Bot reagiert mit einem Haken oder einem Kreuz. Ein abgelaufener Code (codeValidityMinutes) oder ein bereits verknüpftes Discord-Konto wird abgelehnt. Ein bereits verknüpfter Spieler wird ebenfalls abgelehnt, außer autoOverwriteExistingLink ist aktiv.

Der Fehlerbericht-Befehl meldet, es gebe keine Kategorien. categories ist standardmäßig leer. Füge mindestens eine Kategorie hinzu. Ein Bericht wird nur angenommen, wenn seine Eingabe title oder description ausgefüllt ist, und das Formular fügt die Eingabe title selbst hinzu; füge also eine Eingabe mit dem Key description für die Nachricht hinzu.

Fehlerberichte werden von Discord abgelehnt. threadNameTemplate ist für Forumkanäle gedacht. Ist dein Ziel ein normaler Textkanal, leere die Vorlage. Die Konsole zeigt Webhook '…' rejected with HTTP … mit dem Grund.

Konsolenbefehle tun nichts. Der Konsolenkanal benötigt den Bot, und die Kanal-ID in discordChannelId muss übereinstimmen. Ein blockierter Befehl erhält eine Verboten-Reaktion und ein nicht autorisiertes Mitglied ein Kreuz. Standardmäßig ist commandList eine Blacklist mit stop, restart und reload; wechsle zu blacklistIsWhitelist und beschränke allowedRoles für ein sichereres Setup.

Shop-Verkäufe werden nicht angekündigt. Du benötigst ein Shop Notification Manifest (ohne es wird nichts gesendet), und die Shop-Definition muss das Ziel in ihrer notificationWebhookId nennen, mit der ID deines Webhook-Definition-Entrys. Die Shops-Erweiterung muss installiert sein.

Verwandte Erweiterungen​

  • Shops — seine Shops nennen die Webhook Definition, die ihre Transaktionen ankündigt.