QuizBot

Open source Discord bot for quizzes and quest-like events.

Installation

Dependencies

• Python 3.11+
• MongoDB
• Redis/Valkey or Memcached (used for caching, optional)
• Git (only if installing from source)

Installation from release

1. Download the release archive from Releases
2. Unpack the archive to a directory of your choice
3. Go to the project's directory
4. Create a virtual environment: python3 -m venv .venv
5. Activate the virtual environment:
   • Linux: source .venv/bin/activate
   • Windows (cmd): .venv/bin/activate.bat
   • Windows (PowerShell): .venv/bin/activate.ps1
6. Install requirements: pip install -r requirements.txt
7. Copy example config to a real file: cp config_example.json config.json
8. Configure the bot (see Configuration)
9. Start the bot: python main.py
10. The bot can be stopped by a keyboard interrupt (Ctrl+C) and a virtual environment can be deactivated using deactivate

Installation from source

1. Clone the repository: git clone https://git.end-play.xyz/profitroll/QuizBot.git
2. Go to the project's directory: cd QuizBot
3. Continue from step 4 of Installation from release

Configuration

{
    // Bot's default locale. Based on file name from locale/
    "locale": "en-US",
    // Debug mode setting
    "debug": false,
    // Bot's config
    "bot": {
        // Discord ID(s) of bot's owner(s)
        "owners": [
            0
        ],
        // Discord ID(s) of the debug guild(s)
        "debug_guilds": [
            0
        ],
        // Bot's token
        "bot_token": "",
        // Bot's timezone
        "timezone": "UTC",
        // Bot's status activity
        "status": {
            // Whether activity is enabled
            "enabled": true,
            // Type of the activity. Can be: "playing", "watching", "listening", "streaming", "competing" or "custom"
            "activity_type": "playing",
            // Text of the activity
            "activity_text": "The Game Of Life"
        }
    },
    // Database connection
    "database": {
        // User name for database connection. null if without auth
        "user": null,
        // User password for database connection. null if without auth
        "password": null,
        // Database host
        "host": "127.0.0.1",
        // Database port
        "port": 27017,
        // Database name
        "name": "quiz_bot"
    },
    // Cache connection
    "cache": {
        // Type of caching engine. Can be: "memcached", "redis" or null
        "type": null,
        // Memcached connection. Only used if cache type is "memcached"
        "memcached": {
            // Memcached URI
            "uri": "127.0.0.1:11211"
        },
        // Redis connection. Only used if cache type is "redis"
        "redis": {
            // Redis URI
            "uri": "redis://127.0.0.1:6379/0"
        }
    },
    // Emojis used by guilds that prefer emoji messages
    "emojis": {
        // Markdown of a Discord emoji to be used for wrong guesses
        "guess_wrong": null
    }
}

Upgrading

Upgrading from release

Installing over the older version is not supported. Fresh installation is necessary to prevent data corruption.

1. Make a backup of the project's directory. Some of the old files will be reused
2. Follow the Installation from release from the beginning and stop before 7th step
3. Copy file config.json and directory data from the backup you made into the new installation's directory
4. While still in the virtual environment, migrate the database: python main.py --migrate

After these steps are performed, the bot is ready to be started and used.

Upgrading from source

1. Make a backup of the project's directory
2. Go to the project's directory
3. Update the project: git pull
4. Activate the virtual environment:
   • Linux: source .venv/bin/activate
   • Windows (cmd): .venv/bin/activate.bat
   • Windows (PowerShell): .venv/bin/activate.ps1
5. Migrate the database: python main.py --migrate

After these steps are performed, the bot is ready to be started and used.

Usage

1. Invite the bot to your server with permissions 137707834448 and applications.commands scope.
   You can also use the following URL template to invite your bot after replacing CLIENT_ID with you bot's client ID:
   https://discord.com/oauth2/authorize?client_id=CLIENT_ID&permissions=137707834448&integration_type=0&scope=applications.commands+bot
2. Go to "Server Settings > Integrations > QuizBot" and disable access to admin commands for you default role.
   Only admins should have access to following commands: /config, /event, /stage and /user.
   Allowing access to /status is not recommended, however won't do any harm if done so.
3. Configure bot for usage on your server using /config set providing all the necessary arguments.
   Timezones are compatible with daylight saving time (e.g. CET will be interpreted as CEST during daylight saving).