├── .gitignore ├── README.md ├── SUMMARY.md ├── adding-more-command-groups.md ├── checking-for-permissions.md ├── checking-for-user-permissions.md ├── getting-started.md ├── making-your-first-command.md ├── removing-the-unknown-command-response.md ├── setting-a-command-to-guild-only.md ├── setting-a-database-provider.md ├── setting-a-default-value-for-an-arg.md ├── using-a-richembed-in-a-command.md ├── using-a-validator-for-an-arg.md ├── using-aliases-in-commands.md ├── using-an-async-run-method.md ├── using-args-in-commands.md ├── using-client-values-in-a-command.md ├── using-multiple-args-in-one-command.md └── using-throttling-in-commands.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Node rules: 2 | ## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 3 | .grunt 4 | 5 | ## Dependency directory 6 | ## Commenting this out is preferred by some people, see 7 | ## https://docs.npmjs.com/misc/faq#should-i-check-my-node_modules-folder-into-git 8 | node_modules 9 | 10 | # Book build output 11 | _book 12 | 13 | # eBook build output 14 | *.epub 15 | *.mobi 16 | *.pdf -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Discord.js Commando Beginner's Guide 2 | 3 | So I noticed there are very few resources to begin using the Commando command framework for Discord.js. Sure, there are a few tutorials out there, but they don't teach fundamental things such as args or how to properly use Commando's built-in `say`, `embed`, etc. That's what this guide is for. In this guide I will attempt to explain everything in commando from using args to when to use async for your commands. It's the least I can do for the people at Discord.js who helped me greatly on learning how to use it. 4 | 5 | #### Before You Begin 6 | 7 | Before you start with this guide I recommend you take a look at the official Discord.js guide. It'll teach you the fundamentals for Discord.js, which you can use to aid you in understanding this guide. Please note that I'm going to assume you have read that guide before this one. You can find that guide [here](http://discordjs.guide/). 8 | 9 | #### More Information 10 | 11 | Should you need more help after using this guide be sure to the Discord.js Official Server, where a Commando channel is available for all your questions. You can join that server with [this link](https://discord.gg/bRCvFy9). 12 | 13 | #### Updating of this Guide 14 | 15 | I will create a new chapter every once in a while until I deem this tutorial complete. Should anything else come up that you think I should explain, feel free to ask for it to be implemented. 16 | 17 | -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | ## Starting 4 | 5 | * [Introduction](README.md) 6 | * [Getting Started](getting-started.md) 7 | * [First Command](making-your-first-command.md) 8 | * [Adding Groups](adding-more-command-groups.md) 9 | 10 | ## Args 11 | 12 | * [Args](using-args-in-commands.md) 13 | * [Multiple Args](using-multiple-args-in-one-command.md) 14 | * [Validators](using-a-validator-for-an-arg.md) 15 | * [Aliases](using-aliases-in-commands.md) 16 | * [Throttling](using-throttling-in-commands.md) 17 | * [Default](setting-a-default-value-for-an-arg.md) 18 | 19 | ## Commands 20 | 21 | * [Guild Only](setting-a-command-to-guild-only.md) 22 | * [async run Method](using-an-async-run-method.md) 23 | * [Client Permissions](checking-for-permissions.md) 24 | * [User Permissions](checking-for-user-permissions.md) 25 | 26 | ## Settings 27 | 28 | * [Settings Provider](setting-a-database-provider.md) 29 | 30 | ## Other Stuff 31 | 32 | * [Client Values](using-client-values-in-a-command.md) 33 | * [RichEmbeds](using-a-richembed-in-a-command.md) 34 | * [Unknown Command Response Removal](removing-the-unknown-command-response.md) 35 | 36 | -------------------------------------------------------------------------------- /adding-more-command-groups.md: -------------------------------------------------------------------------------- 1 | # Adding Groups 2 | 3 | Before we make our new argument-powered command, I think we should place it within it's own command group. Then, we can have multiple commands sorted separately in our help command and folder structure. 4 | 5 | First, head on over to our `index.js` file and find where we registered our commands. 6 | 7 | ```js 8 | client.registry 9 | .registerDefaultTypes() 10 | .registerGroups([ 11 | ['group1', 'Our First Command Group'] 12 | ]) 13 | .registerDefaultGroups() 14 | .registerDefaultCommands() 15 | .registerCommandsIn(path.join(__dirname, 'commands')); 16 | ``` 17 | 18 | Place a `,` after our `group1` and add another group called `group2`. 19 | 20 | ```js 21 | client.registry 22 | .registerDefaultTypes() 23 | .registerGroups([ 24 | ['group1', 'Our First Command Group'], 25 | ['group2', 'Our Second Command Group'] 26 | ]) 27 | .registerDefaultGroups() 28 | .registerDefaultCommands() 29 | .registerCommandsIn(path.join(__dirname, 'commands')); 30 | ``` 31 | 32 | You can add as many of these as you want. 33 | 34 | The next step is to create another folder in your `commands` folder, called `group2`, just like with our `group1` folder. 35 | 36 | And there you go, another command group for our new command! 37 | 38 | -------------------------------------------------------------------------------- /checking-for-permissions.md: -------------------------------------------------------------------------------- 1 | # Client Permissions 2 | 3 | Sometimes you're going to have a command and start getting a `Forbidden` error. Why? Well, most likely you don't have permissions in the guild to do something. Commando will automatically check for the Send Messages permission and reroute the command to a DM, but for things like Embed Links or Manage Messages you may want to perform a permission check before using the command. Thankfully, this is quite simple. 4 | 5 | Let's grab our say command example from the earlier chapter, as it would fail should the command be used without permissions. We'll start by going into it's `constructor`. 6 | 7 | ```js 8 | super(client, { 9 | name: 'say', 10 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 11 | group: 'group2', 12 | memberName: 'say', 13 | description: 'Replies with the text you provide.', 14 | examples: ['say Hi there!'], 15 | args: [ 16 | { 17 | key: 'text', 18 | prompt: 'What text would you like the bot to say?', 19 | type: 'string' 20 | } 21 | ] 22 | }); 23 | ``` 24 | 25 | Now, obviously the message delete is going to fail if the command is used without permission to Manage Messages. So, we need to perform a check before the command is run. Thankfully, commando now has a simple and easy way of doing this. 26 | 27 | ```js 28 | super(client, { 29 | name: 'say', 30 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 31 | group: 'group2', 32 | memberName: 'say', 33 | description: 'Replies with the text you provide.', 34 | examples: ['say Hi there!'], 35 | clientPermissions: ['MANAGE_MESSAGES'], 36 | args: [ 37 | { 38 | key: 'text', 39 | prompt: 'What text would you like the bot to say?', 40 | type: 'string' 41 | } 42 | ] 43 | }); 44 | ``` 45 | 46 | That's it! 47 | 48 | -------------------------------------------------------------------------------- /checking-for-user-permissions.md: -------------------------------------------------------------------------------- 1 | # User Permissions 2 | 3 | In the last chapter we talked about how to check for bot permissions, in this chapter, we're going to be using a `hasPermission` method and the `userPermissions` option to check whether or not the user is the owner or has a certain permission before using the command. 4 | 5 | The `hasPermission` method can be anything you want, as long as it returns `true` or `false`. When it returns `true`, the command will run. When it returns `false`, the user will not be allowed to use the command. 6 | 7 | Doing this is quite simple. 8 | 9 | ```js 10 | hasPermission(msg) { 11 | return this.client.isOwner(msg.author); 12 | } 13 | ``` 14 | 15 | This will return `false` if the user is not the owner of the bot and `true` if they are. 16 | 17 | The `hasPermission` method should be placed separate from the `run` method, like so \(if you wanted your say command to only be usable by the owner\): 18 | 19 | ```js 20 | const { Command } = require('discord.js-commando'); 21 | 22 | module.exports = class SayCommand extends Command { 23 | constructor(client) { 24 | super(client, { 25 | name: 'say', 26 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 27 | group: 'group2', 28 | memberName: 'say', 29 | description: 'Replies with the text you provide.', 30 | examples: ['say Hi there!'], 31 | guildOnly: true, 32 | args: [ 33 | { 34 | key: 'text', 35 | prompt: 'What text would you like the bot to say?', 36 | type: 'string' 37 | } 38 | ] 39 | }); 40 | } 41 | 42 | hasPermission(msg) { 43 | return this.client.isOwner(msg.author); 44 | } 45 | 46 | run(msg, { text }) { 47 | msg.delete(); 48 | return msg.say(text); 49 | } 50 | }; 51 | ``` 52 | 53 | Simple. 54 | 55 | You can also return a string for a custom response. 56 | 57 | ```js 58 | hasPermission(msg) { 59 | if (!this.client.isOwner(msg.author)) return 'Only the bot owner(s) may use this command.'; 60 | return true; 61 | } 62 | ``` 63 | 64 | Neat, huh? 65 | 66 | Another thing you might want to do is check for specific user permissions, such as if a user has permissions in the current channel to manage messages. We can do that even more simply with the `userPermissions` option. 67 | 68 | ```js 69 | super(client, { 70 | name: 'say', 71 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 72 | group: 'group2', 73 | memberName: 'say', 74 | description: 'Replies with the text you provide.', 75 | examples: ['say Hi there!'], 76 | userPermissions: ['MANAGE_MESSAGES'], 77 | args: [ 78 | { 79 | key: 'text', 80 | prompt: 'What text would you like the bot to say?', 81 | type: 'string' 82 | } 83 | ] 84 | }); 85 | ``` 86 | 87 | Just like `clientPermissions`. 88 | 89 | -------------------------------------------------------------------------------- /getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | When you got your first bot up and running with Discord.js, you should've installed Discord.js using npm, Node.js' Package Manager. The same applies to Commando, which must be separately installed. You can do this in one of two ways: 4 | 5 | Stable: `npm i -S discordjs/Commando#11.2` 6 | Master: `npm i -S discordjs/Commando` 7 | 8 | If you're using Discord.js master, you'll need Commando master, and vice-versa. 9 | 10 | Also note that you are going to need at least Node.js version 7.6.0. Download Node [here](https://nodejs.org/en/). If on master, you'll need at least Node 8. 11 | 12 | #### Creating Your index.js File 13 | 14 | While it doesn't have to be called `index.js`, the index file is your main file for your bot, which handles everything from registering new commands to logging in your client. It's quite similar to standard Discord.js in many ways, but there are a few extra steps that need to be done to get your bot up and running. 15 | 16 | First thing is to require Commando. Contrary to what you may think, you do **not** need to require Discord.js to use Commando. That is, unless you are going to use a MessageEmbed, but more on that later. 17 | 18 | For now, simply require Commando. We'll also be requiring `path` for use later on. Don't worry, you don't have to install `path`. 19 | 20 | ```js 21 | const { CommandoClient } = require('discord.js-commando'); 22 | const path = require('path'); 23 | ``` 24 | 25 | Look familiar? That's just about the same way you required Discord.js in your first bot. The next step is to create a new Commando Client. There's also a few options we are going to set. Some of these are optional, but recommended. 26 | 27 | ```js 28 | const client = new CommandoClient({ 29 | commandPrefix: '', 30 | owner: '', 31 | disableEveryone: true 32 | }); 33 | ``` 34 | 35 | Looks quite similar to your Discord.js Client doesn't it? Well, aside from all the options and stuff. 36 | 37 | In `commandPrefix`, you should insert the prefix you intend to have for your bot. As of writing, you can only have one, so choose wisely! However, note that a mention will **always** be allowed alongside your prefix you set here. In other words, this prefix and mentions are how you will use your bot. **No, there is no way to disable mentions being a prefix!** 38 | 39 | After that is the `owner` field, which should contain the User ID for the owner of the bot. **The user you set here has complete control over the bot, can use eval and other Owner-Only Commands, and ignores command throttling and user permissions!** So, be sure to only give this to yourself. 40 | Also, if you installed master earlier, this can also be an array of IDs instead of a single one. 41 | 42 | ```js 43 | owner: ['ID', 'ID'] 44 | ``` 45 | 46 | The final option, `disableEveryone`, simply prevents the bot from mentioning `@everyone`. This is simply to prevent things from getting annoying. After all, do you want someone mentioning everyone with the bot? Didn't think so. 47 | 48 | Next we're going to register the command groups, args types, and default commands, and register the commands in a folder called `commands`. You can name the folder whatever you want, but I personally recommend `commands` , as it... Well, it makes the most sense. 49 | 50 | ```js 51 | client.registry 52 | .registerDefaultTypes() 53 | .registerGroups([ 54 | ['group1', 'Our First Command Group'] 55 | ]) 56 | .registerDefaultGroups() 57 | .registerDefaultCommands() 58 | .registerCommandsIn(path.join(__dirname, 'commands')); 59 | ``` 60 | 61 | Remember how I said we'd need path? There you go. 62 | 63 | Doing this we've also created our first command group, in the folder `group1` in our `commands` folder. It will be displayed in the help command as 'Our First Command Group'. You can name both of these whatever you like. 64 | 65 | Should you want to disable a default command, say, the help command, you can pass that in `registerDefaultCommands`. 66 | 67 | ```js 68 | .registerDefaultCommands({ 69 | help: false 70 | }) 71 | ``` 72 | 73 | Next, we're going to create a ready event, which is about the same as the one in your first Discord.js Bot. 74 | 75 | ```js 76 | client.on('ready', () => { 77 | console.log('Logged in!'); 78 | client.user.setActivity('game'); 79 | }); 80 | ``` 81 | 82 | This will send `Logged in!` to your console when the bot is ready, and set the Bot's Game to 'Game'. Set that to whatever you wish. 83 | 84 | Last but certainly not least, let's log the bot in. 85 | 86 | ```js 87 | client.login('Your Secret Token'); 88 | ``` 89 | 90 | You can also use environment variables or a `config.json` for your token instead of passing it directly. 91 | 92 | And there you have it! You've set up your `index.js` file! You should now create the `commands` and `group1` folders, in the end your file structure should look like this, along with whatever `.gitignore` or `config.json` you may have: 93 | 94 | ```markdown 95 | commands 96 | - group1 97 | index.js 98 | package.json 99 | ``` 100 | 101 | And your `index.js` file should look something like this: 102 | 103 | ```js 104 | const { CommandoClient } = require('discord.js-commando'); 105 | const path = require('path'); 106 | 107 | const client = new CommandoClient({ 108 | commandPrefix: '', 109 | unknownCommandResponse: false, 110 | owner: '', 111 | disableEveryone: true 112 | }); 113 | 114 | client.registry 115 | .registerDefaultTypes() 116 | .registerGroups([ 117 | ['group1', 'Our First Command Group'] 118 | ]) 119 | .registerDefaultGroups() 120 | .registerDefaultCommands() 121 | .registerCommandsIn(path.join(__dirname, 'commands')); 122 | 123 | client.on('ready', () => { 124 | console.log('Logged in!'); 125 | client.user.setActivity('game'); 126 | }); 127 | 128 | client.login('Your Secret Token'); 129 | ``` 130 | 131 | In the next section, we'll create our first command! How exciting! See you then! 132 | 133 | -------------------------------------------------------------------------------- /making-your-first-command.md: -------------------------------------------------------------------------------- 1 | # First Command 2 | 3 | So now that we've set up a command group and registered our command folder, we're ready to make our first command file! First, you're going to need to, of course, create a new file for the command. Hop over to your `commands` folder, and then your `group1` folder, and make a new file called `reply.js`. This is going to be a simple command that only replies with a message when used. We'll go into arguments and all that later. 4 | 5 | Once you have your file, let's get started! 6 | 7 | #### Creating Your Command Class 8 | 9 | Before you do anything, at the start of your file, you're going to need to require commando again. 10 | 11 | ```js 12 | const { Command } = require('discord.js-commando'); 13 | ``` 14 | 15 | This will allow our command to... Well, exist. 16 | 17 | Now, commands are classes exported with `module.exports`. So let's create the class and set `module.exports` to it. 18 | 19 | ```js 20 | module.exports = class ReplyCommand extends Command { 21 | constructor(client) { 22 | super(client, { 23 | name: 'reply', 24 | group: 'group1', 25 | memberName: 'reply', 26 | description: 'Replies with a Message.', 27 | examples: ['reply'] 28 | }); 29 | } 30 | ``` 31 | 32 | Don't let this scare you, it's actually very simple. 33 | 34 | `name` is the name of the command. 35 | `group` is the command group it is a part of. 36 | `memberName` is the name of the command within the group. 37 | `description` is the help text displayed when the help command is used. 38 | `examples` is an array of examples on how to use the command. 39 | 40 | There are many more properties, but more on those later on. For now, these are the ones we're going to focus on. 41 | 42 | #### Creating Your Run Method 43 | 44 | The next thing we're going to need is a `run` method. This should go right below the constructor for the command. Inside, let's return a message: 45 | 46 | ```js 47 | run(msg) { 48 | return msg.say('Hi, I\'m awake!'); 49 | } 50 | }; 51 | ``` 52 | 53 | That also closed off our command class' brackets, so yay! 54 | 55 | Anyway, as you can see, the `run` method is simply the code you want the bot to run when the command is used. This can be anything you can do in normal discord.js, as commando is simply an extension. 56 | 57 | You may have also noticed that I used `message.say` instead of `message.channel.send`. This is commando's magic. Instead of `send`, use `say`. Instead of `sendEmbed`, use `embed`. Instead of `sendCode`, use `code`, you get the idea. The only real exception I can think of is files, which are still `message.channel.sendFile`. 58 | 59 | So when all that is done, your file should look like this: 60 | 61 | ```js 62 | const { Command } = require('discord.js-commando'); 63 | 64 | module.exports = class ReplyCommand extends Command { 65 | constructor(client) { 66 | super(client, { 67 | name: 'reply', 68 | group: 'group1', 69 | memberName: 'reply', 70 | description: 'Replies with a Message.', 71 | examples: ['reply'] 72 | }); 73 | } 74 | 75 | run(msg) { 76 | return msg.say('Hi, I\'m awake!'); 77 | } 78 | }; 79 | ``` 80 | 81 | Now, fire up the bot as normal and use your command! It should automatically be `reply` to use it. 82 | 83 | In the next tutorial we'll dive into how to use arguments in your commands! See you then! 84 | 85 | -------------------------------------------------------------------------------- /removing-the-unknown-command-response.md: -------------------------------------------------------------------------------- 1 | # Unknown Command Response Removal 2 | 3 | Sometimes, you may want to remove the \(somewhat annoying\) unknown command response from your bot. Be it Cleverbot or other reason, sometimes you just want it gone, and it's quite simple to remove. 4 | 5 | Head over to your `index.js` file and find your `client`. We're going to be adding a new setting here. 6 | 7 | ```js 8 | const client = new commando.Client({ 9 | commandPrefix: '', 10 | owner: '', 11 | disableEveryone: true 12 | }); 13 | ``` 14 | 15 | All you have to do to remove the unknown command response is set `unknownCommandResponse` to `false`. 16 | 17 | ```js 18 | const client = new commando.Client({ 19 | commandPrefix: '', 20 | owner: '', 21 | disableEveryone: true, 22 | unknownCommandResponse: false 23 | }); 24 | ``` 25 | 26 | And that's all there is to it. 27 | 28 | -------------------------------------------------------------------------------- /setting-a-command-to-guild-only.md: -------------------------------------------------------------------------------- 1 | # Guild Only 2 | 3 | You may have noticed that should you use your say command in a DM, you are going to get a `Forbidden` error due to attempting to delete a message from the other user in DM. One easy way around this? Setting the command to guild only! 4 | 5 | First, let's go into your say command's file and find our command data. 6 | 7 | ```js 8 | super(client, { 9 | name: 'say', 10 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 11 | group: 'group2', 12 | memberName: 'say', 13 | description: 'Replies with the text you provide.', 14 | examples: ['say Hi there!'], 15 | args: [ 16 | { 17 | key: 'text', 18 | prompt: 'What text would you like the bot to say?', 19 | type: 'string' 20 | } 21 | ] 22 | }); 23 | ``` 24 | 25 | After `examples` \(though it can be anywhere in this section\) let's add a `guildOnly` setting and set it to `true`. 26 | 27 | ```js 28 | super(client, { 29 | name: 'say', 30 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 31 | group: 'group2', 32 | memberName: 'say', 33 | description: 'Replies with the text you provide.', 34 | examples: ['say Hi there!'], 35 | guildOnly: true, 36 | args: [ 37 | { 38 | key: 'text', 39 | prompt: 'What text would you like the bot to say?', 40 | type: 'string' 41 | } 42 | ] 43 | }); 44 | ``` 45 | 46 | And that's all there is to it! Now, when used in a DM, the bot will not permit the command to be used, and you will no longer receive errors... Unless the bot doesn't have permissions in the guild. But more on that in the next chapter. 47 | 48 | -------------------------------------------------------------------------------- /setting-a-database-provider.md: -------------------------------------------------------------------------------- 1 | # Settings Provider 2 | 3 | Commando has a built-in way of storing guild settings. By default things such as the guild's custom prefix or disabled commands will be stored for Data Persistence, and you can also have your own custom settings as well. 4 | 5 | Setting a Database Provider is simple, and there are many ways to accomplish it. 6 | 7 | 1. You can use an sqliteProvider, which comes built-in with Commando. 8 | 2. You can use the [SequelizeProvider](https://github.com/WeebDev/Commando/blob/master/providers/Sequelize.js), created by Crawl. 9 | 3. You can find another or make your own. 10 | 11 | This chapter will only go over the first one. 12 | 13 | sqliteProvider comes built-in with Commando, you won't have to copy any files to use it. It's actually extremely simple, all you need to do is, firstly, install sqlite. 14 | 15 | `npm i -S sqlite` 16 | 17 | Then, require it of course. 18 | 19 | `const sqlite = require('sqlite');` 20 | 21 | You'll also need to require SQLiteProvider from Commando, where we required the CommandoClient earlier on. 22 | 23 | `const { CommandoClient, SQLiteProvider } = require('discord.js-commando');` 24 | 25 | And lastly, setup the provider. 26 | 27 | ```js 28 | sqlite.open(path.join(__dirname, "settings.sqlite3")).then((db) => { 29 | client.setProvider(new SQLiteProvider(db)); 30 | }); 31 | ``` 32 | 33 | And there, an sqlite provider. 34 | 35 | -------------------------------------------------------------------------------- /setting-a-default-value-for-an-arg.md: -------------------------------------------------------------------------------- 1 | # Default 2 | 3 | Sometimes you may want an argument to be optional. In that case, you can use `default`. 4 | 5 | Let's say you have a command that rolls a dice, it's args would probably looking something like this: 6 | 7 | ```js 8 | args: [ 9 | { 10 | key: 'value', 11 | prompt: 'What is the maximum number you wish to appear?', 12 | type: 'integer' 13 | } 14 | ] 15 | ``` 16 | 17 | Let's say you wanted it to default to `6` if not set, like a real dice. 18 | 19 | ```js 20 | args: [ 21 | { 22 | key: 'value', 23 | prompt: 'What is the maximum number you wish to appear?', 24 | type: 'integer', 25 | default: 6 26 | } 27 | ] 28 | ``` 29 | 30 | And then it will be 6 if no argument is set. 31 | 32 | You can take advantage of this to create completely optional arguments, for example: 33 | 34 | ```js 35 | args: [ 36 | { 37 | key: 'value', 38 | prompt: 'What is the maximum number you wish to appear?', 39 | type: 'integer', 40 | default: '' 41 | } 42 | ] 43 | ``` 44 | 45 | This sets the default to `''`, which is falsey. Then, in your run, you can handle that. 46 | 47 | ```js 48 | if (!value) { 49 | // do this 50 | } else { 51 | // do something else 52 | } 53 | ``` 54 | 55 | 56 | 57 | -------------------------------------------------------------------------------- /using-a-richembed-in-a-command.md: -------------------------------------------------------------------------------- 1 | # RichEmbeds/MessageEmbeds 2 | 3 | You may have noticed that if you try to use a RichEmbed \(or MessageEmbed for master\) in your command, that there's no way to create the new embed, as `new Discord.RichEmbed()` is going to say `Discord` is undefined. That's because when using a RichEmbed, we need to require Discord.js alongside Commando. 4 | 5 | ```js 6 | const { Command } = require('discord.js-commando'); 7 | const { RichEmbed } = require('discord.js'); 8 | ``` 9 | 10 | Now that it has been required, our RichEmbed won't be undefined. Let's create a new command that embeds the content of the user's message. 11 | 12 | ```js 13 | const { Command } = require('discord.js-commando'); 14 | const { RichEmbed } = require('discord.js'); 15 | 16 | module.exports = class EmbedCommand extends Command { 17 | constructor(client) { 18 | super(client, { 19 | name: 'embed', 20 | group: 'group2', 21 | memberName: 'embed', 22 | description: 'Embeds the text you provide.', 23 | examples: ['embed Embeds are cool.'], 24 | args: [ 25 | { 26 | key: 'text', 27 | prompt: 'What text would you like the bot to embed?', 28 | type: 'string' 29 | } 30 | ] 31 | }); 32 | } 33 | 34 | run(msg, args) { 35 | const { text } = args; 36 | const embed = new RichEmbed() 37 | .setDescription(text) 38 | .setAuthor(msg.author.username, msg.author.displayAvatarURL) 39 | .setColor(0x00AE86) 40 | .setTimestamp(); 41 | return msg.embed(embed); 42 | } 43 | }; 44 | ``` 45 | 46 | Simple isn't it? It's just like regular Discord.js RichEmbeds. 47 | 48 | -------------------------------------------------------------------------------- /using-a-validator-for-an-arg.md: -------------------------------------------------------------------------------- 1 | # Validators 2 | 3 | Sometimes you're going to want an argument to be a certain thing, for example, a certain text, or maybe you want to check the length, there's many things you may want to do. This can be accomplished with a `validate` in your arg. 4 | 5 | Let's say you have a command where your first argument has to match a certain text, for example if we wanted our say command to only allow 200 characters to be said, and no more. It's very simple. 6 | 7 | First, let's pull our argument from our say command: 8 | 9 | ```js 10 | args: [ 11 | { 12 | key: 'text', 13 | prompt: 'What text would you like the bot to say?', 14 | type: 'string' 15 | } 16 | ] 17 | ``` 18 | 19 | Let's add a blank `validate` to the arg. 20 | 21 | ```js 22 | args: [ 23 | { 24 | key: 'text', 25 | prompt: 'What text would you like the bot to say?', 26 | type: 'string', 27 | validate: text => {} 28 | } 29 | ] 30 | ``` 31 | 32 | Inside our validate, let's check to see if the length is below 201 characters, and return `true` if it does. 33 | 34 | ```js 35 | validate: text => { 36 | if (text.length < 201) return true; 37 | } 38 | ``` 39 | 40 | Now, below that, let's let it return an error message if that check does not pass. 41 | 42 | ```js 43 | validate: text => { 44 | if (text.length < 201) return true; 45 | return 'Message Content is above 200 characters'; 46 | } 47 | ``` 48 | 49 | In the end, your args should look like this: 50 | 51 | ```js 52 | args: [ 53 | { 54 | key: 'text', 55 | prompt: 'What text would you like the bot to say?', 56 | type: 'string', 57 | validate: text => { 58 | if (text.length < 201) return true; 59 | return 'Message Content is above 200 characters'; 60 | } 61 | } 62 | ] 63 | ``` 64 | 65 | And now you've got a validator. 66 | 67 | -------------------------------------------------------------------------------- /using-aliases-in-commands.md: -------------------------------------------------------------------------------- 1 | # Aliases 2 | 3 | Aliases are simply different ways to call the same command. They're extremely simple to do. 4 | 5 | Let's, once again, grab our say command. Head over to all of the command properties. 6 | 7 | ```js 8 | super(client, { 9 | name: 'say', 10 | group: 'group2', 11 | memberName: 'say', 12 | description: 'Replies with the text you provide.', 13 | examples: ['say Hi there!'], 14 | args: [ 15 | { 16 | key: 'text', 17 | prompt: 'What text would you like the bot to say?', 18 | type: 'string' 19 | } 20 | ] 21 | }); 22 | ``` 23 | 24 | Underneath the `name` property, let's place the aliases. We'll set them to copycat, repeat, echo, and parrot. 25 | 26 | ```js 27 | super(client, { 28 | name: 'say', 29 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 30 | group: 'group2', 31 | memberName: 'say', 32 | description: 'Replies with the text you provide.', 33 | examples: ['say Hi there!'], 34 | args: [ 35 | { 36 | key: 'text', 37 | prompt: 'What text would you like the bot to say?', 38 | type: 'string' 39 | } 40 | ] 41 | }); 42 | ``` 43 | 44 | Now, you can use `say`, `copycat`, `echo`, etc. and all of them will call our say command. 45 | 46 | Also, note that aliases and command names are automatically case insensitive. `say` `SaY` and `sAy` are all valid here. Auto-Aliases are also created for aliases and command names containing a hyphen \(-\). For example, `server-info` will automatically have `serverinfo` as an alias without needing to list it in the aliases. Cool, huh? 47 | 48 | -------------------------------------------------------------------------------- /using-an-async-run-method.md: -------------------------------------------------------------------------------- 1 | # async run Method 2 | 3 | `async` is a simple way to make your Promise-Powered code look _extremely_ neat. Normally with promises, we would use `.then` to continue running the command after the promise has resolved. 4 | 5 | ```js 6 | msg.say('Hi').then(message => { 7 | message.edit('Hello'); 8 | }); 9 | ``` 10 | 11 | However, `async` can make this much easier to do. 12 | 13 | ```js 14 | const message = await msg.say('Hi'); 15 | message.edit('Hello'); 16 | ``` 17 | 18 | Now we've completely dropped the indentation, and our code looks cleaner because of it. 19 | 20 | Let's modify our first command, reply, to edit the message after it has been sent, and let's use `async` to do it. 21 | 22 | First, mark the `run` method with the `async` keyword. 23 | 24 | ```js 25 | async run(msg) { 26 | return msg.say('Hi, I\'m awake!'); 27 | } 28 | ``` 29 | 30 | Now, let's edit the message we send from 'Hi, I'm awake!' to 'I want to go to bed.'. 31 | 32 | ```js 33 | async run(msg) { 34 | const message = await msg.say('Hi, I\'m awake!'); 35 | return message.edit('I want to go to bed.'); 36 | } 37 | ``` 38 | 39 | You can `await` anything that returns a Promise. In other words, anything you can perform a `.then` on can be swapped with `await`. `async` is very useful for making code cleaner, especially if you have lots of Promises you're performing `.then` on. 40 | 41 | In the end, our Reply command looks like this: 42 | 43 | ```js 44 | const { Command } = require('discord.js-commando') 45 | 46 | module.exports = class ReplyCommand extends Command { 47 | constructor(client) { 48 | super(client, { 49 | name: 'reply', 50 | group: 'group1', 51 | memberName: 'reply', 52 | description: 'Replies with a Message.' 53 | }); 54 | } 55 | 56 | async run(msg) { 57 | const message = await msg.say('Hi, I\'m awake!'); 58 | return message.edit('I want to go to bed.'); 59 | } 60 | }; 61 | ``` 62 | 63 | Now just remember, don't use `async` for everything. 64 | 65 | -------------------------------------------------------------------------------- /using-args-in-commands.md: -------------------------------------------------------------------------------- 1 | # Args 2 | 3 | Sometimes when using commands we may want to get data from our user to narrow down the command further. In this section we'll create a command that pulls a string from the message and says it back to the user. 4 | 5 | A `string` argument is simply the text after the command name and prefix. For example, `!say Hi there!` would cause our arg to be `Hi there!`. It's quite simple to create one. For our example, we'll be making the aforementioned say command. 6 | 7 | First, go into your `group2` folder and make a new file called `say.js`. You know the drill. Once you have it, set up your command class and everything just like the one in our reply command. 8 | 9 | ```js 10 | const { Command } = require('discord.js-commando'); 11 | 12 | module.exports = class SayCommand extends Command { 13 | constructor(client) { 14 | super(client, { 15 | name: 'say', 16 | group: 'group2', 17 | memberName: 'say', 18 | description: 'Replies with the text you provide.', 19 | examples: ['say Hi there!'] 20 | }); 21 | } 22 | 23 | run(msg) { 24 | 25 | } 26 | }; 27 | ``` 28 | 29 | Place a `,` after the `examples` field, we're going to be adding an `args` field. 30 | 31 | The `args` field is simply an array of objects, each containing data for that argument. 32 | 33 | ```js 34 | super(client, { 35 | name: 'say', 36 | group: 'group2', 37 | memberName: 'say', 38 | description: 'Replies with the text you provide.', 39 | examples: ['say Hi there!'], 40 | args: [ 41 | { 42 | key: 'text', 43 | prompt: 'What text would you like the bot to say?', 44 | type: 'string' 45 | } 46 | ] 47 | }); 48 | ``` 49 | 50 | See? Simple. 51 | 52 | `key` is the name of the argument, when you define it in your `run` method, this is what we'll be using. 53 | `prompt` is the text that displays if no argument is provided. For example: someone just uses `say`. That prompt will come up asking for the text. 54 | `type` is the type the argument is a part of. This can be many things, including `string`, `integer`, `user`, `member`, you get the idea. We'll go over more of these later. 55 | 56 | Now, head on over to your `run` method and, firstly, set our `text` arg to a variable. 57 | 58 | ```js 59 | run(msg, { text }) { 60 | } 61 | ``` 62 | 63 | Next, let's make the `run` method return the message. 64 | 65 | ```js 66 | run(msg, { text }) { 67 | return msg.say(text); 68 | } 69 | ``` 70 | 71 | Let's also make it delete our original message before saying it. 72 | 73 | ```js 74 | run(msg, { text }) { 75 | msg.delete(); 76 | return msg.say(text); 77 | } 78 | ``` 79 | 80 | And there we have it, a say command using args! 81 | 82 | ```js 83 | const { Command } = require('discord.js-commando'); 84 | 85 | module.exports = class SayCommand extends Command { 86 | constructor(client) { 87 | super(client, { 88 | name: 'say', 89 | group: 'group2', 90 | memberName: 'say', 91 | description: 'Replies with the text you provide.', 92 | examples: ['say Hi there!'], 93 | args: [ 94 | { 95 | key: 'text', 96 | prompt: 'What text would you like the bot to say?', 97 | type: 'string' 98 | } 99 | ] 100 | }); 101 | } 102 | 103 | run(msg, { text }) { 104 | msg.delete(); 105 | return msg.say(text); 106 | } 107 | }; 108 | ``` 109 | 110 | And now we're done! 111 | 112 | -------------------------------------------------------------------------------- /using-client-values-in-a-command.md: -------------------------------------------------------------------------------- 1 | # Client Values 2 | 3 | This one is easy. Say you wanted to use a client value in your command, for example, you wanted to get the amount of guilds the bot was in. Normally, you'd do this: 4 | 5 | ```js 6 | client.guilds.size 7 | ``` 8 | 9 | However, in Commando, you have to use `this` to get these values. 10 | 11 | ```js 12 | this.client.guilds.size 13 | ``` 14 | 15 | That's all there is to it. 16 | 17 | -------------------------------------------------------------------------------- /using-multiple-args-in-one-command.md: -------------------------------------------------------------------------------- 1 | # Multiple Args 2 | 3 | Sometimes you may want to collect more than one piece of content from a message. Well, you're in luck, as Commando makes using multiple Arguments very simple. 4 | 5 | Let's create a simple command to send a DM to the user mentioned, and the content of the DM will be the content of the message after the mention. 6 | 7 | First, you know the drill, let's create our command class and run method. 8 | 9 | ```js 10 | const { Command } = require('discord.js-commando'); 11 | 12 | module.exports = class SayCommand extends Command { 13 | constructor(client) { 14 | super(client, { 15 | name: 'dm', 16 | group: 'group2', 17 | memberName: 'dm', 18 | description: 'Sends a message to the user you mention.', 19 | examples: ['dm @User Hi there!'], 20 | args: [] 21 | }); 22 | } 23 | 24 | run(msg, {}) { 25 | 26 | } 27 | }; 28 | ``` 29 | 30 | Now, let's define our args a little differently. Remember, `args` is just an array of objects. 31 | 32 | ```js 33 | args: [ 34 | { 35 | key: 'user', 36 | prompt: 'Which user do you want to send the DM to?', 37 | type: 'user' 38 | }, 39 | { 40 | key: 'content', 41 | prompt: 'What would you like the content of the message to be?', 42 | type: 'string' 43 | } 44 | ] 45 | ``` 46 | 47 | Simple, isn't it? Now, let's make the run method. 48 | 49 | ```js 50 | run(msg, { user, content }) { 51 | return user.send(content); 52 | } 53 | ``` 54 | 55 | See how easy it is? Now, the command has multiple args. 56 | 57 | ```js 58 | const { Command } = require('discord.js-commando'); 59 | 60 | module.exports = class SayCommand extends Command { 61 | constructor(client) { 62 | super(client, { 63 | name: 'dm', 64 | group: 'group2', 65 | memberName: 'dm', 66 | description: 'Sends a message to the user you mention.', 67 | examples: ['dm @User Hi there!'], 68 | args: [ 69 | { 70 | key: 'user', 71 | prompt: 'Which user do you want to send the DM to?', 72 | type: 'user' 73 | }, 74 | { 75 | key: 'content', 76 | prompt: 'What would you like the content of the message to be?', 77 | type: 'string' 78 | } 79 | ] 80 | }); 81 | } 82 | 83 | run(msg, { user, content }) { 84 | return user.send(content); 85 | } 86 | }; 87 | ``` 88 | 89 | Doesn't get much simpler than that. 90 | 91 | -------------------------------------------------------------------------------- /using-throttling-in-commands.md: -------------------------------------------------------------------------------- 1 | # Throttling 2 | 3 | Throttling is like rate-limiting, it only allows the command to be used in a certain period of time. A cooldown of sorts. They're very simple, as with most things I've explained in Commando. 4 | 5 | Let's \(for the millionth time\) grab our say command's properties. 6 | 7 | ```js 8 | super(client, { 9 | name: 'say', 10 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 11 | group: 'group2', 12 | memberName: 'say', 13 | description: 'Replies with the text you provide.', 14 | examples: ['say Hi there!'], 15 | args: [ 16 | { 17 | key: 'text', 18 | prompt: 'What text would you like the bot to say?', 19 | type: 'string' 20 | } 21 | ] 22 | }); 23 | ``` 24 | 25 | Now, let's add `throttling` to the command. `throttling` is an object, which contains two things: 26 | 27 | `usages` is the amount of times the command can be used in the given time period. 28 | `duration` is the amount of time the cooldown lasts, in seconds. 29 | 30 | Let's make it have 2 usages allowed in a 10 second period. 31 | 32 | ```js 33 | super(client, { 34 | name: 'say', 35 | aliases: ['copycat', 'repeat', 'echo', 'parrot'], 36 | group: 'group2', 37 | memberName: 'say', 38 | description: 'Replies with the text you provide.', 39 | examples: ['say Hi there!'], 40 | throttling: { 41 | usages: 2, 42 | duration: 10 43 | }, 44 | args: [ 45 | { 46 | key: 'text', 47 | prompt: 'What text would you like the bot to say?', 48 | type: 'string' 49 | } 50 | ] 51 | }); 52 | ``` 53 | 54 | And now the command has a cooldown. 55 | 56 | --------------------------------------------------------------------------------