From e11978f4dc06344639bf79c6e98cee44ebaa53b8 Mon Sep 17 00:00:00 2001 From: GRZ4NA Date: Mon, 5 Jul 2021 21:37:52 +0200 Subject: [PATCH] Updated README - reformat + new features and events --- README.md | 326 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 199 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index aef5530..3151a64 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,60 @@ # CommandBot + **1.1.3** Discord.js framework that helps you build your own Discord bot. Key features -- command system -- auto-generated help command -- command permissions + +- command system +- auto-generated help command +- command permissions ## Table of contents -- [Getting started](#getting-started) - + [Installation](#installation) - + [Creating bot instance](#creating-bot-instance) -- [Bot instance](#bot-instance) -- [Commands](#commands) - + [All parameters](#all-parameters) - + [Command function](#command-function) - * [Arguments](#arguments) - * [Return](#return) - * [Errors](#errors) - + [Command examples](#command-examples) - * [Simple reply](#simple-reply) - * [Example with arguments](#example-with-arguments) -- [Events](#events) -- [Customization and built-in messages](#customization-and-built-in-messages) - + [Help message](#help-message) - + [System messages](#system-messages) -- [Complete example](#complete-example) + +- [Getting started](#getting-started) + - [Installation](#installation) + - [Creating bot instance](#creating-bot-instance) +- [Bot instance](#bot-instance) +- [Commands](#commands) + - [All parameters](#all-parameters) + - [Command function](#command-function) + - [Arguments](#arguments) + - [Return](#return) + - [Errors](#errors) + - [Command examples](#command-examples) + - [Simple reply](#simple-reply) + - [Example with arguments](#example-with-arguments) +- [Events](#events) +- [Customization and built-in messages](#customization-and-built-in-messages) + - [Help message](#help-message) + - [System messages](#system-messages) +- [Complete example](#complete-example) ## Getting started + ### Installation + 1. Install this package using npm + ``` 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 "type": "module" ``` 3. Import the package + ```javascript -import { Bot, Command } from 'commandbot'; +import { Bot, Command } from "commandbot"; ``` + ### Creating bot instance + ```javascript const bot = new Bot({ name: "Command bot", // Name of your bot @@ -52,122 +62,156 @@ const bot = new Bot({ argumentSeparator: ",", // Used to get arguments from message helpCommand: true, // Enable or disable the *help* command (optional) 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 + ```javascript bot.start(); ``` + 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 + 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 -- **commands** - *CommandManager* - base of the command system (see [Commands](#commands)) -- **config** - *object* - object that stores the login token and *helpMessage* value from the constructor -- **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)) + +- **name** - _string_ - bot's name specified in the constructor +- **client** - _[Client](https://discord.js.org/#/docs/main/stable/class/Client)_ - Discord.js client instance +- **commands** - _CommandManager_ - base of the command system (see [Commands](#commands)) +- **config** - _object_ - object that stores the login token and _helpMessage_ value from the constructor +- **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 + > [IMPORTANT] -> All commands have to be declared above the *start* method +> All commands have to be declared above the _start_ method + ### All parameters -- **name** - *string* - command name (used to trigger the command) -- **function** - *Function* - function that will trigger when the commands gets called -- **visible** - *boolean* - show command in the *help message* (optional, defaults to *true*) -- **description** - *string* - command description shown in the *help message* (optional) -- **usage** - *string* - command usage 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") -- **permissions** - *[PermissionResolvable](https://discord.js.org/#/docs/main/stable/typedef/PermissionResolvable)* - permissions needed to run the command (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) + +- **name** - _string_ - command name (used to trigger the command) +- **function** - _Function_ - function that will trigger when the commands gets called +- **visible** - _boolean_ - show command in the _help message_ (optional, defaults to _true_) +- **description** - _string_ - command description shown in the _help message_ (optional) +- **usage** - _string_ - command usage 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") +- **permissions** - _[PermissionResolvable](https://discord.js.org/#/docs/main/stable/typedef/PermissionResolvable)_ - permissions needed to run the command (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 + #### 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 + 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 + 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 + #### Simple reply + 1. Create a command + ```javascript //CREATE COMMAND const command = new Command({ name: "ping", function: (m, a) => { - return 'pong'; - } + return "pong"; + }, }); //APPEND IT TO THE COMMANDS LIST bot.commands.add(command); ``` + or + ```javascript -bot.commands.add(new Command({ - name: "ping", - function: (m, a) => { - return 'pong'; - } -})); +bot.commands.add( + new Command({ + name: "ping", + function: (m, a) => { + return "pong"; + }, + }) +); ``` + 2. Call it from Discord text channel (example prefix: "!") + ``` -!ping +!ping Result: @mention, pong ``` + #### Example with arguments + 1. Create a command + ```javascript const command = new Command({ name: "repeat", function: async (m, a) => { - if(a[0] && a[1]) { + if (a[0] && a[1]) { const count = parseInt(a[1]); - if(!isNaN(count)) { - for(let i = 0; i < count; i++) { + 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'); + } else { + throw new Error("Number of messages is incorrect"); } } - } + }, }); bot.commands.add(command); ``` + or + ```javascript -bot.commands.add(new Command({ - name: "repeat", - function: async (m, a) => { - if(a[0] && a[1]) { - const count = parseInt(a[1]); - if(!isNaN(count)) { - for(let i = 0; i < count; i++) { - await m.channel.send(a[0]); +bot.commands.add( + new Command({ + name: "repeat", + function: async (m, a) => { + if (a[0] && a[1]) { + 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'); - } - } - } -})); + }, + }) +); ``` + 2. Call it from Discord text channel (example prefix: "!", example separator: "," [default]) + ``` !repeat test, 5 @@ -179,75 +223,103 @@ test test @caller, Repeated "test" 5 times ``` + ## 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) -- **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] -> Do not use client.on('message') event handler! This handler is a core part of the command system. + +Events are emitted using built-in event emitter **(since version 2.0.0)**. You can handle them using _on_ property + +- **ready** - emitted when the client successfully connect to Discord API +- **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 -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 -Configuration parameters are stored in *messages.help* property -- **title** - *string* - title of help message -- **bottomText** - *string* - text shown below the title -- **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) + +Configuration parameters are stored in _messages.help_ property + +- **title** - _string_ - title of help message +- **bottomText** - _string_ - text shown below the title +- **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 -All options are stored in *messages.system* property + +All options are stored in _messages.system_ property There are 3 types of system messages -- Error message (**ERROR**) -- Command not found message (**NOT_FOUND**) -- Insufficient permissions message (**PERMISSION**) + +- Error message (**ERROR**) +- Command not found message (**NOT_FOUND**) +- Insufficient permissions message (**PERMISSION**) 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 + ```javascript -import { Bot, Command } from 'commandbot'; +import { Bot, Command } from "commandbot"; const bot = new Bot({ name: "CommandBot", - prefix: "!" + prefix: "!", }); -bot.messages.help.accentColor = '#ff0000'; +bot.messages.help.accentColor = "#ff0000"; bot.messages.system.NOT_FOUND.accentColor = "BLUE"; //Command triggers: !ping, !pong, pingpong -bot.commands.add(new Command({ - name: 'ping', - aliases: 'pong', - keywords: 'pingpong', - function: (m, a) => { - return 'Bot ping: ' + bot.client.ws.ping + 'ms'; - } -})); -bot.commands.add(new Command({ - name: "repeat", - function: async (m, a) => { - if(a[0] && a[1]) { - const count = parseInt(a[1]); - if(!isNaN(count)) { - for(let i = 0; i < count; i++) { - await m.channel.send(a[0]); +bot.commands.add( + new Command({ + name: "ping", + aliases: "pong", + keywords: "pingpong", + function: (m, a) => { + return "Bot ping: " + bot.client.ws.ping + "ms"; + }, + }) +); +bot.commands.add( + new Command({ + name: "repeat", + function: async (m, a) => { + if (a[0] && a[1]) { + 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'); -``` \ No newline at end of file +bot.start(3000, "TOKEN"); +```