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 fileswebsite
- this creates a set of website config filesall
- 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]
- thelogging.Logger
loglevel that you want to start the bot with
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 classesconfig/config.toml
- this is your bot’s configuration fileconfig/config.example.toml
- this is a git-safe version of your configuration file; you can commit this as you pleaseconfig/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 routeswebsite/backend.py
- a simple set of backend routeswebsite/static/
- a folder for all of your static fileswebsite/templates/
- a folder for your Jinja2 templatesconfig/website.toml
- this is your bot’s configuration fileconfig/website.example.toml
- this is a git-safe version of your configuration file; you can commit this as you pleaseconfig/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