Creating Commands

If you want your module to do anything, you're probably going to want some commands! Within ModBot, each command is its own separate file, and each command file may contain only one command.

To create a new command, you'll want to create a new JavaScript file in the configured commands folder for your module. If you are uncertain what folder this is, you can always check commands_directory in your bot_module.json. The JavaScript file can be named whatever you want, as long as its extension is .js.

Here is an example of a command file (ModBot/modules/<module_name>/<command_directory>/<command_name>.js):

module.exports = {
    name: 'ping',
    description: 'Sends a message back. Used to test if the bot is working.',
    syntax: 'ping [arbitrary argument for testing]',
    num_args: 0,
    args_to_lower: true,
    needs_api: false,
    has_state: false,
    execute(message, args, extra) {
      message.channel.send("Admin Pong!");
    }
};

Name	Description	Type	Example
name	The name of the command. This is what will determine how you call it.	String (no spaces)	If the module's command_prefix is / and the name of the command is ping, you'll invoke the command by typing /ping
description	This gives a description of the command, and what it does. It will be displayed to the user from some core commands.	String	"Responds with a message, to show if the server is working."
syntax	A string giving the syntax for your command and its arguments. Use <> for required arguments, [] for optional arguments, | for listing out possible values.	String	`ping <required_argument> [optional argument] [some_value
num_args	The number of REQUIRED arguments. If there are no required arguments, set to 0.	Integer	--
args_to_lower	If set to true, all arguments will be converted to lower case before reaching the command	Boolean	--
needs_api	Determines whether or not an instance of the API Client will be passed as a property of extra	Boolean	--
has_state	Determines whether the command uses ModBot's State System. If set to true, the command will receive a state as a property of extra	Boolean	--
execute()	The function that runs the command. This is where you put all your code.	Function	execute(message, args, extra)

The Execute Function

The code that your bot runs will go inside your command's execute() function. However, I would HIGHLY RECOMMEND that you don't place all of the code for your command inside this function, depending on how complex it is. It is always best to modularize your code, and abstract sections of the code out into separate functions, to make debugging easier.

Parameter	Description
message	This is the Discord.js message object that was created for the message that ran this command. Through this object, you can access pretty much all of the discord-related information and functions you'll need. Check out the Discord.js documentation for info on how to use it.
args	This is an array of strings, which make up the arguments of your command. This array includes the command itself (stripped of the command_prefix) at index 0.
extra	This is an object that contains other things as properties, that may be helpful when creating your command. See below for more information.

Object	Description	Condition
extra.api	An instance of core/js/APIClient which gives access to the database, through the API.	Only passed if needs_api == true
extra.module_handler	An instance of core/js/ModuleHandler, which gives the command access to the internals of ModBot.	Only passed if the module is a Core Module
extra.message_helper	An instance of core/js/MessageHelper, which includes helpful functions that deal with messages. You should ALWAYS use MessageHelper.send() to send messages, rather than message.channel.send(). This helps to ensure that the bot doesn't run into rate limit issues, or crash because the message is too large.	Always passed
extra.state	This is the state object related to this command and user. See Saved-State System for more info.	Only passed if has_state == true

Logging

ModBot uses the winston NodeJS module for all of its logging needs. This allows us to keep logs in files, as well as in the console, and it has a ton of other useful features.

Whenever you want to log something, please do not use console.log or console.error. Instead, you should use the Winston logging functions. If you are familiar with Winston, you'll know that you need a Logger object in order to be able to log anything. This can be found inside your command itself! Access the logger using this.logger.

Here are basic functions that you may need to use for the logger:

//To log at different levels
this.logger.log('error', 'This is an error!');
this.logger.log('warn', 'This is a warning.');
this.logger.log('info', 'This is info.');
this.logger.log('debug', 'This is a debug log statement');

//There are also shortcut functions
this.logger.error("This is an error");
this.logger.warn("This is a warning");
this.logger.info("This is an info log");
this.logger.debug("This is a debug log");

//You can also pass any data or objects you want and they will be printed
this.logger.info("This is an info log", { someData: "Here is a string", someMoreData: 12345 });

//Sometimes the above doesn't work like you'd expect it to. I think it's a bug.
//To get around this, pass everything as one object, and use "message" for the text.
this.logger.info({ message: "This is an info log", someData: "Here is a string", someMoreData: 12345 });

The log files are stored in ModBot/logs/.