search

TheDiscordian / onebot

One bot to rule them all...
BSD 3-Clause "New" or "Revised" License
14 stars 1 forks source link

readme

OneBot

Onelib Go Reference

OneBot is a multi-protocol bot driven by feature plugins. It's primary purpose is for chatting, but it's flexible enough to be used for a variety of things.

Version v0.1.1-WIP

Table of Contents

Features

OneBot is powered by plugins, this will be a list of features and what plugins provide them.

Protocols

OneBot can connect to, read, and send messages on the following protocols:

Plugins

OneBot supports the following plugins and features. This section will also list commands provided by the plugins. A command for parrot for example is say, and the default command prefix is ,. So if a user typed ,say Hello World! the bot would reply with Hello World!.

Getting Started

Requirements

Getting OneBot

In your terminal run the follow commands as an unprivileged user in their home folder:

wget https://github.com/TheDiscordian/onebot/releases/latest/download/onebot-linux64.tar.xz
tar -xf onebot-linux64.tar.xz
mv bin/release ./onebot
rmdir bin

OneBot will now be located in the onebot directory.

Configuring OneBot

OneBot looks in the current directory for a config file named onebot.sample.toml by default, copy it to onebot.toml with cp onebot.sample.toml onebot.toml. Open onebot.toml using your favourite text editor (if you're very new to shells, try nano onebot.toml). You should see the following at the top:

[general]
default_prefix = ","
default_nickname = "OneBot"

You'll want to set these to what you want the command prefix to be, and the default nickname. The command prefix is used for invoking commands for example if it's , you could use the parrot plugin by saying ,say Hello World!. The nickname should be whatever you want the bot to be nicknamed (or what it's already nicknamed). This isn't extremely important, but if it's wrong some plugins may misbehave.

Protocols

In onebot.toml, head down to the line defining the protocol plugins, it should look something like this:

protocols = ["matrix", "discord", "bluesky"]

Edit this to only contain protocols you want to use.

Matrix

The Matrix config section looks like this:

[matrix]
# for example: https://matrix.org
home_server = ""
# if using auth_token, it must be in "@username:homeserver" format
auth_user = ""
# if blank, falls back onto auth_pass
auth_token = ""
# if set, this will be used to retrieve an auth token, then the password can be omitted from this file
auth_pass = ""

It's pretty self-explanatory. You set the homeserver of the bot, just like you would on a Matrix client. You set your username also as you normally would. If you have an auth_token, you can set that here too. If you don't have one, you can set auth_pass instead. Once the bot successfully logs in once it will store an auth_token in it's database, so you can remove the password from this file after.

Discord

The Discord config section looks like this:

[discord]
# is set as "Bot auth_token"
auth_token = ""
# id of admin user (for certain plugins like 'roletriggers')
admin_id = ""

You can get an auth_token for the bot from the Discord Developer Portal (if you don't know how, check out this guide).

admin_id isn't required, but can be helpful for plugins like roletriggers. ID here would be a Discord UID of the admin user.

Bluesky

The Bluesky protocol is pretty new, and only supports https://bsky.social as a PDS for now, but this is expected to change in the near future. It's section looks like this:

[bluesky]
# The handle on Bluesky of the account to use
handle = ""
# The password of the Bluesky account
password = ""
# The number of posts to fetch at once per poll
feed_count = 50
# The number of seconds to wait in between polls
feed_freq = 10
# The number of seconds to wait in between syncing followers
follow_freq = 60

The only required fields are handle and password. They're pretty self-explanatory, if you login with discordian.ca, you use discordian.ca as your handle. The password is your password (app passwords work too).

OneBot polls the PDS for new posts, and to check if it has any new followers. OneBot only sees posts by people it follows and will automatically follow anyone who follows it. The defaults should be fine for most people, however you're free to adjust these settings as much as your PDS allows.

Running OneBot

The simplest way to run OneBot after configuration is simply to run the binary:

cd ~/onebot
./onebot

However if you'd like OneBot to persist outside of just this terminal session, then I highly recommend using tmux. Install tmux, ensure OneBot isn't running, then try the following:

tmux
cd ~/onebot
./onebot # run the bot
CTRL+b, d

That last bit is saying "Press CTRL+b, release the keys, then press the d key". This will background a tmux shell, if you want to return to it at any time, ensure you're on your user account and run tmux attach.

Building OneBot

Requirements

Instructions

Get the source code with git clone https://github.com/TheDiscordian/onebot.git

Build the bot with make build.

Run the bot with make run.

Build everything and run with make dev. Note: This will also trigger tools/updatelicense.py, which is a recursive function.

Build the plugins via make plugins and make protocols. This will build all the plugins in the plugins directory, and all the protocol plugins in the protocols directory.

Check code correctness via make check. Note: This tool outputs suggestions, make sure to ask before making changes to already comitted code based on these guidelines.