Command

Create a command

To create a command it is recommended to use the CLI to correctly generate the body of the command.

CLI pattern

bot add command

Define message origin

Once your command is created, If you want handle messages from GuildChannels only or from DMChannel only, follow these steps.

GuildChannel only

import { Command } from "#core/command"

export default new Command({
  channelType: "guild",

  // ...some properties
})

DMChannel only

import { Command } from "#core/command"

export default new Command({
  channelType: "dm",

  // ...some properties
})

Setup a cooldown

If you want to setup a cooldown, you simply need to add the coolDown property when you create the command, define the duration you want in milliseconds, and trigger the cooldown where you want in the command body. Example:

import { Command, CooldownType } from "#core/command";

const canAccessHourly: () => boolean = //...
const processHourly: () => Promise = //...

export default new Command({
  name: "hourly",
  cooldown: {
    duration: 1000 * 60 * 60, // 1 hour of cooldown
    type: CooldownType.Global,
  },
  async run(message) {
    if(canAccessHourly()) {
      // trigger the cooldown only if hourly is triggered
      message.triggerCoolDown()

      await processHourly()
    }
  }
})

If you forget the message.triggerCoolDown() in the command, a warn appear in server logs on loading of the command.

Arguments

ALl command can have a lots of arguments. This framework considers that Discord bot commands should resemble Unix commands in their syntax. You will therefore find some similarities between CLIs and the commands of your Discord bot.

The character is not a valid argument separator. If you want to break the line before putting an argument, add a space at the start of argument. (issue#19)

The name and description argument properties are obligatory.

Categories of arguments

There are three specific types of arguments based on the Yargs parser, here is a short overview.

Positional

The most common type of argument on Discord bots. It is used to define values according to their positioning in the command typed.

import { Command } from "#core/command"

export default new Command({
  name: "cmd",
  description: "A command",
  channelType: "all",
  positional: [
    {
      name: "name",
      description: "A name positional",
      type: "string",
    },
  ],
  async run(message) {
    app.log(message.args.name) // string | null
  },
})

The last code example will be used like that on Discord:

• !cmd "multiline value"

• !cmd value

Option

This kind of argument is used for options, most often optional.

import { Command } from "#core/command"

export default new Command({
  name: "cmd",
  description: "A command",
  channelType: "all",
  options: [
    {
      name: "name",
      description: "A name option",
      type: "string",
    },
  ],
  async run(message) {
    app.log(message.args.name) // string | null
  },
})

The last code example will be used like that on Discord:

• !cmd --name "multiline value"

• !cmd --name value

Flag

The flag is an argument of type "present or not" which returns a boolean. You can also assign it values such as on/off or 1/0 or true/false or Y/N, it will always return a boolean.

import { Command } from "#core/command"

export default new Command({
  name: "cmd",
  description: "A command",
  channelType: "all",
  flags: [
    {
      name: "named",
      flag: "n",
      description: "Is named flag",
    },
  ],
  async run(message) {
    console.log(message.args.named) // true | false
  },
})

The last code example will be used like that on Discord:

Command	Returning value
!cmd --named off	false
!cmd --named	true
!cmd -n	true
!cmd	false

Rest

Represents all command text that was not passed as an argument.

import { Command } from "#core/command"

export default new Command({
  name: "cmd",
  description: "A command",
  channelType: "all",
  rest: {
    name: "name",
    description: "The rest of arguments",
    required: true,
  },
  async run(message) {
    console.log(message.args.name) // string
  },
})

The last code example will be used like that on Discord:

• !cmd multiline value

• !cmd value

Required arguments

If argument is required, it will never have the null value and will return an error message before the execution of the command if it is missing. The command will then not be executed.

Casting types

Yout can use the type property to force a certain type of input and convert the textual input into an object of the type you want.

For example if I want the user to mention a member as positional, and retrieve the GuildMember mentioned in the body of my command, I can use the type property like this:

import { Command } from "#core/command"

export default new Command({
  name: "cmd",
  description: "A command",
  channelType: "all",
  positional: [
    {
      name: "target",
      description: "The mentionned member",
      type: "member",
      required: true,
    },
  ],
  async run(message) {
    console.log(message.args.target) // GuildMember
  },
})

All types are available in src/types.ts, and you can add custom types there. Please refer to the types file for an exhaustive list of existing types.

Middlewares

The documentation is currently being produced.

Slash commands

The documentation is currently being produced.

About commands

https://github.com/bot-ts/docs/blob/master/usage/broken-reference/README.md

https://github.com/bot-ts/docs/blob/master/usage/broken-reference/README.md