geas-bot/COMMANDS.md

# Bot Commands

A full list of native bot commands can be retrieved using the `-help` command in the bot.
The commands have full descriptions of their function as well as syntax that can be accessed via the help command.
This will not apply to `/commands`, and so this reference file will provide a list of all the commands, the cogs that control them, as well as their syntax or usage notes.

`N.B.: Do not delete any roles, channels, or categories that are created by the Bot unless you are certain you need to.
The Bot has no way of synchronising manual actions with its data files at present, and any conflict between the guild setup and the Bot's data will cause errors.
In a future version, I may try and make the bot more flexible to work with both its own commands and user actions.`

The prefix for the Bot's native commands is dynamic.
It can be changed using the relevant command below.
The default prefix for the bot is `-`.

In the syntax description below, mandatory arguments are given in `<angled brackets>`, and optional arguments are given in `[square brackets]`.

For most purposes, the bot will primarily rely on the new `/command` framework, and as such those commands will be listed first. The native bot commands will be provided below.

## `/commands`

`/commands` operate through a level of base commands, groups, and sub-commands.
Sub-commands inherit their permissions from their base commands.
All permissions are thus set at the level of the base command.
The commands are given in different cogs in order to keep the design modular, and to ensure that different modules can be activated or deactivated depending on what the configuration of the guild is like.

### Configuration Commands

These commands are to set up the bot for the guild.
The base command for the bot is `/config`.
Configuration commands are `admin only`.

| Command | Description |
|---|---|
| `/config roles <key> <role exists> [role]`  | Sets up the various key roles referenced by the bot, such as `bot` for dice bots, `committee`, `students`, as well as `newcomer`/`returning-player`. If a role already exists, the bot will assign that role. If it does not, the bot will create one. The bot will not be able to create games until a dice bot role has been defined.
| `/config channels <key> <channel exists> [channel]` | Sets up the various key channels referenced by the bot, such as the `mod` channel for notifications to Committee, as well as the `help` channel for the bot to monitor, and the `signup` channel for membership confirmations. If a channel already exists, the bot will assign it. If it does not, the bot will create one. The bot will not be able to use these features until the channels are defined. |
| `/config membership add <name> <role exists> [role]` | Creates a new membership type for the Bot to administer in the Guild. If a role exists, it will assign that role to the membership type. If it does not, the bot will create it. |
| `/config membership list` | Shows the current types of membership set up. |
| `/config membership remove <membership role>` | Deletes a membership type set up in the Guild. The command is locked if there are no membership types configured. |
| `/config notifications <key> <value>` | Whether or not the bot notifies the Committee on messages being posted here. This includes monitoring for the `help` channel and `membership signups` channel, etc. |
|`/config restrict <value>` | Enables or disables membership restriction in the Guild. |
| `/config timeslots add <key> <name>` | Creates a new timeslot for the Guild to host games in. The bot will not be able to create games until at least one time slot is configured. |
| `/config timeslots list` | Shows the current timeslots with their keys and names that are configured for the Guild. This command will only display if there is at least one timeslot configured. If you delete the last time slot, this command will be locked. |
| `/config timeslots modify <key> <name>` | Edits the name of a configured timeslot. You cannot change the key of a timeslot. This command will only display if there is at least one timeslot configured. If you delete the last time slot, this command will be locked. |
| `/config timeslots remove` | Opens a prompt to delete a configured timeslot. You cannot delete a time slot that has games configured for it. This command will only display if there is at least one timeslot configured. If you delete the last time slot, this command will be locked. |

### Game Commands

These commands are for setting up and managing games configured on the Guild.
The base command for the bot is `/game`.
The commands are `admin only`.
The base command is locked and only become available when at least one timeslot is set up, and a bot role has been assigned.
The sub-commands have additional restrictions.

| Command | Description |
|---|---|
| `/game create ...` | This is the base command to create games. This command takes several parameters that are far too many for me to list here. The Prompt system will make it clear what arguments need to be entered and when. |
| `/game delete <@game role>` | Deletes the game associated with the role that is mentioned. This command is locked until there is at least one game configured. If the last game that is configured is deleted by the bot, the command is locked again. `This command must be issued in a text channel associated with the game being deleted (in addition to mentioning the game role).` |
| `/game modify <@game role> ...` | This command also takes several parameters, just like `/game create`, but all of them are optional as long as at least one is entered. It changes the various parameters of the game. |
| `/game purge` | Opens a prompt to delete all games in a given time slot. It also has the option of deleting all games for all time slots. `Use this command with extreme caution.` |

### Player Commands

These commands are for managing players and their membership of games.
The base command is `/player`.
Permissions for this command are open to all users (i.e. all users who have the `use slash command` permission enabled on the Guild settings).
These commands are locked until there is at least one game configured.

| Command | Description |
|---|---|
| `/player add <@player> <@game>` | Adds a player to a game. It can only be used by the GM of the game being mentioned, or by an admin. |
| `/player leave` | Removes the user issuing the command from the game they are in. This command `must be issued in a text channel associated with the game you are trying to leave`. |
| `/player remove <@player>` | Removes the user mentioned from the game. This command `must be issued in a text channel associated with the game you are trying to leave`. |

While this is not strictly a `/player` command, and it is housed in a separate cog, it has the same level of permissions and prerequisites as all the `/player` commands.

| Command | Description |
|---|---|
|`/tcard`| Invokes a T-Card in the game. This command also posts a graphic of the T-Card, tags the game's role, and pings a message in the appropriate voice channel.|

### Pitch Command

The `/pitch` command is used to run pitches for games on the server.
It is locked until at least one game is set up.
The command is `admin only`.
It turns the current text channel where it is issued into a pitch listing channel, setting its permissions appropriately.
It opens a prompt to select which timeslot to pitch for.

The command further generates a menu of the games running, and also gives the admins a control panel with which to control access to the game staggered by the various roles (newcomers, returning players) if they are defined.

The pitch menu runs until it is closed using the relevant button.

## Native Bot `-commands`

These commands are issued using the bot's text prefix.
The prefix may vary depending on the bot's configuration.

### Default Commands

These commands are default to the `Discord.py` library and are automatically enabled in the bot

| Command | Permissions | Syntax and Aliases | Description |
|---|---|---| --- |
| help | All Users | `-help [command]`| Default Discord helper command. Gives a list of all of the commands enabled in the Guild. And when used with an optional argument that gives a command name, it provides the help text, description, and syntax of the command.|

### Debug Commands

These commands are found in the file `./cogs/controlcommands/debug.py` and provide meta-controls for how the bot and its functionality work.
The permissions for these commands has been set up at the Cog level for those with the Bot Maintainer role only or for the owner of the Guild. If no bot maintainer role is defined, the command will fail.

Information about debug commands will be displayed to users authorised to use them via the `-help` command.

### Prefix Command

This command is in the file `./cogs/botcommands/prefix.py`.
It allows for the dynamic control of the bot's command prefix for native commands.
The permission has been set up at the Cog level.

| Command | Permissions | Syntax and Aliases | Description |
|---|---|---| --- |
| changeprefix | Admin Only | `-changeprefix [str]` or `-prefix [str]` | Sets the given string as a prefix. The argument is option, and if not provided an argument it sets the prefix to `-` as the default. |