Trivium

Multiple-choice trivia rounds played through Discord buttons, with per-server leaderboards, per-user streaks, and optional admin-scheduled daily trivia.

A plugin for YourBot (formerly MMO Maid) — runs sandboxed in the platform and reacts to Discord interactions on installed servers.

What it does

Members run /trivia play to start a multiple-choice question with four answer buttons. The default mode is single-player (only the user who started the round can answer); an admin can switch a server to open mode where anyone can answer and the first-correct click wins. Points are awarded by difficulty (easy +10, medium +20, hard +30) and tracked per user in a server leaderboard. Streaks bump on every correct answer and break on wrong ones.

Admins can configure a daily trivia channel and UTC time with /trivia config. The production cron checks every five minutes and posts the one-hour open round at the first tick on or after the configured time (an event backstop may post it sooner). The first-correct answerer gets a +50 daily bonus on top of the difficulty award. /trivia daily shows the current day's result (or "not posted yet").

Questions come from Open Trivia DB (primary) with The Trivia API as fallback when OTDB is rate-limited, returns no results for a (category, difficulty) combo, or exhausts its session-token suppression window. The OTDB session token is per-server and reused across all categories — its 6-hour idle timeout naturally rolls suppression state on a quiet server.

Capabilities

This plugin lands in the Safe tier. Each capability is requested for a specific behavior:

Slash commands

/trivia config uses a KV-based admin allowlist (cfg:server.admin_user_ids). The Discord-based role check turned out unusable in v0.5.2 (the runtime's get_guild returns 404 and list_roles returns permissions=0 for every role), so the allowlist is the primary gate.

First-time setup: run any /trivia config sub-command (e.g. action:show). If no admin is configured yet, the denial message includes a "Claim Trivium admin (one-time)" button — click it to claim admin. After that, admin slash-command actions work normally for the seeded admin. Subsequent additions use /trivia config action:admin-add value:@user; action:admin-remove and action:admin-list are also available, and you can't remove the last admin.

Note on the click-to-claim button: the platform currently doesn't push manifest slash-command updates to Discord reliably, which makes the admin-bootstrap sub-command unreachable in some installs. The button bypasses that by living inline on the message rather than as a pre-registered slash choice. When the platform fixes propagation, the slash path becomes available too.

Known limitations (v1)

These are deliberate trade-offs documented up-front so server admins know what to expect:

1. The embed doesn't auto-reveal the answer on timeout. If no one clicks an answer button before the round's inflight TTL expires (default 20s for /trivia play, 1h for daily), the public embed stays as the original question. Production cron has a five-minute floor, so it cannot provide precise timeout handling for normal rounds; we trade silent timeout for reliable multi-tenant execution. Daily rounds with their 1-hour window almost always have a winner. (Note: when someone does click, the embed updates to reveal the answer and the buttons grey out — that path works fine.)
2. Some categories have no fallback. Open Trivia DB has 24 categories; The Trivia API covers ~10 of those cleanly. Categories like Video Games, Mythology, Anime & Manga don't have a Trivia API mapping — if OTDB is unavailable for them, /trivia play returns "Trivia sources are unavailable, try again in a few minutes."

Quick start (development)

# 1. Clone & install
git clone https://github.com/CubCadetXT1/mmo-maid-plugin-trivium.git
cd mmo-maid-plugin-trivium
python -m venv ../mmo-maid-plugin-trivium-venv          # keep .venv outside the repo
source ../mmo-maid-plugin-trivium-venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# 2. Local dev loop (hot-reload + mock host)
yourbot dev --watch

# 3. Tests
python -m pytest -q

# 4. Pre-flight validation (also runs in CI)
python scripts/validate_plugin.py .

Keep the virtualenv outside the repo (or use a name not on the validator's disallowed list) — validate_plugin.py flags a .venv/ at the repo root since it isn't supposed to ship in the upload zip.

Release process

Releases are tagged on main with semver tags (v1.2.3), which triggers .github/workflows/release.yml to validate, test, build the upload zip, and attach it to the GitHub release.

# 1. Bump manifest.json "version" and update CHANGELOG.md
# 2. Verify locally
make release          # validates, tests, builds dist/trivium-<version>.zip

# 3. Commit, tag, push
git commit -am "Release v1.2.3"
git tag v1.2.3
git push && git push --tags

The tag's version (v1.2.3 → 1.2.3) must match manifest.json's version field; CI rejects the release otherwise.

Submitting for review

The YourBot dev portal links this repo and pulls the latest tag for review. Review turnaround is typically 1–3 business days. The reviewer checks the manifest, scans for disallowed imports, validates SQL safety (Trivium uses no SQL), and re-prompts installed users on any tier shift.

Project structure

Runtime files (in the upload zip):

manifest.json          slash command schema + capabilities
__main__.py            entire plugin runtime
requirements.txt       pinned to yourbot-sdk >=0.7.1,<0.9.0

Repo-only (stripped at release time by scripts/build_release.py):

README.md              this file
LICENSE                MIT
CHANGELOG.md           version history
tests/                 pytest suite (~200 cases using MockContext)
.github/workflows/     CI + release automation
.gitignore .gitattributes Makefile requirements-dev.txt
scripts/               validate_plugin.py + build_release.py

License

MIT — see LICENSE.