Blockbot

Blockbot is a Discord bot, written in Python, that is maintained by the Redbrick Webgroup. This project uses hikari, an opinionated microframework, to interface with the Discord API. hikari-arc is the command handler and hikari-miru is the component handler of choice.

File Structure

All bot files are under src/.

• bot.py
  • Contains the bot configuration and instantiation (e.g. loading the bot extensions).
• extensions/
  • Contains extensions (files) that are loaded when the bot is started. Extensions are a way to split bot logic across multiple files, commonly used to group different features. Extensions can contain plugins, command, event listeners and other logic. Read more.
• examples/
  • Contains example extensions with commands, components and more as reference for developers.
• config.py
  • Configuration secrets and important constants (such as identifiers) are stored here. The secrets are loaded from environment variables, so you can set them in your shell or in a .env file.
• utils.py
  • Utility functions are stored here, that can be reused across the codebase.

Installation

Tip

Docker Compose for local development is highly recommended. This is similar to how it is deployed on Redbrick.

Discord Developer Portal

As a prerequisite, you need to have an application registered on the Discord developer portal.

1. Create a Discord application here.
2. Go to "OAuth2 > URL Generator" on the left sidebar, select the bot and applications.commands scopes, and then select the bot permissions you need (for development, you can select Administrator).
3. Go to the generated URL and invite the application to the desired server.

Bot Token

1. Open the application on the Discord developer portal.
2. Go to "Bot" on the left sidebar, click Reset Token.
3. Copy the newly generated token.

Running from source (deprecated)

1. Fork, git clone and cd into the blockbot repository.

   Tip

   Read the contributing docs for more information on using Git and GitHub.

2. It is generally advised to work in a Python virtual environment:

   Bash

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Rename .env.sample to .env inside the repo folder and fill in the environment variables with your secrets. e.g.:

   Text Only

   TOKEN=<Discord bot token here>
   

4. Run pip install -r requirements.txt to install the required packages.

5. Start the bot by running python3 -m src.

Running with Docker Compose

1. Fork, git clone and cd into the blockbot repository.

   Tip

   Read the contributing docs for more information on using Git and GitHub.

2. Rename .env.sample to .env inside the repo folder and fill in the environment variables with your secrets. e.g.:

   Text Only

   TOKEN=<Discord bot token here>
   

3. Run the compose.yaml file: docker compose up --build

Library Resources

• hikari Documentation
• hikari Examples
• hikari-arc Documentation
• hikari-arc Examples
• hikari-miru Documentation
• hikari-miru Examples

Usage Guides

hikari

• Getting Started - first steps of using hikari
• Events - understanding receiving events from Discord with hikari

hikari-arc

• Getting Started - first steps of using hikari-arc
• Guides - various guides on aspects of hikari-arc

hikari-miru

• Getting Started - first steps of using hikari-miru
• Guides - various guides on aspects of hikari-miru

FAQ

What's the difference between hikari, hikari-arc and hikari-miru?

• hikari - the Discord API wrapper. Can be used to, for example:
  • add roles to server members
  • create threads
  • send individual messages
  • fetch guild (server) information
  • update member roles (add role, remove role, edit roles)
  • listen for events from Discord, like message edits
• hikari-arc - the command handler. Can be used to:
  • create application commands (slash, message & user commands)
  • respond to command interactions
• hikari-miru - the component handler. Can be used to:
  • create message components (buttons, select menus & modals)
  • respond to component interactions (button clicks, select menu selections & modal submissions)

Why use a hikari.GatewayBot instead of a hikari.RESTBot?

TL;DR: RESTBots do not receive events required for some blockbot features (e.g. starboard), so GatewayBot must be used instead.

GatewayBots connect to Discord via a websocket, and Discord sends events (including interactions) through this websocket. RESTBots run a web server which Discord sends only interactions to (not events) via HTTP requests. These events are required for specific blockbot features, like starboard (which uses reaction create/remove events).

Further reading: https://arc.hypergonial.com/getting_started/#difference-between-gatewaybot-restbot

What's the difference between hikari.GatewayBot, arc.GatewayClient and miru.Client?

• hikari.GatewayBot is the actual Discord bot. It:
  • manages the websocket connection to Discord
  • sends HTTP requests to the Discord REST API
  • caches information received in events sent by Discord
• arc.GatewayClient adds additional functionality to hikari.GatewayBot for:
  • splitting the bot across multiple files using extensions
  • grouping commands using plugins
  • easily creating and managing commands and command groups
  • accessing objects globally (in any extension, plugin or command) using dependency injection (e.g. a database connection)
• miru.Client adds additional functionality to hikari.GatewayBot for:
  • creating message components using views
  • creating modals
  • creating navigators and menus using views

Do's and Don'ts

• Always try to get data from the cache before fetching it from the API.

  Python

  # command example
  async def command(ctx: arc.GatewayContext) -> None:
      user = ctx.client.cache.get_user(123)
      if not user:
          user = await ctx.client.rest.fetch_user(123)