CommandBot

A Discord.js based framework that makes creating Discord bots easy and fast.

Table of contents

• Instalation
  • System requirements
  • Creating a project
    • Registering Discord app
    • Creating application
• Commands
  • Creating and registering a command
  • Command function
    • Arguments
    • Return value
    • Errors
  • Parameters
    • Types
    • Defining
    • Reading input value

Installation

System requirements

• Node.js 16.6.0 or newer
• npm or yarn package manager

Creating a project

Registering Discord app

1. Visit Discord Developer Portal and create an app
2. Navigate to the Bot section and register a bot
3. Navigate to OAuth 2 section, select bot and application.commands scopes and check bot permissions
4. Copy the link and add your bot to the servers

Creating application

1. Create empty directory
2. Run npm init -y or yarn init -y
3. Add the CommandBot package

// npm
npm install commandbot@latest

// yarn
yarn add commandbot@latest

4. Create index.js file
5. Import the CommandBot package

// CommonJS
const { Bot, Command } = require("commandbot");

// ES Modules (to use ESM add "type": "module" to your package.json file)
import { Bot, Command } from "commandbot";

6. Initialize the bot instance

const bot = new Bot({
    name: "YOUR_BOT_NAME",
    prefix: "BOT_PREFIX",
    parameterSeparator: ",",
    clientOptions: {
        intents: [..."DISCORD_API_INTENTS"],
    },
    token: "DISCORD_BOT_TOKEN",
    applicationId: "APPLICATION_ID",
});

Properties (* - required):

• name* - string - bot name
• prefix - string - bot prefix to use with text commands (if undefined, only slash commands will be available)
• parameterSeparator - string - used to separate parameters from messages (default: ',')
• clientOptions - ClientOptions - Discord.js client options
• token* - string - Discord bot token
• applicationId* - string - Discord application ID

7. Create and add commands to the Bot instance (see Commands)
8. Start your bot

bot.start(
    port, // If passed, the application will create a HTTP server
    true // If true or undefined, the app will register all slash commands in the Discord API
);

Commands

Creating and registering a command

To create a command, initialize a Command object

Example:

const cmdGreet = new Command({
    name: "greet",
    parameters: [
        {
            name: "name",
            description: "Name that will be greeted",
            optional: true,
            type: "string",
        },
    ],
    aliases: ["hello"],
    description: "Welcomes someone",
    usage: "[name]",
    permissionCheck: "ALL",
    permissions: ["SEND_MESSAGES"],
    guilds: undefined,
    visible: true,
    slash: true,
    announceSuccess: true,
    function: function(p. m) {
        if(p('name')) {
            return `Hello, ${p('name')}!`
        }
        else {
            return 'Hello!'
        }
    }
});

// Register
bot.commands.add(cmdGreet)

Properties (* - required):

• name* - string - command name
• parameters - ParameterSchema[] - array of parameters (see Parameters)
• aliases - string | string[] - array of alternative strings that can call this command (not available for slash commands)
• description - string - command description
• usage - string - command usage visible in the help message (if not defined, usage string will be automatically generated based on defined parameters)
• permissionCheck - "ALL" | "ANY" - whether to check if caller has all defined permission or at least one of them
• permissions - PermissionResolvable | (m?: Message | CommandInteraction) => boolean - permissions required to run this command
• guilds - string[] - array of servers IDs in which this command will be available (if slash command)
• visible - boolean - whether this command is visible in the help message
• slash - boolean - whether this command should be registered as a slash command
• announceSuccess - boolean - whether a command reply should be sent automatically if no other response is defined or the reply should be deleted
• function* - (p: function, m?: Message | CommandInteraction) => void | MessageEmbed | string | ReplyMessageOptions - function that will be executed on call

Register your command in bot client using:

bot.commands.add(cmd);

where (* - required):

• cmd - Command

Command function

Arguments

• p - function - call this function with parameter name to fetch parameter value
• m? - Message | CommandInteraction - interaction object

Return value

If function returns (also after resolving a Promise):

• void - If announceSuccess property is true, bot will automatically send a SUCCESS message (see Messages). If command has been called using slash commands and announceSuccess property is set to false, reply will be automatically deleted
• string - this string will be sent in a reply
• MessageEmbed - embedded content will be sent in a reply
• ReplyMessageOptions - these options will get used to send a reply

It is possible to manually send replies directly from the command function using the m argument. If you are using slash commands don't forget to use the editReply method instead of the reply method since a reply is already deferred when a command function is being called (read more here) If you try to create a new reply, you app will throw an error that will result a crash. If you manually reply to a slash command interaction and return void from the command function, a SUCCESS message will not be sent or reply will not get deleted (if you want to disable SUCCESS messages on prefix interactions set announceSuccess property to false).

Errors

If a command function will throw an error, it will automatically get caught and your bot will send an ERROR message (see Messages). The app will not crash.

Parameters

Types

• string - text value
• boolean - True or False
• number - number (double) value
• user - ObjectID object with ID value (shown as selection menu in Discord)
• role - ObjectID object with ID value (shown as selection menu in Discord)
• channel - ObjectID object with ID value (shown as selection menu in Discord)
• mentionable - ObjectID object with ID value (shown as selection menu in Discord)

To get an entity ID from ObjectID use the value property. You can also call toObject method to retrieve full entity object from Discord API

ObjectID.toObject(g, "TYPE");

where (* - required):

• g* - Guild - Guild object to fetch from
• "TYPE"* - "user' | "role" | "channel" - defines the entity type

Defining

Example:

{
    name: "user",
    description: "User to mention",
    optional: false,
    type: "user"
}

Properties (* - required):

• name* - string - parameter name
• description - string - parameter description
• optional* - boolean - whether this parameter is optional
• type* - "string" | "boolean" | "number" | "user" | "role" | "channel" | "mentionable" - parameter type
• choices - string[] - parameter value choices (to use this, set type to "string")

Reading input value

To read parameter values use a function that is passed in the first argument of a call function (defined in function parameter in Command object)

p(query, returnType);

where (* - required):

• query* - string - parameter name
• returnType - "value" | "object" - whether to return only parameter value or a full object

function: (p, m) => {
    const userObj = p('user')
    if(userObj) {
        const user = user.toObject(m.guild, "user");
        if(user) {
            return `Hello, ${user.toString()}`
        }
        else {
            throw new Error('User not found')
        }
    }
}

Coming soon...