search

FragSoc / esports-bot

A Discord bot utilising Discord.py to provide functionality for UoY Esports game hubs
GNU Affero General Public License v3.0
2 stars 2 forks source link
discord-bot discord-py

readme

UoY Esports Bot Rewrite

Dependency Versions:

This Discord bot was written to merge all the functions of different bots used in the Fragsoc Discord server into one bot that is maintained by Fragsoc members.

How to set up an instance of this bot with Docker

  1. Clone this repository:

    $ git clone https://github.com/FragSoc/Esports-Bot-Rewrite.git

  2. Change into the repo directory:

    $ cd Esports-Bot-Rewrite

  3. Rename the secrets.template to secrets.env and set all the variables. Be sure to read the Current Functions section below for the Cog you want to enable in case of any special setup instructions:

    $ nano secrets.env

  4. Run docker-compose:

    $ docker-compose up

How to set up an instance of this bot without Docker

Requirements needed to run:

  1. Clone this repository: 
    
$ git clone https://github.com/FragSoc/Esports-Bot-Rewrite.git

2. Change into the repo directory:
```console
$ cd Esports-Bot-Rewrite

  1. Rename the secrets.template to secrets.env and set all the variables. Be sure to read the Current Functions section below for the Cog you want to enable in case of any special setup instructions:

    $ nano secrets.env
$ source secrets.env

  2. Change into the bot directory:

    $ cd src

  3. Install all the requirements for python:

    pip install -r requirements.txt

  4. Run the bot:

    python3 main.py

Current Functions

The list below describes the different "Cogs" of the bot, their associated commands, and any additional information required to set them up.

Voicemaster ### Voicemaster #### !voice setparent * Aliases: `setvmparent` * Make the given ID a Voicemaster parent voice channel. #### !voice getparents * Aliases: `setvmparent` * Get all the Voicemaster parent voice channels in the server. #### !voice removeparent * Aliases: `removevmparent` * Remove the given ID as a Voicemaster parent voice channel. #### !voice removeallparents * Remove all Voicemaster parents from the server. #### !voice removeallchildren * Delete all the Voicemaster child channels in the server. #### !voice lock * Aliases: `lockvm` * Locks the Voicemaster child you're currently in to the number of current members. #### !voice unlock * Aliases: `unlockvm` * Unlocks the Voicemaster child you're currently in. #### !voice rename * Aliases: `renamevm` * Renames your current Voicemaster voice channel.
Default Role ### Default role #### !setdefaultroles * Sets the roles that the server gives to members when they join the server. #### !getdefaultroles * Gets the current default roles set for the server. #### !removedefaultroles * Removes the current default roles for the server.
Log Channel ### Log Channel #### !setlogchannel * Set the log channel to the #'ed channel or given role ID. #### !getlogchannel * Gets the current log channel value. #### !removelogchannel * Removes the current log channel value.
Administrator Tools ### Administrator Tools Adds a few commands useful for admin operations. #### !admin clear * Aliases: `cls, purge, delete` * Clear the specified number of messages from the current text channel. #### !admin version * Get the current version of the bot. #### !admin members * List the current number of members in the server. #### !dev remove-cog \ * Unloads the given cog. * *This command requires your user ID to be defined in the env file under `DEV_IDS`* #### !dev add-cog \ * Loads the given cog. * *This command requires your user ID to be defined in the env file under `DEV_IDS`* #### !dev reload-cog \ * Reloads the given cog. * *This command requires your user ID to be defined in the env file under `DEV_IDS`* #### !admin set-rep \ \ * Sets the permissions for a user in the channels/categories given. * *Requires `administrator` permission in Discord* #### !admin user-info \ * Get basic information about a users profile. * *Requires `administrator` permission in Discord*
Twitter Integration ### Twitter Integration Enables forwarding tweets when they are tweeted to a discord channel for specific Twitter accounts. Requires the `ENABLE_TWITTER` variable to be set to `TRUE` in order to function. #### !twitter add \ * Add a Twitter handle to notify when they tweet or quote retweet. #### !twitter remove \ * Remove the given Twitter handle from notifications. #### !twitter hook [optional: channel mention] [optional: hook name] * Aliases: `addtwitterhook, create-hook` * Creates a Discord Webhook bound to the channel the command was executed in, unless a channel is given, and with a default name unless a name is given. #### !twitter remove-hook \ * Aliases: `deltwitterhook, delete-hook` * Deletes the Discord Webhook so that updates are no longer sent to that channel #### !twitter list * Aliases: `accounts, get-all`. * Returns a list of the currently tracked Twitter accounts for the server.
Event Channel Management ### Event Category Management Each server can have any number of named event categories, where each category creates a sign-in channel, a general chat, a voice chat and a role for the event. All commands in this cog required the `administrator` permission in Discord. #### !events create-event \ \ * Creates the text channels, and voice channel for the event. The role given is used to later expose the sign-in channel to members. Upon creation the event is set to `closed`. * See the `open-event` and `close-event` for more information regarding which members can see which channels. * The role created for this event will have the same as the event name, it is not the role given in the command. #### !events open-event \ * Allows the role given in the `create-event` command to see the sign-in channel, and add reactions to the sign-in message. * The sign-in message grants the role created by the bot for the event. #### !events close-event \ * Stops any member who is not an administrator from being able to see any of the event channels. #### !events delete-event \ * Deletes all the channels in the category for the event and deletes the role created by the bot for the event.
Twitch Integration ### Twitch Integration Enables sending notifications to a Discord channel whenever a tracked channel goes live. Requires the `ENABLE_TWITCH` variable to be set to `TRUE` in order to function. Set the `TEMP_BEARER_FILE` to anything you like, this will be the file where your bearer token is stored for reuse. ### Creating your self-signed SSL keys: 1. Create the Certificate Authority (CA) private key: ```console $ openssl genrsa -des3 -out servercakey.pem ``` 2. Create the CA public certificate: ```console $ openssl req -new -x509 -key servercakey.pem -out root.crt ``` 3. Create the server's private key file: ```console $ openssl genrsa -out server.key ``` 4. Create the server's certificate request: ```console $ openssl req -new -out reqout.txt -key server.key ``` 5. Use the CA private key file to sign the server's certificate: ``` $ openssl x509 -req -in reqout.txt -days 3650 -sha1 -CAcreateserial -CA root.crt -CAkey servercakey.pem -out server.crt ``` 6. Move your `server.crt` and `server.key` files into the `src` folder. 7. Set the environment variable `SSL_CERT_FILE` to the name of your `server.crt` file and the variable `SSL_KEY_FILE` to the name of your `server.key` file. ### Getting your Twitch Credentials: 1. Go to the [Twitch Developers](https://dev.twitch.tv/) site. 1. Once logged in, in the top left, go to `Your Console` or [this](https://dev.twitch.tv/console) site. 1. Register a new application using any name and the OAuth Redirect URL of `http://localhost`. 1. Once created, click `manage`. Copy the string that is in `Client ID` and then click the `New Secret` button to generate a new `Client Secret` and then copy the string it generates. In your `.env` file the `TWITCH_SUB_SECRET` should be a string that is 10-100 characters long and should not be shared anywhere. This is used to authenticate if a message has come from Twitch or if it has been altered along the way. The `TWITCH_CALLBACK` is the URL to your HTTPS server. For testing you can use `ngrok`: - Run `ngrok http 443` and copy the `https` URL **not** the `htttp` URL and use that as your `TWITCH_CALLBACK` variable. #### !twitch createhook \ \ * Creates a Discord Webhook bound to the channel given and with the name given, but prefixed with the Twitch Webhook prefix. #### !twitch deletehook \ * Deletes the given Discord Webhook. #### !twitch add \ \ [optional: custom message] * Adds a Twitch channel to be tracked in the given Webhook. * *__If a custom message is given, it must be surrounded by double quotes__*: `!twitch add "custom_message"` #### !twitch remove \ \ * Removes a Twitch channel from being tracked in the current Discord server. #### !twitch list [optional: hook name] * Shows a list of all the currently tracked Twitch accounts and their custom messages. * If a hook name is given, only shows the information for the given hook. #### !twitch webhooks * Get a list of the current Discord Webhooks for Twitch notifications. #### !twitch setmessage \ \ [optional: custom message] * Sets the custom message of a Twitch channel. Can be left empty if the custom message is to be removed. * *__If a custom message is given, it must be surrounded by double quotes__*: `!twitch setmessage "custom_message"` #### !twitch getmessage \ [optional: hook name] * Gets the currently set custom message for a Twitch channel. * If a hook name is given, gets the currently set custom message for the Twitch channel in that Webhook. #### !twitch preview \ \ * Get a preview of the live notification for the given Twitch channel in the given Webhook.
Role Reaction Menus ### Role Reaction Menus. Role reaction menus allow admins to create reactable menus that when reacted to grant defined roles to the user. For devs: * To enable this function in the bot use the `ENABLE_ROLEREACTIONS` env var and set it to `TRUE`. * Making new types of reaction menus is easy - simply extend `DiscordReactableMenus.ReactableMenu` or one of the example menus in `DiscordReactableMenus.ExampleMenus`. #### !roles make-menu \ \<description> [\<mentioned role> \<emoji>] * Creates a new role reaction menu with the given roles and their emojis. * Each option must be a mentioned role followed by the emoji to use as its reaction. There can be up to 25 roles in a single reaction menu. * The `title` is displayed at the top of the menu, and the `description` just below. To have either blank leave the quotes empty. * If the `DELETE_ROLE_CREATION` env var is set to `TRUE` the command message will be deleted. * *Requires `administrator` permission in Discord* * An example usage of this command is as such: `!roles make-menu "{title}" "{description}" {@option1 role} {option1 emoji} ... ...` #### !roles add-option [optional: menu id] [\<mentioned role> \<emoji>] * Adds more role reaction options to the given menu. If there is no menu id given, the latest role reaction menu will be used. * There can be one or many options added at the same time with this command. * Each option must be a mentioned role followed by the emoji to use as its reaction. There can be up to 25 roles in a single reaction menu. * *Requires `administrator` permission in Discord* * An example usage of this command is as such: `!roles add-option {menu id} {@option role} {option emoji} ... ...` #### !roles remove-option \<emoji> [optional: menu id] * Removes the role associated with the emoji from the given menu. If there is no menu id given, the latest role reaction menu will be used. * *Requires `administrator` permission in Discord* #### !roles disable-menu [optional: menu id] * Disables a reaction menu. This means that roles will not be given to users when they react to the message. If there is no menu id given, the latest role reaction menu will be used. * *Requires `administrator` permission in Discord* #### !roles enable-menu [optional: menu id] * Enables a reaction menu. This means that users will be able to receive roles from the reaction menu when they react. If there is no menu id given, the latest role reaction menu will be used. * *Requires `administrator` permission in Discord* #### !roles delete-menu \<menu id> * Deletes the given role reaction menu. __Does not__ delete any of the roles in the menu, just the message. * *Requires `administrator` permission in Discord* #### !roles toggle-ids * Shows or Hides all role reaction menu footers, which contain the ID of the role reaction menu for ease of identification. * *Requires `administrator` permission in Discord* </details> <details> <summary>Poll Reaction Menus</summary> ### Poll Reaction menus. Poll reaction menus allow users to create polls with up to 25 different options for other users, and themselves, to vote on. The poll start and end is not time based, but instead controlled by the user that created the poll or administrators. For devs: * To enable this function in the bot use the `ENABLE_VOTINGMENUS` env var and set it to `TRUE`. * Making new types of reaction menus is easy - simply extend `DiscordReactableMenus.ReactableMenu` or one of the example menus in `DiscordReactableMenus.ExampleMenus`. #### !votes make-poll \<title> [\<emoji> \<description>] * Creates a new poll with each emoji having a description. * Each option must be an emoji and a description, with each one on a new line. There can be up to 25 roles in a single reaction menu. * If the `DELETE_VOTING_CREATION` env var is set to `TRUE` the command message will be deleted. * An example usage of this command is as such: ``` !votes make-poll {title} {option1 emoji} {option1 description} {option2 emoji} {option2 description} ... ... [up to option 25] ``` #### !votes add-option \<menu id> \<emoji> \<description> * Aliases: `add, aoption` * Adds another option to the poll with the menu id given. * Only one option can be added at a time with this command. * Each option must be an emoji and a description, with each one on a new line. There can be up to 25 roles in a single reaction menu. * *You must be the owner of the poll or be an administrator* * An example usage of this command is as such: `!votes add-option {menu id} {option emoji} {option description}` #### !votes remove-option \<menu id> \<emoji> * Aliases: `remove, roption` * Removes the option from the poll with the menu id given. * *You must be the owner of the poll or be an administrator* #### !votes delete-poll \<menu id> * Aliases: `delete, del` * Deletes the poll with the menu id given. * *You must be the owner of the poll or be an administrator* #### !votes end-poll \<menu id> * Aliases: `finish, complete, end` * Deletes the actual poll message and sends a new message with the results of the poll. * *You must be the owner of the poll or be an administrator* #### !votes reset-poll \<menu id> * Aliases: `reset, clear, restart` * Removes all the current user-added reactions from the poll with the menu id given. * *You must be the owner of the poll or be an administrator* </details> <details> <summary>Music Bot</summary> ### Music Bot A basic music bot that functions similarly to the popular 'Hydra Bot'. Commands that use the prefix of `!music` are commands that must be sent in the defined music channel for the server. The rest of the commands in this cog can be sent anywhere. Most `!music` commands require you to be in the same voice channel as the bot, or if it is not in a channel, for you to be in a voice channel. Some `!music` commands can have this requirement ignored if the user performing the command is an administrator and uses the `force` or `-f` flag in the command. To add new songs to the queue, just put the name, YouTube link, or a YouTube playlist into the music channel once set. Also requires you to be in the voice channel with the bot, or if the bot is inactive, in any voice channel. To enable this cog, use the `ENABLE_MUSIC` env var in your `secrets.env` file, and set it to `TRUE`. For this cog to work, the `GOOGLE_API` env var must also be set, and instructions on how to get an API credential is below: ### To create your Google API credentials: 1. Go to the [Google Cloud API]("https://console.cloud.google.com/apis/") site. 1. Create a new project and name it whatever you want. 1. In the [dashboard](https://console.cloud.google.com/apis/dashboard), click the `Enable APIs and Services` and search for `YouTube Data API v3`. 1. Click `Enable` to enable the use of the YouTube API. 1. Keep going back until at your [dashboard](https://console.cloud.google.com/apis/dashboard), and go to the [credentials](https://console.cloud.google.com/apis/credentials) section on the left. 1. Click on `Create Credentials` and then `API key`. 1. Copy the key given. For security, it is recommended that you "restrict key" and only enable `YouTube Data API v3`. #### !musicadmin set \<channel mention> [optional: [args]] * This sets the channel mentioned to be used as the music channel. All messages into this channel will be considered music requests, and any music commands must be sent in this channel. * Optional args: * Using `-c` will clear the entire channel before setting it up as the music channel. * *Requires `administrator` permission in Discord* #### !musicadmin get * Sends the currently set music channel for the server. * *Requires `administrator` permission in Discord* #### !musicadmin reset * This clears the current music channel and resets the preview and queue messages. * *Requires `administrator` permission in Discord* #### !musicadmin remove * Unlinks the currently linked music channel from being the music channel. This will not delete the channel or its contents. * *Requires `administrator` permission in Discord* #### !musicadmin fix * If the bot has broken and thinks it is still in a Voice Channel, use this command to force it to reset. * *Requires `administrator` permission in Discord* #### !music queue * Aliases: `songqueue, songs, songlist, songslist` * Gets the current list of songs in the queue. #### !music join [optional: -f | force] * Aliases: `connect` * Make the bot join the channel. * If you are an admin you can force it join your voice channel using the `-f` or `force` option. #### !music kick [optional: -f | force] * Aliases: `leave` * Kicks the bot from the channel. * If you are an admin you can force it to leave a voice channel with the `-f` or `force` option. #### !music play [optional: song request] * Aliases: `resume` * Resumes playback of the current song. * If a song is requested and there is no current song, it is played, otherwise it is added to the queue. #### !music pause * Pauses the current song. #### !music shuffle * Shuffles the current queue of songs. #### !music volume \<volume level> * Sets the volume of the bot for everyone to the level given. #### !music clear * Clears the queue entirely, does not stop the current song from playing. #### !music skip [optional: skip to position] * Skips the current song. * If a number is given it will also skip to the song at the position given. * For example, if 'songs to skip' is 4, the next song to play would be song 4 in the queue. #### !music remove \<song position> * Removes the song at the given position from the queue. #### !music move \<from position> \<to position> * Moves the song at position `from position` to position `to position` in the queue. </details> <details> <summary>Pingable Roles</summary> ### Pingable Roles Pingable roles are roles that can be voted in to be created by any user, and that once created have a cooldown tied to how often that role can be pinged. A user can create a poll where if there are enough votes by the time the poll ends, a role will be created. The length of the poll and the number of votes required are customisable by server admins. After the poll finishes, a reaction menu gets created, allowing *any* user to react and receive the role. Initially the role will have the default cooldown of the server, but can be overridden. #### !pingme settings get-settings * Returns an embed of the current default settings for the server. * *Requires `administrator` permission in Discord* #### !pingme settings default-settings * Resets all settings for this guild to the bot-defined defaults defined in the `.env` file. * *Requires `administrator` permission in Discord* #### !pingme settings poll-length \<poll length in seconds> * Sets the default poll length to the given time in seconds. * Polls can have a custom length by specifying it when using the [`!pingme create-role`](#pingme-create-role-role-name-optional-poll-length-in-seconds) command. * *Requires `administrator` permission in Discord* #### !pingme settings poll-threshold \<number of votes threshold> * Sets the number of votes required in a poll for the role to be created. * *Requires `administrator` permission in Discord* #### !pingme settings ping-cooldown \<cooldown in seconds> * Sets the default ping cooldown for any pingable role created with this cog. * Roles can have their cooldown altered individually with the [`!pingme role-cooldown`](#pingme-role-cooldown-role-mention--role-id-cooldown-in-seconds) command. * *Requires `administrator` permission in Discord* #### !pingme settings poll-emoji \<emoji> * Sets the emoji to be used when creating a poll to vote in. * *Requires `administrator` permission in Discord* #### !pingme settings role-emoji \<emoji> * Sets the default emoji to be used in the role reaction menu for the pingable role once it has been created. * Roles can have their reactable emoji altered individually with the [`!pingme role-emoji`](#pingme-role-emoji-role-mention--role-id-emoji) command. * *Requires `administrator` permission in Discord* #### !pingme disable-role \<one or many role mentions> * Disables the roles mentioned from being mentioned by non-administrators and disables their reaction menus. * The roles provided __must__ be pingable roles created with this cog. * *Requires `administrator` permission in Discord* #### !pingme enable-role \<one or many role mentions> * Enabled the roles mentioned to be mentioned by non-administrators and allows their reaction menus to be reacted to. * The roles provided __must__ be pingable roles created with this cog. * *Requires `administrator` permission in Discord* #### !pingme create-role \<role name> [optional: poll length in seconds] * Creates a new poll to create a role if the number of votes has surpassed the server's threshold after the poll length has passed. #### !pingme delete-role \<one or many role mentions> * Deletes the mentioned roles from the server. * The roles provided __must__ be pingable roles created with this cog. * *Requires `administrator` permission in Discord* #### !pingme convert-role \<one or many role mentions> * Converts the mentioned roles into pingable roles and creates their reaction menus. * The roles provided __cannot__ be roles that are already pingable roles. * *Requires `administrator` permission in Discord* #### !pingme convert-pingable \<one or many role mentions> * Converts the mentioned roles from pingable roles into normal roles and deletes their reaction menus. * The roles provided __must__ be pingable roles created with this cog. * *Requires `administrator` permission in Discord* #### !pingme role-cooldown \<role mention | role ID> \<cooldown in seconds> * Sets the ping cooldown for a specific role which overrides the server default for that role. * The role provided __must__ be a pingable role created with this cog. * *Requires `administrator` permission in Discord* #### !pingme role-emoji \<role mention | role ID> \<emoji> * Sets the emoji to use in the reaction menu for the given role. * The role provided __must__ be a pingable role created with this cog. * *Requires `administrator` permission in Discord* </details></div> </div> <div class="footer"> <ul class="body"> <li>© <script> document.write(new Date().getFullYear()) </script> Githubissues.</li> <li>Githubissues is a development platform for aggregating issues.</li> </ul> </div> <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script> <script src="/githubissues/assets/js.js"></script> <script src="/githubissues/assets/markdown.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/highlight.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/languages/go.min.js"></script> <script> hljs.highlightAll(); </script> </body> </html>