Trivia & Games
Relevant source files
The following files were used as context for generating this wiki page:
The Trivia & Games module provides interactive entertainment features within the Red-DiscordBot environment. It primarily consists of a robust Trivia system allowing users to compete in quiz sessions based on structured data files. Additionally, the General module provides standard bot games such as Rock Paper Scissors, 8-ball, and coin flipping. These components integrate with the bot's core configuration and economy systems to manage scores, payouts, and server-specific settings.
Sources: redbot/cogs/trivia/trivia.py:68 redbot/cogs/general/general.py:46 redbot/cogs/trivia/session.py:22
Trivia System Architecture
The Trivia system manages competitive quiz sessions through a dedicated Trivia cog and a TriviaSession class. The Trivia cog handles management tasks, such as loading lists, modifying settings, and tracking leaderboards. Each active game runs in a TriviaSession instance, which controls the lifecycle of questions and answers within a specific Discord channel.
Sources: redbot/cogs/trivia/trivia.py:72-88, redbot/cogs/trivia/session.py:22
Session Lifecycle
A trivia session starts when a user invokes the trivia command with one or more categories. The system validates the category files, merges them if multiple are selected, and initializes a session.
The session tracks participant scores and updates the leaderboard upon completion. If enabled, winners receive a payout based on a multiplier and the bot's economy system.
Sources: redbot/cogs/trivia/trivia.py:347-384, redbot/cogs/trivia/trivia.py:603-620, redbot/cogs/trivia/session.py:22
Trivia Configuration and Schema
Trivia lists are stored as YAML files. Every list must adhere to a specific JSON schema to ensure compatibility.
Trivia List Schema
| Field | Type | Description |
|---|---|---|
AUTHOR | String | The creator of the trivia list. |
DESCRIPTION | String | A brief summary of the list content. |
CONFIG | Object | Local overrides for session settings. |
| Additional Keys | Array of Strings | Questions (keys) mapped to valid answers (arrays). |
Sources: schema/trivia.schema.json
Session Settings
Administrators configure trivia behavior via the triviaset command group.
| Setting | Default | Description |
|---|---|---|
max_score | 10 | Points required to win a session. |
delay | 15.0 | Seconds permitted to answer a question. |
timeout | 120.0 | Seconds of inactivity before a session stops. |
bot_plays | False | Whether the bot gains points for missed questions. |
reveal_answer | True | Whether to show the correct answer on timeout. |
payout_multiplier | 0.0 | Multiplier for economy credit rewards. |
use_spoilers | False | Hides revealed answers behind Discord spoilers. |
Sources: redbot/cogs/trivia/trivia.py:82-91, schema/trivia.schema.json:16-56
Leaderboards and Data Tracking
The Trivia cog tracks user statistics across sessions, including total wins, total games played, and cumulative scores. These stats are stored per guild and can be viewed via server-specific or global leaderboards.
Leaderboard Logic
The system generates leaderboards by calculating an average score (total_score / games) and sorting by priority fields.
General Games and Utilities
The General cog provides several deterministic and randomized games that do not require complex session management.
Rock Paper Scissors (RPS)
The RPS game uses an internal parser and an enumeration to determine winners based on user input.
Additional Game Commands
| Command | Description | Implementation |
|---|---|---|
roll | Rolls a random number between 1 and a specified limit. | Uses random.randint. |
flip | Flips a coin (Heads/Tails) or "flips" a mentioned user's name. | Uses random.choice and string translation. |
8ball | Returns a random response to a question ending in "?". | Uses a static list of 20 responses. |
choose | Picks a random option from a provided list. | Uses random.choice. |
Sources: redbot/cogs/general/general.py:73-114, redbot/cogs/general/general.py:157-164
Custom Trivia Management
Bot owners can extend the Trivia system by uploading custom YAML files. The system performs the following validations before saving:
- Reserved Name Check: Prevents overwriting core commands or internal lists.
- Syntax Validation: Ensures the file is valid YAML.
- Schema Validation: Validates the content against
TRIVIA_LIST_SCHEMA. - File System Safety: Checks if the filename is supported by the host OS.
Sources: redbot/cogs/trivia/trivia.py:646-708, tests/cogs/test_trivia.py:18-35
Conclusion
Trivia & Games provides a layer of interactive engagement for Discord guilds. The Trivia system is highly extensible through its schema-based YAML loading and offers competitive tracking through detailed leaderboards. Simpler games in the General module provide quick interactions, leveraging standard Python randomization to ensure varied outcomes. Together, these systems utilize Red's core Config and Bank APIs to provide a seamless user experience.
Sources: redbot/cogs/trivia/trivia.py:72, redbot/cogs/general/general.py:46