A Discord bot that digests daily puzzle-game results posted in a channel into a single, auto-updating leaderboard embed.
How score calculation works: see SCORING.md.
- Watches a designated channel for raw game result pastes.
- Parses results for: Wordle, Worldle, Flagle, Globle, Travle, Metazooa, Redactle, Songless, Centumth, Roughly, Magnitudle, Majority, Trivmount, Thursday Thirty, Songspot, Regionle, Mathle, History in Order, Tradle, Chessle (T30 is weekly and only appears in
/missingon Thursdays; pastes still count any day) (lower rank score always wins; points games like Centumth store negated scores). - Deletes raw score pastes, confirms with a short self-destructing acknowledgement incl. current placement and daily standing, and updates one consolidated daily leaderboard embed per day. Any message without a recognized score is left untouched, including announcements and banter mentioning game names.
- New daily boards are pinned automatically; older digest boards from the same channel are unpinned when the new one is posted (other pins and yesterday's wrap are untouched). Requires the Manage Messages permission.
- When the first board of a new day appears, publishes yesterday's locked wrap above it: player turnout, playful easiest/hardest verdicts from comparable scored games only, final standings, and one playful placement comment (randomly a winner, silver, mid-pack, second-last or last). Skipped on days with no scores; posted once per date.
- Logs every successfully parsed message to the
ingest_logtable (raw text + user) – the audit trail and data source for/undo. Run with--debug(orDEBUG_LOG=1) to also dump them to the console. - Easter egg: exact integer results of
42,67,69, or420get a public, curated gif reaction (de-duplicated per paste, ignoring puzzle ids and dates). The gif is uploaded as an attachment so it renders reliably; if retrieval fails, the bot falls back to posting the direct link. Any broken/unformatted score text stays untouched. - Awards daily points per game (🥇 = 3 pts · 🥈 = 2 pts · 🥉 = 1 pt, ties share placement; games with ≥2 players) plus a standings summary on the board.
- Slash commands:
/h2h <opponent> [player1]– head-to-head record across all shared puzzles./stats [game] [period] [user] [public]– all-time games played, solve rate, golds 🥇, personal bests, play streaks, and prison history; withgame, shows a private 10- or 20-day fixed-attempt or score-history chart unlesspublicis enabled./week– seven-day recap: group leaderboard, turnout, and game difficulty./export [days]– admin-only CSV export for the last N days (default 7, max 31), privately attached with formula-safe cells./board– re-posts today's board at the bottom of the channel./wrap– posts yesterday's wrap on demand (once per date; skips empty days)./layout_switch– toggles the channel's board between compact (three games per row) and wide (one line per game)./games– lists supported games with short descriptions and links (private reply)./missing– private (ephemeral) checklist: your games still to play today, with links./undo– removes the scores from your most recent post today (self-serve, ephemeral reply)./forfeit game:…– records a manual DNF for games with no "give up" share text (e.g. Globle). Puzzle id inferred from today's results; no points./remove game:… puzzle_id:… [user] [date]– precise entry removal, requires Manage Messages. Deletions are announced publicly (transparency) and logged asadmin_remove.
-
Python 3.10+ (uses
X | None-style annotations viastr | Nonereturn types and built-in generics).pip install -r requirements.txt
-
Create a Discord application/bot at https://discord.com/developers/applications.
- Enable the Message Content and Server Members privileged intents.
- Invite it with
bot+applications.commandsscopes and permissions: Send Messages, Attach Files (for curated gif uploads), Manage Messages (to delete raw pastes), Embed Links, Read Message History.
-
Set environment variables:
Variable Required Description DISCORD_BOT_TOKENyes Your bot token. Keep it secret. SCORE_CHANNEL_IDno Channel to watch. If unset, watches all. BOT_TZno Timezone for the daily cutoff, e.g. Europe/Warsaw. Defaults to server-local time.DISABLED_GAMESno Comma-separated games to turn off, e.g. Wordle. Hidden from the board,/gamesand/missing; on by default.PRISON_ENABLEDno 1to enable first-attempt prison on Globle, Regionle, Metazooa, and Redactle. Jailed players stay on the leaderboard but earn no points that day. Opt-in, disabled by default. -
Run:
python main.py
Scores are stored in a local
scores.dbSQLite file (created automatically).
main.py → entry point: bot instance + wiring only
config.py → env vars (token, channel, BOT_TZ, DISABLED_GAMES, PRISON_ENABLED, DEBUG_LOG), date helpers
games.py → game registry (icons/links/descriptions), GRADED_GAMES, result-hint regex
db.py → SQLite schema + ingest log
parsers.py → parse_all_games: one share-text -> result dicts (the file that grows per game)
embeds.py → daily board + /missing checklist builders
stats_charts.py → reusable game-history models, loaders, and chart renderers
handlers.py → on_message ingest flow + daily board maintenance
commands.py → slash commands, attached via register(bot)
test_parsers.py → fixture suite: python test_parsers.py (run it before/after parser changes)
Never commit your bot token. This project reads it from DISCORD_BOT_TOKEN; there is no token in the source. If you previously shared or committed a real token anywhere, regenerate it immediately.