GuildTools DE

GuildTools

🌐 English · Deutsch

GuildTools ist ein Werkzeugkasten für (WoW-)Discord-Gilden. Es bündelt drei Cogs, die gemeinsam in einem Paket ausgeliefert werden: Mitglieder-/Umfrage-Exporte, einen Abwesenheits-Tracker, /whois-Charakterabfragen für World of Warcraft über die Blizzard-API sowie einen privaten Raid-Verfügbarkeitsplaner („Ready-Times"). Die meisten Befehle sind ausschließlich Slash und antworten ephemeral (nur du siehst die Antwort). Das Paket bindet sich automatisch in das PDC Web Dashboard ein. Autor: pd-codes · benötigt Red 3.5.0+ · Status: Beta.

Installation

[p]repo add PDC_Redbot_Cogs https://github.com/pd-codes/PDC_Redbot_Cogs
[p]cog install PDC_Redbot_Cogs GuildTools
[p]load GuildTools
[p]slash sync

[p] ist das Präfix deines Bots. Die vollständige Downloader-Anleitung findest du unter Installation. Da fast jeder Befehl nur als Slash funktioniert, ist ein einmaliges [p]slash sync nach dem Laden erforderlich.

Beim Installieren von GuildTools werden gleich drei Cogs geladen: GuildTools (Exporte, Abwesenheiten, Whois), ReadyTimes (Verfügbarkeitsplaner) und GuildToolsPollExport (Umfrage-CSV-Export). Für die /whois-Abfrage brauchst du außerdem Blizzard-API-Zugangsdaten (siehe unten).

Die Blizzard-Token-Anfrage nutzt aiohttp. Es wird mit Red ausgeliefert; fehlt es, meldet /whois, dass aiohttp nicht installiert ist.

Befehle

Alle Befehle außer setblizzard / clearblizzard sind native Application-(Slash-)Befehle. Die beiden Credential-Befehle sind Prefix, nur Owner.

Befehl	Typ	Parameter	Funktion
whois	Slash	charname, realm?	Zeigt WoW-Charakterinfos (Level, Klasse, Rasse, Fraktion, Gilde, Itemlevel, letztes Login) eines Classic-Charakters über die Blizzard-API. Ohne realm wird der Gilden-Standardrealm/-region verwendet.
set-wow-defaults	Slash	region (eu/us/kr/tw), realm	Setzt Standard-Region + -Realm für /whois in dieser Gilde.
setblizzard	Prefix (Owner)	client_id, client_secret	Speichert Blizzard-API-Zugangsdaten in der Config als Fallback, wenn keine Umgebungsvariablen genutzt werden. Löscht den Token-Cache.
clearblizzard	Prefix (Owner)	–	Entfernt die gespeicherten Blizzard-Zugangsdaten und den Token-Cache aus der Config.
export-userlist	Slash	–	Exportiert alle Gildenmitglieder in eine ;-getrennte CSV (UTF-8 BOM): UserID, Username, Servername, Rollen, Beitrittsdatum, Zuletzt-online-Zeitstempel. Wird ephemeral gesendet.
export-poll	Slash	poll, mode (Key-Oriented / Value-Oriented)	Exportiert eine native Discord-Umfrage als ;-getrennte CSV. poll bietet Autocomplete über die letzten Umfragen im Channel; alternativ Nachrichten-ID oder Link einfügen.
add-absence	Slash	von, bis	Trägt eine Abwesenheit (Start-/Enddatum) ein. Akzeptiert DD-MM-YYYY, DD.MM.YYYY oder DD/MM/YYYY. Max. 365 Tage; Ende darf nicht vor Start liegen. Die Bestätigung wird öffentlich gepostet.
list-absence	Slash	–	Listet deine eigenen Abwesenheiten als ephemeres Embed.
get-absence	Slash	–	Exportiert alle erfassten Abwesenheiten der Gilde als CSV (nur Mods).
set-readytimes	Slash	–	Öffnet ein privates, interaktives Panel, um deine Raid-Verfügbarkeit pro Wochentag zu setzen (Ja/Nein togglen, HH:MM Start/Ende per Modal eintragen).
get-readytimes	Slash	day?, start?, end?, user?	Fragt ab, wer verfügbar ist — gesamt, für einen Wochentag oder gefiltert nach Zeitfenster. Mit user als reine Lese-Übersicht einer Person. Antworten sind ephemeral.

Zu /whois

Realm- und Charakternamen werden automatisch „geslugged" (Umlaute und Apostrophe berücksichtigt), sodass Blackmoore oder Tä'Lon wie eingegeben funktionieren. Die Abfrage nutzt den Classic-Profil-Namespace (profile-classic-<region>). Bei falschem Charakter oder Realm kommt eine „nicht gefunden"-Antwort. Das Itemlevel wird aus dem Equipment-Endpoint gelesen, sofern verfügbar.

Zu /get-readytimes

Die Abfrage ist rein lesend und ändert niemandes Zeiten. Verhalten je nach Argumentkombination:

Argumente	Ergebnis
keine	Gesamtübersicht: pro Wochentag, wer kann und sein Zeitfenster.
nur day	Alle, die an diesem Wochentag können, mit Zeitfenster.
day + start/end	Mitglieder, deren Fenster sich mit dem gewünschten überschneidet (Fenster über Mitternacht werden behandelt).
nur start/end	Pro Mitglied, welche Wochentage sich mit dem Zeitfenster überschneiden.
user	Reine Lese-Wochenübersicht dieses einzelnen Mitglieds.

Wochentage akzeptieren sowohl den englischen Schlüssel (monday) als auch die deutsche Bezeichnung (Montag). Zeiten akzeptieren HH:MM und Kurzformen wie 22, 915 oder 2230.

Konfiguration

GuildTools nutzt mehrere Config-Scopes plus Dateien auf der Platte für Abwesenheiten:

Scope	Key	Standard	Gesetzt durch
Global	blizz_client_id / blizz_client_secret	""	setblizzard
Global	blizz_token / blizz_token_expires_at	"" / 0	automatisch (Token-Cache)
Guild	wow_default_region	eu	set-wow-defaults
Guild	wow_default_realm	""	set-wow-defaults
Guild	last_seen	{}	Presence-Tracking (automatisch)
Member	je Wochentag {can, start, end}	False / None / None	set-readytimes

Abwesenheiten werden als absences_<guildid>.txt im Datenordner des Cogs gespeichert, eine ;-getrennte Zeile pro Eintrag.

Blizzard-Zugangsdaten — ENV zuerst

/whois holt seinen OAuth-Token ENV-first: Sind die Umgebungsvariablen BLIZZARD_CLIENT_ID und BLIZZARD_CLIENT_SECRET gesetzt, werden sie verwendet und der Token nur im Speicher gehalten. Andernfalls werden die über setblizzard (in der Config) gespeicherten Zugangsdaten genutzt und der Token zusätzlich persistiert. Tokens werden gecacht und kurz vor Ablauf erneuert.

Presence-Tracking

Wenn der Bot den Presences-Intent aktiviert hat, erfasst GuildTools den jeweils letzten Online-/Offline-Wechsel eines Mitglieds in last_seen. Dieser Zeitstempel erscheint in der export-userlist-CSV („Zuletzt online"). Ohne den Intent bleibt der Wert unbekannt.

Dashboard-Integration

Alle drei Cogs registrieren sich beim Laden sowohl beim AAA3A-Dashboard als auch beim PDC Web Dashboard. GuildTools bietet ein Widget:

Oberfläche	Mount	Berechtigung	Zweck
Widget „Erfasste Mitglieder"	Dashboard-Startseite (KPI, klein)	guild_member	Zeigt, wie viele Mitglieder einen Zuletzt-online-Zeitstempel haben.

Berechtigungen & Hinweise

Befehl(e)	Erforderliche Berechtigung
export-userlist, get-absence, set-wow-defaults	manage_guild (Slash-Default-Berechtigung)
setblizzard, clearblizzard	Bot-Owner
whois, add-absence, list-absence, set-readytimes, get-readytimes, export-poll	Jedes Gildenmitglied

Für export-userlist benötigt der Bot Mitglieder anzeigen (View Guild Members), um die vollständige Mitgliederliste zu lesen. export-poll setzt voraus, dass der Bot die Zielnachricht lesen und die Umfrage-Wähler abrufen kann. Die info.json von GuildTools deklariert keine Speicherung personenbezogener Daten, in der Praxis enthalten die Abwesenheitsdateien und die last_seen-Map jedoch User-IDs und Namen für die Gildenfunktionen.

Siehe auch: Installation · Dashboard-Integration · WoWTools · Start