CommandBot/README.md

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
  • 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,
    annouceSuccess: 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
  • Arguments
  • • p - function - call this function with parameter name to fetch parameter value
    • m? - Message | CommandInteraction - interaction object

Register your command in bot client using:

bot.commands.add(cmd);

where (* - required):

• cmd - Command

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')
        }
    }
}