# QuizBot

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

## Installation

### Dependencies

- [Python 3.11+](https://www.python.org)
- [MongoDB](https://www.mongodb.com)
- [Redis](https://redis.io)/[Valkey](https://valkey.io) or [Memcached](https://memcached.org) (used for caching,
  optional)
- [Git](https://git-scm.com) (only if installing from source)

### Installation from release

1. Download the release archive from [Releases](https://git.end-play.xyz/profitroll/QuizBot/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](#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](#installation-from-release)

## Configuration

```json
{
    // 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](#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).