GuildTools

GuildTools

🌐 English · Deutsch

GuildTools is a toolbox for (WoW) Discord guilds. It bundles three cogs that ship together in one package: member/poll exports, an absence tracker, World-of-Warcraft /whois character lookups via the Blizzard API, and a private raid availability ("ready-times") planner. Most commands are slash-only and answer ephemerally (only you see the reply). The package wires itself into the PDC Web Dashboard automatically. Author: pd-codes · requires 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] is your bot's prefix. See Installation for the full Downloader walkthrough. Because almost every command is slash-only, running [p]slash sync once after loading is required.

Installing GuildTools actually loads three cogs at once: GuildTools (exports, absences, whois), ReadyTimes (availability planner) and GuildToolsPollExport (poll CSV export). For the /whois lookup you also need Blizzard API credentials (see below).

The Blizzard token request uses aiohttp. It ships with Red; if it is missing, /whois will report that aiohttp is not installed.

Commands

All commands except setblizzard / clearblizzard are native application (slash) commands. The two credential commands are prefix, owner-only.

Command	Type	Parameters	What it does
whois	Slash	charname, realm?	Shows WoW character info (level, class, race, faction, guild, item level, last login) for a Classic character via the Blizzard API. Falls back to the guild's default realm/region when realm is omitted.
set-wow-defaults	Slash	region (eu/us/kr/tw), realm	Sets the default region + realm used by /whois for this guild.
setblizzard	Prefix (owner)	client_id, client_secret	Stores Blizzard API credentials in Config as a fallback when environment variables are not used. Clears any cached token.
clearblizzard	Prefix (owner)	–	Removes the stored Blizzard credentials and cached token from Config.
export-userlist	Slash	–	Exports all guild members to a ;-separated CSV (UTF-8 BOM): UserID, username, server nickname, roles, joined date, last-seen timestamp. Sent ephemerally.
export-poll	Slash	poll, mode (Key-Oriented / Value-Oriented)	Exports a native Discord poll to a ;-separated CSV. poll has autocomplete over recent polls in the channel; you can also paste a message ID or link.
add-absence	Slash	von, bis	Records an absence (start/end date). Accepts DD-MM-YYYY, DD.MM.YYYY or DD/MM/YYYY. Max. 365 days; end must not be before start. The confirmation is posted publicly.
list-absence	Slash	–	Lists your own absences as an ephemeral embed.
get-absence	Slash	–	Exports all recorded absences for the guild as a CSV (mods only).
set-readytimes	Slash	–	Opens a private, interactive panel to set your raid availability per weekday (toggle Yes/No, enter HH:MM start/end via a modal).
get-readytimes	Slash	day?, start?, end?, user?	Queries who is available — overall, for one weekday, or filtered by a time window. Pass user for a single read-only overview. Replies are ephemeral.

About /whois

Realm and character names are slugified automatically (umlauts and apostrophes handled), so Blackmoore or Tä'Lon work as typed. The lookup hits the Classic profile namespace (profile-classic-<region>). If the character or realm is wrong you get a "not found" reply. Item level is read from the equipment endpoint when available.

About /get-readytimes

The query is purely read-only and never edits anyone's times. Behaviour by argument combination:

Arguments	Result
none	Full overview: for every weekday, who can and their window.
day only	Everyone available on that weekday, with their time window.
day + start/end	Members whose window overlaps the requested window (overnight windows that wrap past midnight are handled).
start/end only	Per member, which weekdays overlap the time window.
user	Read-only weekly overview of that single member.

Weekdays accept both the English key (monday) and the German label (Montag). Times accept HH:MM and short forms like 22, 915 or 2230.

Configuration

GuildTools uses several Config scopes plus on-disk files for absences:

Scope	Key	Default	Set by
Global	blizz_client_id / blizz_client_secret	""	setblizzard
Global	blizz_token / blizz_token_expires_at	"" / 0	auto (token cache)
Guild	wow_default_region	eu	set-wow-defaults
Guild	wow_default_realm	""	set-wow-defaults
Guild	last_seen	{}	presence tracking (auto)
Member	per-weekday {can, start, end}	False / None / None	set-readytimes

Absences are stored as absences_<guildid>.txt in the cog's data folder, one ;-separated row per entry.

Blizzard credentials — ENV first

/whois acquires its OAuth token environment-first: if the env vars BLIZZARD_CLIENT_ID and BLIZZARD_CLIENT_SECRET are set, they are used and the token is kept only in memory. Otherwise the credentials stored via setblizzard (in Config) are used and the token is additionally persisted. Tokens are cached and refreshed shortly before expiry.

Presence tracking

When the bot has the presences intent enabled, GuildTools records each member's last online/offline transition into last_seen. This timestamp appears in the export-userlist CSV ("last online"). Without the intent, the value stays unknown.

Dashboard integration

All three cogs register with both the AAA3A Dashboard and the PDC Web Dashboard on load. GuildTools exposes one widget:

Surface	Mount	Permission	Purpose
Widget "Tracked members"	Dashboard home (KPI, small)	guild_member	Shows how many members have a recorded last-seen timestamp.

Permissions & notes

Command(s)	Required permission
export-userlist, get-absence, set-wow-defaults	manage_guild (slash default permission)
setblizzard, clearblizzard	Bot owner
whois, add-absence, list-absence, set-readytimes, get-readytimes, export-poll	Any guild member

For export-userlist the bot needs View Guild Members to read the full member list. export-poll requires the bot to be able to read the target message and fetch poll voters. GuildTools' info.json declares no personal-data storage, but in practice the absence files and last_seen map do contain user IDs and names for guild functionality.

See also: Installation · Dashboard Integration · WoWTools · Home