Discord/CommandBot
Archived
1
0 Fork 0
Code Issues Actions Packages Projects Releases 40 Wiki Activity

Updated README - reformat + new features and events

Browse Source
This commit is contained in:
mmacierzanka committed 2021-07-05 21:37:52 +02:00
1 parent 245d9a36df
commit e11978f4dc
1 file changed
+199 -127
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+199 -127
View File
@@ -1,50 +1,60 @@
# CommandBot # CommandBot
**1.1.3** **1.1.3**
Discord.js framework that helps you build your own Discord bot. Discord.js framework that helps you build your own Discord bot.
Key features Key features
- command system
- auto-generated help command - command system
- command permissions - auto-generated help command
- command permissions
## Table of contents ## Table of contents
- [Getting started](#getting-started)
+ [Installation](#installation) - [Getting started](#getting-started)
+ [Creating bot instance](#creating-bot-instance) - [Installation](#installation)
- [Bot instance](#bot-instance) - [Creating bot instance](#creating-bot-instance)
- [Commands](#commands) - [Bot instance](#bot-instance)
+ [All parameters](#all-parameters) - [Commands](#commands)
+ [Command function](#command-function) - [All parameters](#all-parameters)
* [Arguments](#arguments) - [Command function](#command-function)
* [Return](#return) - [Arguments](#arguments)
* [Errors](#errors) - [Return](#return)
+ [Command examples](#command-examples) - [Errors](#errors)
* [Simple reply](#simple-reply) - [Command examples](#command-examples)
* [Example with arguments](#example-with-arguments) - [Simple reply](#simple-reply)
- [Events](#events) - [Example with arguments](#example-with-arguments)
- [Customization and built-in messages](#customization-and-built-in-messages) - [Events](#events)
+ [Help message](#help-message) - [Customization and built-in messages](#customization-and-built-in-messages)
+ [System messages](#system-messages) - [Help message](#help-message)
- [Complete example](#complete-example) - [System messages](#system-messages)
- [Complete example](#complete-example)
## Getting started ## Getting started
### Installation ### Installation
1. Install this package using npm 1. Install this package using npm
``` ```
npm install commandbot@latest npm install commandbot@latest
``` ```
2. Add the following entry to your *package.json* file 2. Add the following entry to your _package.json_ file
```json ```json
"type": "module" "type": "module"
``` ```
3. Import the package 3. Import the package
```javascript ```javascript
import { Bot, Command } from 'commandbot'; import { Bot, Command } from "commandbot";
``` ```
### Creating bot instance ### Creating bot instance
```javascript ```javascript
const bot = new Bot({ const bot = new Bot({
name: "Command bot", // Name of your bot name: "Command bot", // Name of your bot
@@ -52,122 +62,156 @@ const bot = new Bot({
argumentSeparator: ",", // Used to get arguments from message argumentSeparator: ",", // Used to get arguments from message
helpCommand: true, // Enable or disable the *help* command (optional) helpCommand: true, // Enable or disable the *help* command (optional)
clientOptions: undefined, // Instance of ClientOptions from Discord.js clientOptions: undefined, // Instance of ClientOptions from Discord.js
token: "" // Bot token from Discord Developer Portal (optional, you can pass the token in *start* method) token: "", // Bot token from Discord Developer Portal (optional, you can pass the token in *start* method)
}); });
``` ```
Start your bot using Start your bot using
```javascript ```javascript
bot.start(); bot.start();
``` ```
Optional arguments for this method Optional arguments for this method
- **port** - *number* - if specified, the app will create a http server that will be listening on the specified port
- **token** - *string* - app token from Discord Developer Portal - **port** - _number_ - if specified, the app will create a http server that will be listening on the specified port
- **token** - _string_ - app token from Discord Developer Portal
## Bot instance ## Bot instance
The main object of this library has the following properties The main object of this library has the following properties
- **name** - *string* - bot's name specified in the constructor
- **client** - *[Client](https://discord.js.org/#/docs/main/stable/class/Client)* - Discord.js client instance - **name** - _string_ - bot's name specified in the constructor
- **commands** - *CommandManager* - base of the command system (see [Commands](#commands)) - **client** - _[Client](https://discord.js.org/#/docs/main/stable/class/Client)_ - Discord.js client instance
- **config** - *object* - object that stores the login token and *helpMessage* value from the constructor - **commands** - _CommandManager_ - base of the command system (see [Commands](#commands))
- **messages** - *SystemMessageManager* - object instance containing all configuration parameters for built-in messages (see [Customization and built-in messages](#customization-and-built-in-messages)) - **config** - _object_ - object that stores the login token and _helpMessage_ value from the constructor
- **on** - *object* - object containing function that trigger on specified events (see [Events](#events)) - **messages** - _SystemMessageManager_ - object instance containing all configuration parameters for built-in messages (see [Customization and built-in messages](#customization-and-built-in-messages))
- **on** - _object_ - object containing function that trigger on specified events (see [Events](#events))
## Commands ## Commands
> [IMPORTANT] > [IMPORTANT]
> All commands have to be declared above the *start* method > All commands have to be declared above the _start_ method
### All parameters ### All parameters
- **name** - *string* - command name (used to trigger the command)
- **function** - *Function* - function that will trigger when the commands gets called - **name** - _string_ - command name (used to trigger the command)
- **visible** - *boolean* - show command in the *help message* (optional, defaults to *true*) - **function** - _Function_ - function that will trigger when the commands gets called
- **description** - *string* - command description shown in the *help message* (optional) - **visible** - _boolean_ - show command in the _help message_ (optional, defaults to _true_)
- **usage** - *string* - command usage description shown in the *help message* (optional) - **description** - _string_ - command description shown in the _help message_ (optional)
- **permissionCheck** - *"ALL" | "ANY"* - specifies if the caller has to have all of the specified permissions or any of that (optional, default value: "ANY") - **usage** - _string_ - command usage description shown in the _help message_ (optional)
- **permissions** - *[PermissionResolvable](https://discord.js.org/#/docs/main/stable/typedef/PermissionResolvable)* - permissions needed to run the command (optional) - **permissionCheck** - _"ALL" | "ANY"_ - specifies if the caller has to have all of the specified permissions or any of that (optional, default value: "ANY")
- **aliases** - *string | string[]* - other words that can trigger the command with prefix (optional) - **permissions** - _[PermissionResolvable](https://discord.js.org/#/docs/main/stable/typedef/PermissionResolvable)_ - permissions needed to run the command (optional)
- **keywords** - *string | string[]* - other words that can trigger the command without prefix (optional) - **aliases** - _string | string[]_ - other words that can trigger the command with prefix (optional)
- **keywords** - _string | string[]_ - other words that can trigger the command without prefix (optional)
### Command function ### Command function
#### Arguments #### Arguments
- **m** - *[Message](https://discord.js.org/#/docs/main/stable/class/Message)* - a message object instance containing message content, author and additional informations
- **a** - *string[]* - list of arguments passed with the message (splitted with *argumentSeparator*) - **m** - _[Message](https://discord.js.org/#/docs/main/stable/class/Message)_ - a message object instance containing message content, author and additional informations
- **a** - _string[]_ - list of arguments passed with the message (splitted with _argumentSeparator_)
#### Return #### Return
If command function returns If command function returns
- *string* - the returned text will be sent as a reply to the command caller
- *[MessageEmbed](https://discord.js.org/#/docs/main/stable/class/MessageEmbed)* - the embedded content will be sent as a standalone message - _string_ - the returned text will be sent as a reply to the command caller
- _[MessageEmbed](https://discord.js.org/#/docs/main/stable/class/MessageEmbed)_ - the embedded content will be sent as a standalone message
#### Errors #### Errors
If your command throws an error, it will get logged to the console and sent to the user in a message with embedded content. **The bot will not crash.** ([Example](https://raw.githubusercontent.com/GRZ4NA/CommandBot/master/assets/error_example.png)) If your command throws an error, it will get logged to the console and sent to the user in a message with embedded content. **The bot will not crash.** ([Example](https://raw.githubusercontent.com/GRZ4NA/CommandBot/master/assets/error_example.png))
### Command examples ### Command examples
#### Simple reply #### Simple reply
1. Create a command 1. Create a command
```javascript ```javascript
//CREATE COMMAND //CREATE COMMAND
const command = new Command({ const command = new Command({
name: "ping", name: "ping",
function: (m, a) => { function: (m, a) => {
return 'pong'; return "pong";
} },
}); });
//APPEND IT TO THE COMMANDS LIST //APPEND IT TO THE COMMANDS LIST
bot.commands.add(command); bot.commands.add(command);
``` ```
or or
```javascript ```javascript
bot.commands.add(new Command({ bot.commands.add(
name: "ping", new Command({
function: (m, a) => { name: "ping",
return 'pong'; function: (m, a) => {
} return "pong";
})); },
})
);
``` ```
2. Call it from Discord text channel (example prefix: "!") 2. Call it from Discord text channel (example prefix: "!")
``` ```
!ping !ping
Result: Result:
@mention, pong @mention, pong
``` ```
#### Example with arguments #### Example with arguments
1. Create a command 1. Create a command
```javascript ```javascript
const command = new Command({ const command = new Command({
name: "repeat", name: "repeat",
function: async (m, a) => { function: async (m, a) => {
if(a[0] && a[1]) { if (a[0] && a[1]) {
const count = parseInt(a[1]); const count = parseInt(a[1]);
if(!isNaN(count)) { if (!isNaN(count)) {
for(let i = 0; i < count; i++) { for (let i = 0; i < count; i++) {
await m.channel.send(a[0]); await m.channel.send(a[0]);
} }
return `Repeated "${a[0]}" ${count} times`; return `Repeated "${a[0]}" ${count} times`;
} } else {
else { throw new Error("Number of messages is incorrect");
throw new Error('Number of messages is incorrect');
} }
} }
} },
}); });
bot.commands.add(command); bot.commands.add(command);
``` ```
or or
```javascript ```javascript
bot.commands.add(new Command({ bot.commands.add(
name: "repeat", new Command({
function: async (m, a) => { name: "repeat",
if(a[0] && a[1]) { function: async (m, a) => {
const count = parseInt(a[1]); if (a[0] && a[1]) {
if(!isNaN(count)) { const count = parseInt(a[1]);
for(let i = 0; i < count; i++) { if (!isNaN(count)) {
await m.channel.send(a[0]); for (let i = 0; i < count; i++) {
await m.channel.send(a[0]);
}
return `Repeated "${a[0]}" ${count} times`;
} else {
throw new Error("Number of messages is incorrect");
} }
return `Repeated "${a[0]}" ${count} times`;
} }
else { },
throw new Error('Number of messages is incorrect'); })
} );
}
}
}));
``` ```
2. Call it from Discord text channel (example prefix: "!", example separator: "," [default]) 2. Call it from Discord text channel (example prefix: "!", example separator: "," [default])
``` ```
!repeat test, 5 !repeat test, 5
@@ -179,75 +223,103 @@ test
test test
@caller, Repeated "test" 5 times @caller, Repeated "test" 5 times
``` ```
## Events ## Events
There are 2 events defined in the *on* property
- **message** - *Function* - a function that will trigger for every message sent in any text channel (a [Message](https://discord.js.org/#/docs/main/stable/class/Message) object is passed to the first argument) Events are emitted using built-in event emitter **(since version 2.0.0)**. You can handle them using _on_ property
- **command** - *Function* - a function that will trigger for every message that gets recognized as a command (a [Message](https://discord.js.org/#/docs/main/stable/class/Message) object is passed to the first argument and a CommandMessageStructure object to the second argument)
> [IMPORTANT] - **ready** - emitted when the client successfully connect to Discord API
> Do not use client.on('message') event handler! This handler is a core part of the command system. - **message** - emitted for every message sent in any text channel (a [Message](https://discord.js.org/#/docs/main/stable/class/Message) object is passed to the first argument)
- **command** - emitted for every message that gets recognized as a command (a [Message](https://discord.js.org/#/docs/main/stable/class/Message) object is passed to the first argument and a CommandMessageStructure object to the second argument)
- **error** - emitted on permission and command errors (an error object is passed to the first argument)
> [IMPORTANT]
> Do not use client.on('message') and client.on('ready') event handler! This handler is a core part of the command system.
Example
```javascript
bot.on("ready", () => {
console.log("Bot is ready!");
});
```
## Customization and built-in messages ## Customization and built-in messages
All configuration parameters for messages are stored in *messages* property (example: bot.messages)
All configuration parameters for messages are stored in _messages_ property (example: bot.messages)
### Help message ### Help message
Configuration parameters are stored in *messages.help* property
- **title** - *string* - title of help message Configuration parameters are stored in _messages.help_ property
- **bottomText** - *string* - text shown below the title
- **color** - *[ColorResolvable](https://discord.js.org/#/docs/main/stable/typedef/ColorResolvable)* - color of the embedded content - **title** - _string_ - title of help message
- **description** - *string* - command description (equivalent of the *description* property in *Command* object) - **bottomText** - _string_ - text shown below the title
- **usage** - *string* - equivalent of the *usage* property in *Command* object (You can pass a command name, alias or keyword with the *help* command to get detailed information about the specified command) - **color** - _[ColorResolvable](https://discord.js.org/#/docs/main/stable/typedef/ColorResolvable)_ - color of the embedded content
- **description** - _string_ - command description (equivalent of the _description_ property in _Command_ object)
- **usage** - _string_ - equivalent of the _usage_ property in _Command_ object (You can pass a command name, alias or keyword with the _help_ command to get detailed information about the specified command)
### System messages ### System messages
All options are stored in *messages.system* property
All options are stored in _messages.system_ property
There are 3 types of system messages There are 3 types of system messages
- Error message (**ERROR**)
- Command not found message (**NOT_FOUND**) - Error message (**ERROR**)
- Insufficient permissions message (**PERMISSION**) - Command not found message (**NOT_FOUND**)
- Insufficient permissions message (**PERMISSION**)
Each message can be customized using these properties Each message can be customized using these properties
- **title** - *string* - title of the message
- **bottomText** - *string* - text shown below the title
- **accentColor** - *[ColorResolvable](https://discord.js.org/#/docs/main/stable/typedef/ColorResolvable)* - color of the embedded content
- **showTimestamp** - *boolean* - show time and date at the bottom of the embedded content
- **footer** - *string* - footer of the embedded content
The *messages.system* also contains a *deleteTimeout* property. It specifies the time (in ms) after which a system message will be deleted. Set it to *Infinity* to never delete messages (default value). - **enabled** - _boolean_ - enables or disables the system message
- **title** - _string_ - title of the message
- **bottomText** - _string_ - text shown below the title
- **accentColor** - _[ColorResolvable](https://discord.js.org/#/docs/main/stable/typedef/ColorResolvable)_ - color of the embedded content
- **showTimestamp** - _boolean_ - show time and date at the bottom of the embedded content
- **footer** - _string_ - footer of the embedded content
The _messages.system_ also contains a _deleteTimeout_ property. It specifies the time (in ms) after which a system message will be deleted. Set it to _Infinity_ to never delete messages (default value).
## Complete example ## Complete example
```javascript ```javascript
import { Bot, Command } from 'commandbot'; import { Bot, Command } from "commandbot";
const bot = new Bot({ const bot = new Bot({
name: "CommandBot", name: "CommandBot",
prefix: "!" prefix: "!",
}); });
bot.messages.help.accentColor = '#ff0000'; bot.messages.help.accentColor = "#ff0000";
bot.messages.system.NOT_FOUND.accentColor = "BLUE"; bot.messages.system.NOT_FOUND.accentColor = "BLUE";
//Command triggers: !ping, !pong, pingpong //Command triggers: !ping, !pong, pingpong
bot.commands.add(new Command({ bot.commands.add(
name: 'ping', new Command({
aliases: 'pong', name: "ping",
keywords: 'pingpong', aliases: "pong",
function: (m, a) => { keywords: "pingpong",
return 'Bot ping: ' + bot.client.ws.ping + 'ms'; function: (m, a) => {
} return "Bot ping: " + bot.client.ws.ping + "ms";
})); },
bot.commands.add(new Command({ })
name: "repeat", );
function: async (m, a) => { bot.commands.add(
if(a[0] && a[1]) { new Command({
const count = parseInt(a[1]); name: "repeat",
if(!isNaN(count)) { function: async (m, a) => {
for(let i = 0; i < count; i++) { if (a[0] && a[1]) {
await m.channel.send(a[0]); const count = parseInt(a[1]);
if (!isNaN(count)) {
for (let i = 0; i < count; i++) {
await m.channel.send(a[0]);
}
return `Repeated "${a[0]}" ${count} times`;
} else {
throw new Error("Number of messages is incorrect");
} }
return `Repeated "${a[0]}" ${count} times`;
} }
else { },
throw new Error('Number of messages is incorrect'); })
} );
}
}
}));
bot.start(3000, 'TOKEN'); bot.start(3000, "TOKEN");
``` ```