CommandBot

A Discord.js based framework that makes creating Discord bots with support for slash commands easy and fast.

Features

• Support for slash commands, context menu interactions
• Intuitive usage
• Flexible
• Good customization
• Permission system
• Built-in help command
• Built-in information messages
• Automatic error catching
• Large documentation in README and using JSDoc
• Written in TypeScript

Documentation

Reference for available objects and structures is available here. All descriptions can also be accessed from your code editor/IDE. TypeScript declaration files are also included (.d.ts) for some programs (like Visual Studio Code) to give autocompletion suggestions.

Table of contents

• CommandBot
  • Features
  • Documentation
  • Table of contents
• Instalation
  • System requirements
  • Creating a project
    • Registering Discord app
    • Creating application
• Commands
  • Creating a command
  • Parameters
    • Types
    • Defining
    • Reading input value
  • Subcommands
• Events
• Messages
  • System messages
  • Help message
• Experimental features
• Issues

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, paste it in your web browser and add the bot to a server

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/index.ts file (TypeScript is a recommended language)
5. Import the CommandBot package

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

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

6. Initialize the bot instance (InitOptions) (list of available intents here)

const bot = new Bot({
    name: "YOUR_BOT_NAME",
    globalPrefix: "!",
    argumentSeparator: ",",
    commandSeparator: "/",
    clientOptions: {
        intents: [..."DISCORD_API_INTENTS"],
    },
    token: "DISCORD_BOT_TOKEN",
    applicationId: "APPLICATION_ID",
    help: {
        enabled: true,
        title: "List of commands",
        usage: "[command name]",
        description: "Show all commands available to use in my fantastic Discord bot.",
        bottomText: "Hello World",
        color: "#0055ff",
        visible: false,
    },
});

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 [type: number (integer)]
    true // If true or undefined, the app will register all slash commands in the Discord API [type: boolean]
);

WARNING! All commands have to be added to the instance before starting the bot. Adding commands while the bot is running is not possible and can cause issues.

Commands

Creating a command

To create a command, use CommandManager.prototype.add method

Command types

• CHAT - message interactions using command prefixes or slash commands
• USER - right-click context menu interactions on users
• MESSAGE - right-click context menu interactions on messages

Chat command example:

bot.commands.add("CHAT", {
    name: "greet",
    parameters: [
        {
            name: "user",
            description: "User to greet",
            optional: false,
            type: "user",
        },
    ],
    aliases: ["hello"],
    description: "Welcome someone to your server",
    usage: "[user]",
    dm: false,
    guilds: ["123456789874561230"],
    slash: true,
    visible: true,
    permissions: {
        resolvable: ["ADMINISTRATOR"],
        checkType: "ANY",
    },
    ephemeral: "NONE",
    function: async (i) => {
        const user = await i.get("user").toObject();
        return `Hello ${user.toString()}`;
    },
});

Command function schema is defined here

Parameters

Types

• primitive
• objects

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

Defining

Pass a list of ParameterSchema objects to parameters property

Example parameter object:

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

Reading input value

To read parameter values use InputManager.prototype.get() (passed in the first argument of a command function)

Example:

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

Subcommands

To create a subcommand create a standard chat command and use ChatCommand.prototype.append method to create and attach subcommands or subcommand groups. To add subcommands to groups use SubCommandGroup.prototype.append.

// Create a chat command
const cmd = bot.commands.add("CHAT", {
    name: "parent",
    slash: true,
    description: "This is a parent",
});

// Create and append a subcommand
cmd.append("COMMAND", {
    name: "child",
    description: "This is a subcommand",
    aliases: ["ch"],
});

// Create and append a subcommand group
const group = cmd.append("GROUP", {
    name: "command_group",
    description: "This is a subcommand group",
});

// Add a subcommand to the group
group.append({
    name: "group_command",
    description: "This is a subcommand that is a child of the command_group",
    aliases: ["subch"],
});

To invoke subcommands using Discord messages use an argumentSeparator (default: "/").

!parent - "parent" command
!parent/child - "child" command
!parent/command_group - this will invoke the "parent" command
!parent/command_group/group_command - "group_command" command which is a parent of "command_group" group

Events

CommandBot is using EventEmitter that is built into Node.js. You can listen to events using the on method. Event types are available here.

Messages

System messages

System messages can be composed and sent automatically when a certain action happens. All message types are available here. Their configuration is stored in Bot.prototype.messages property. Each of these messages can be customized with SystemMessageAppearance objects. There is also a global deleteTimeout property so messages can automatically be deleted after a given time.

Help message

To configure it use the help property in the bot's constructor and pass there a HelpMessageParams object.

WARNING! You can't customize these messages after starting the bot. Changing these properties while the bot is running will have no effect.

Experimental features

• The package has a PrefixManager class which is taking care of setting different prefixes for every server that the bot is on but there is no module to store that date in a file or database so the it's lost every time the application restarts. If you want to use it in your project, you should create a data store and write a function that dumps the data there.
• CommandManager has 2 methods to interact with the Discord Permissions API (getPermissionsApi and setPermissionsApi) and set interaction permissions that are independent from the CommandBot permission system. This functionality has not been polished and fully tested yet.

Issues

Since this package is created by only 1 person it may contain some bugs or behave weirdly. If you notice any problem, typo etc, please create an issue in the Issues tab on GitHub.

Thank you.

Created with ❤️ by GRZANA