Royal PB Bot

A Discord slash-command bot for tracking clan personal bests (PBs) in Old School RuneScape. Members submit kill screenshots, staff approve them in a review queue, and the bot maintains a navigable leaderboard channel, with optional blert.io verification for supported bosses, record-break pings, monthly digests, and an admin toolset.

What it does

• Submission flow. A member runs /pb submit with a screenshot and a time (or level). The bot posts the screenshot to a staff review channel with Approve / Reject buttons and gives the submitter an ephemeral receipt (only they see it; the submit channel itself stays clean). The bot does not DM users on decision; the result is visible in the review-message footer and, on approval, the announcements channel (an admin tells a submitter directly if they need to re-submit). The submit channel keeps a single pinned "how to submit" message. An admin pins it manually from the text in this page (see Submit channel pinned message); it is not bot-managed. An edit window (5 minutes) lets a member replace a pending submission without cluttering the queue.
• Review flow. Staff approve or reject from the review channel. Approvals go to an announcements channel as a rich embed (image, roster mentions, proof link); rejections open a reason modal and post a red embed. The bot detects first-of-category approvals and labels them.
• Leaderboard. A dedicated channel gets a Master Board (overview + navigation buttons) and a detail message with a Select menu. Anyone can pick a boss from the select for an ephemeral ranked view; /pb top posts a public top-5; /pb history shows the record progression; /pb lookup shows a player's best per category with their clan-wide rank.
• Record-break pings. When a record that has stood longer than a configurable threshold falls, the bot pings a role (e.g. @records).
• Monthly digest. On the 1st of each month the bot posts a "records set last month" summary to the announcements channel.
• Admin toolset. Configure channels and roles, add/edit/remove bosses and categories, export the whole sheet to .xlsx, prune rejected/reverted submissions to an archive, force a leaderboard refresh, and re-sync the sheet with the built-in boss seed.

Requirements

• Python 3.11+. Uses modern Python features; older versions will not work.
• A Discord bot application with the applications.commands and bot scopes.
• A Google Cloud service account with the Sheets API enabled, and a Google Sheet shared with that service account.
• A persistent host (the bot holds a gateway connection; if it restarts, persistent views let old Approve/Reject buttons and the leaderboard Select menu keep working).

Python dependencies

discord.py>=2.4
gspread>=6.0
openpyxl>=3.1
python-dotenv>=1.0
aiohttp            # ships with discord.py, listed for clarity

Install:

pip install discord.py gspread openpyxl python-dotenv

Setup

Google service account + sheet

1. In Google Cloud Console, create a project and enable the Google Sheets API.
2. Create a service account and download its JSON key. Save it next to pbbot.py as google-key.json (the filename is configurable; see Configuration file).
3. Create a Google Sheet. Copy its ID from the URL: https://docs.google.com/spreadsheets/d/<SHEET_ID>/edit.
4. Share the sheet with the service account's email (found in the JSON under client_email) as an Editor.
5. The bot creates the config, bosses, categories, and submissions tabs on first run. You do not need to pre-build them. The submissions_archive tab is created on first /pbadmin prune.

Discord application + invite

1. Create an application at the Discord Developer Portal. Add a Bot user and copy its token.
2. Under OAuth2 → URL Generator, select scopes bot and applications.commands. Give the bot at minimum these permissions:
   • View Channels, Send Messages, Embed Links, Attach Files, Read Message History
   • Manage Messages (for leaderboard refresh: deletes + re-sends)
   • Use External Emojis (optional, for medal emojis)
3. Open the generated URL and invite the bot to your clan server.
4. Note the guild ID of your clan server (Developer Mode → right-click server → Copy ID). Setting DEV_GUILD_ID makes slash commands sync instantly during setup.

Configuration file

Create a .env file next to pbbot.py:

DISCORD_TOKEN=<bot token>
GOOGLE_KEYFILE=google-key.json
SHEET_ID=<your sheet id>
DEV_GUILD_ID=<your clan guild id>   # optional, for instant slash sync

DEV_GUILD_ID is optional. If set, slash commands sync to that guild on startup (instant). If unset, they sync globally (can take up to an hour to propagate). Either way commands work in every server the bot is in.

First run

python pbbot.py

On startup the bot:

1. Opens the Google Sheet and creates the four base tabs if missing, seeds the boss/category list from the built-in seed, and seeds the Hallowed Sepulchre meme banner URL into the config tab. This is safe to run on every restart: it only adds missing bosses/categories, never removes anything (removals are explicit, via /pbadmin boss remove).
2. Registers persistent views (the Approve/Reject buttons on old review messages and the Select menu on the old leaderboard detail message keep working after a restart).
3. Syncs slash commands (guild if DEV_GUILD_ID is set, else global).
4. Starts the background loops: cache warmup every ~45s and the monthly digest checker every 15 minutes.

You'll see five print() lines on startup. That is the bot's only logging. There is no log file.

Post-startup checklist

After the bot is online and you see the startup lines, run these once:

1. /pbadmin set-channel submit <your submit channel>: binds the member submit channel.
2. /pbadmin set-channel review <your staff review channel>: binds the staff review queue.
3. /pbadmin set-channel announce <your announcements channel>: binds the approval announcements channel.
4. /pbadmin set-channel leaderboard <your leaderboard channel>: binds and immediately posts the Master Board + detail message + Hallowed Sepulchre meme banner.
5. /pbadmin set-role <your staff role>: binds the staff role (used for review-queue gating and record-break pings).
6. Restrict the /pbadmin command group to your staff role in Server Settings → Integrations → Royal PB Bot.
7. Pin the how-to message in the submit channel manually: copy the text from Submit channel pinned message below, post it, and right-click → Pin.
8. (Optional) /pbadmin record-ping <role> <days>: set the role to ping when a record standing longer than days falls.

Commands

There are two command groups: /pb (everyone) and /pbadmin (admins). The admin group also has subgroups /pbadmin boss and /pbadmin category.

Member commands: /pb

/pb submit

boss         Boss (autocomplete)                          required
category     Category (autocomplete, after boss)          required
time         Kill time e.g. 2:31.40, or a level e.g. 167  required
proof        Screenshot of the kill (image attachment)    required
teammate_2 … teammate_8   Teammates (you are #1 automatically)
blert_url    blert.io recording link (blert-supported bosses only)
notes        Anything staff should know

Must be run in the submit channel. Gives an ephemeral receipt (only you see it; the channel stays clean), posts the screenshot to the review queue with Approve/Reject buttons. The bot does not DM you on decision: watch the announcements channel for approved records (an admin will tell you directly if you need to re-submit). A 5-minute edit window lets you resubmit to replace a pending submission (the old review message is deleted). A duplicate guard blocks re-submitting the exact same boss+category+time+roster after approval. The submit channel's pinned how-to message (pinned by an admin) at the top explains the fields; see below for the text to pin.

Submit channel pinned message

The bot does not create or manage a pinned message in the submit channel. An admin posts the text below and pins it manually (right-click the message → Pin). This keeps the instructions at the top of the channel so members landing there always see how to submit. Copy the block verbatim:

**How to submit a personal best**

Use the `/pb submit` command in this channel. You'll get a private (ephemeral) reply confirming it's in the staff review queue — the channel itself stays clean.

**Fields:**
• **boss** — start typing and pick from the list (e.g. `Theatre of Blood`)
• **category** — pick after choosing the boss (e.g. `Solo`, `Duo`)
• **time** — kill time for time-based categories. Formats: `2:31.40`, `1:02:31`, `5m19s`, `90s`. Use a plain integer for level-based categories (e.g. `167`)
• **proof** — screenshot of the kill (required, image only)
• **teammate_2 … teammate_8** — for raids; you're #1 automatically
• **blert_url** — blert.io recording link, only for blert-supported challenges
• **notes** — anything staff should know

The bot does not DM you on decision — watch the announcements channel for approved records (an admin will tell you directly if you need to re-submit).

Tips: re-submitting within 5 minutes replaces your pending submission (handy for typos). An identical time + roster to an existing approved record is refused as a duplicate.

/pb top

boss   Boss (autocomplete)   required

Posts a public top-5 ranked embed for that boss (visible to the whole channel). Medal emojis on spots 1–3 (🏆 🥈 🥉).

/pb history

boss   Boss (autocomplete)   required

Posts a public record progression for that boss with relative timestamps ("2 days ago", "1 hour ago"). The current champion is crowned with 🏆.

/pb lookup

player   Discord user (autocomplete shows current members)   required

Posts a public embed of that player's best approved record per category, with their clan-wide rank. Footer shows their Discord user ID. Categories where they are #1 get 🏆.

Admin commands: /pbadmin

Setup

Records management

Boss management: /pbadmin boss

Category management: /pbadmin category

Google Sheets schema

The bot owns four tabs (plus a fifth created on demand). All tabs are created on first run; you do not need to pre-build them. You can browse and edit the sheet directly at any time. The bot caches reads for up to 60 seconds, so in-sheet edits appear within a minute or after /pbadmin refresh.

config: key/value pairs

bosses

categories

submissions

submissions_archive

Same columns as submissions. Created on first /pbadmin prune. Rows moved here are deleted from submissions. The archive append is idempotent: re-running prune after a partial failure skips rows whose ID is already in the archive.

How the leaderboard works

The leaderboard channel contains three things, posted by /pbadmin set-channel leaderboard (and re-posted by /pbadmin refresh):

1. The Master Board: an overview embed plus Prev/Next navigation buttons. The overview lists the currently selected boss group (one of 17 pre-defined groups, e.g. [Raids] Theatre of Blood, [DT2] Desert Treasure 2 (all variants), [Misc] …). Navigation cycles through the 17 groups.
2. The detail message: a Select menu. Anyone can pick a boss from the dropdown for an ephemeral ranked view (only they see it; the shared detail message does not change). This is the main way members browse rankings.
3. The Hallowed Sepulchre meme banner: a fixed embed with an image and a fake "records" entry. The meme's title, credit line, and banner image URL all live in the config tab (sepulchre_meme_title, sepulchre_meme_credit, sepulchre_meme_banner_url); editing any of those rows updates the meme with no restart. The shipped defaults are generic and non-identifying (no Discord user IDs or personal handles). An admin pastes a clan-specific credit (e.g. 🏆 - <@&ROLE_ID> to ping a role) and a durable image URL on first run. The banner URL is intentionally empty by default (signed Discord CDN URLs expire within ~24 h); until an admin sets it, the meme renders without an image.

The Master Board and the detail message are persistent: they survive bot restarts. The bot reuses the existing messages on restart (does not re-send) unless /pbadmin refresh is run.

Spot formatting: 🏆 on rank 1, 🥈 on rank 2, 🥉 on rank 3. Times render as M:SS.cc (e.g. 2:31.40); levels render as Level N. The [proof] link in each spot points to the announcements message (rich context) when available, falling back to the bare proof image URL.

blert.io verification

Some bosses are flagged as blert-supported in the built-in seed (ToB, ToB HM, TFA, Doom of Mokhaiotl, Fortis Colosseum, The Inferno). When a submitter supplies a blert_url for one of these bosses, the bot:

1. Fetches the blert.io recording metadata.
2. Verifies the boss and participants match what was submitted.
3. Stores the result in blert_status (verified, mismatch, unreachable) and blert_detail on the submission row.
4. Shows the verification status on the review embed so staff can see it before approving.

Background jobs

Two background loops start with the bot:

• Cache warmup: every ~45s, re-reads the sheet tabs so the bot's in-memory cache stays fresh. The first iteration runs immediately so the cache is warm before the first command. This is why autocomplete stays responsive even during a large prune.
• Monthly digest: every 15 minutes, checks whether the calendar month has rolled over since the last digest. If it has, builds a "records set last month" summary and posts it to the announcements channel, then records the month in the config tab.

Both loops log failures to stdout and continue; a transient sheet error does not crash them.

Troubleshooting