Getting Started

Command Line

There’s a few available things from the commandline (CMD) that you can do with VoxelBotUtils. You can run the module either as python3 -m voxelbotutils, or it’s registered as a plain voxelbotutils to your PATH on install that you can run instead.

  • $ voxelbotutils create-config

    • bot - this creates a set of bot config files

    • website - this creates a set of website config files

    • all - this creates a set of all available config files

  • $ voxelbotutils run-bot

    • [bot_directory] - the directory that the bot files are located in; defaults to .

    • [config_file] - the path to the config file to use; defaults to config/config.toml

    • --min [amount] - the minimum shard ID for this instance

    • --max [amount] - the maximum shard ID for this instance

    • --shardcount [amount] - the number of shards that the bot should identify as (not the number of shards for this instance)

    • --loglevel [level] - the logging.Logger loglevel that you want to start the bot with

  • $ voxelbotutils run-interactions

    • [bot_directory] - the directory that the bot files are located in; defaults to .

    • [config_file] - the path to the config file to use; defaults to config/config.toml

    • --host - the host that you want to run the webserver with.

    • --port - the port that you want to run the webserver on.

    • --path - the path that the route should be added as; defaults to /interactions

    • --connect - if you want to connect your bot to the gateway as well as running the interactions webserver; shards will be automatically calculated and intents will be set to none.

    • --loglevel [level] - the logging.Logger loglevel that you want to start the bot with

  • $ voxelbotutils commands

    • [action] - the action you want to take for your commands - this can be add or remove

    • [bot_directory] - the directory that the bot files are located in; defaults to .

    • [config_file] - the path to the config file to use; defaults to config/config.toml

    • --guild [guild_id] - if you want to perform the action for a specific guild, you can specify its ID here

Getting Started With Bots

To get started you’ll first want to make a config file. Fortunately, making one is pretty easy, and can be done via CMD.

$ voxelbotutils create-config bot

Doing this will make a few files and folders:

  • cogs/ping_command.py - a simple base class that you can copy/paste to build new classes

  • config/config.toml - this is your bot’s configuration file

  • config/config.example.toml - this is a git-safe version of your configuration file; you can commit this as you please

  • config/database.pgsql - this file should contain your database schema; it’ll be pushed to your bot’s database at every startup

  • .gitignore - a default Gitignore file to ignore your configuration file

Running the Bot

Running the bot is also available via the package at a CMD level.

$ voxelbotutils run-bot

The information in the bot’s config/config.toml file will be used to run it, as well as automatically loading any files found in the cogs/ folder, should they not start with an underscore (eg the file cogs/test.py would be loaded, but cogs/_test.py would not).

If your database is enabled when you start your bot, the information found in the config/database.pgsql will be automatically run, so make sure to write your tables as CREATE TABLE IF NOT EXISTS and put your enum creations in an if statement -

DO $$ BEGIN
   CREATE TYPE my_type AS ENUM ('Example 1', 'Example 2');
EXCEPTION
   WHEN duplicate_object THEN null;
END $$;

Migrating

If you’re reading this, you probably already have a bot that you want to get using with VoxelBotUtils. Fortunately, migrating is pretty easy. Most base Discord.py classes work by default without alteration, and as such you can just run your existing bot with a VBU config file, and that can be that.

If you really want to get things going, you can change all of your @commands.command() lines to @voxelbotutils.command()<voxelbotutils.Command>, and any class MyCog(commands.Cog) to class MyCog(voxelbotutils.Cog)<voxelbotutils.Cog>, and everything else should pretty much handle itself.

Alternatively, some people want to make as few code changes as possible, using only the VoxelBotUtils utilities. That’s available too! If you change your bot instance in your current Discord.py code to use voxelbotutils.MinimalBot then everything else is drag and drop as usual. This change is necessary to make use of the changes to Discord.py’s discord.abc.Messageable (which include buttons and ephemeral messages). If there are certain extensions that you wish to load yourself from VoxelBotUtils, you can do that with bot.load_extension("voxelbotutils.cogs.[NAME]").

Getting Started With Websites

To get started, you’ll need to make a configuration file that VBU can use. The library is nice enough to do this for you if you run the module via the commandline:

$ voxelbotutils create-config website

Doing this will make a few files and folders:

  • website/frontend.py - a simple set of frontend routes

  • website/backend.py - a simple set of backend routes

  • website/static/ - a folder for all of your static files

  • website/templates/ - a folder for your Jinja2 templates

  • config/website.toml - this is your bot’s configuration file

  • config/website.example.toml - this is a git-safe version of your configuration file; you can commit this as you please

  • config/database.pgsql - this file should contain your database schema

  • .gitignore - a default Gitignore file to ignore your configuration file

Running the Website

You can write your website routes in the frontend.py and backend.py files (as well as any other files you specify in your config) and run your website from CMD.

$ voxelbotutils run-website