A fast, button-driven math quiz game for Discord. Players join a lobby, answer multiple-choice questions under a timer, and rack up points based on correctness and speed.

Tech: Python + discord.py (v2.x) with UI Views/Buttons

• Lobby system with Join/Leave buttons and countdown timer
• Multiple-choice questions delivered via Discord buttons
• Timed rounds with configurable answer window
• Point splitting: each round awards a fixed pool of points split evenly among correct responders
• Difficulty + operation variety (addition, subtraction, multiplication, division, percentage, powers, square roots, algebra, patterns, time, geometry)
• Per-guild settings (channel + automatic mode) persisted to data/settings.json
• Clean embeds and friendly UX

• Python 3.10+ recommended
• A Discord application + bot token
• Bot permissions that allow it to read messages and send messages (and use interactions/buttons)

git clone <your-repo-url>
cd math-blitz
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

Copy the example env file and fill it in:

# Windows
copy .env.example .env

# macOS/Linux
cp .env.example .env

Edit .env:

DISCORD_BOT_TOKEN="your_bot_token_here"

# Optional (only used by the legacy cog.py version):
MATH_BLITZ_CHANNEL_ID=123456789012345678

# Optional settings (used by config/constants.py)
COMMAND_PREFIX=!
JOIN_WINDOW_SECONDS=30
MIN_PLAYERS=2
ROUNDS=10
TIME_TO_ANSWER=8
TIME_BETWEEN_QUESTIONS=3
POINTS_PER_CORRECT=100

Note: The modern bot flow stores per-guild channel settings in data/settings.json.
If you don’t set a channel, it will allow commands anywhere until an admin sets one.

python bot.py

You should see a log line like:

• Logged in as <botname> (id: ...)
• and the bot status will advertise !mb start (or your chosen prefix)

1. In your server, go to the channel you want to host the game in.
2. Run:

!mb start

3. Click Join during the lobby countdown.
4. When the game starts, answer each question by clicking one of the four buttons.
5. Final leaderboard is posted after the last round.

All commands are under mb (alias: math_blitz).

• !mb
  Shows help and current configuration (automatic mode, channel, etc.)

• !mb start (admin-only)
  Opens a lobby and starts a game after the countdown if players joined

• !mb status
  Shows whether automatic mode is enabled, which channel is set, and whether a game/lobby is active

• !mb automatic true|false
  Enables/disables auto-lobby behavior. If enabled and no channel is set, it defaults to the current channel.

• !mb setchannel #channel
  Locks Math Blitz commands to a specific channel.

Channel guard behavior:
If no channel is set, commands are allowed anywhere (for convenience). Once set, commands are restricted.

Each round has a pool of points:

• POINTS_PER_CORRECT (default: 100)

If N players answer correctly in a round, each gets:

• POINTS_PER_CORRECT / N

Ties are broken on the final leaderboard by:

1. Total points (descending)
2. Average response time (ascending)

These are read from .env (with defaults) via config/constants.py:

Guild settings stored in data/settings.json:

• automatic (bool): whether auto-lobby starts on bot ready and after games
• channel_id (int): the allowed channel for game commands

This bot uses:

• message_content intent (enabled in bot.py)
• members intent (enabled in bot.py)

In the Discord Developer Portal, enable Message Content Intent if needed.

Minimum Discord permissions typically needed:

• View channels
• Send messages
• Embed links
• Read message history (recommended)
• Use application commands / interactions (for buttons)

MIT. See LICENSE.