Skip to content

Latest commit

 

History

History
348 lines (266 loc) · 14.2 KB

api.md

File metadata and controls

348 lines (266 loc) · 14.2 KB
Raw

TwistyBot API v1.5.3

Table of Contents

TwistyBot

const TwistyBot = require('twistybot');
let bot = new TwistyBot.Client();

(async function() {
	// Register default commands
	await bot.add_default_commands();

	// Register a folder of commands
	await bot.add_command_directory(__dirname + '/commands');

	// Begin listening for commands
	bot.login('your bot token');
})();

class: Client

Client.add_command(options)

  • options <Object>

    • help <?Object>
      • description <String> A short, one line description of the command.
      • parameters <String> Parameter usage information.
      • details <?String> A longer description of the command.
      • examples <?Array<String|Object>> An array of example commands and explanations.
        • params <String> The example's parameters.
        • result <String> The example's result.
    • params <?Object>
      • min <?Number> The minimum number of parameters.
      • max <?Number> The maximum number of parameters.
      • parser <?String|?Function> A parser used to convert the raw parameter string to parsed parameters.
      • check <?Function> A function used to check if the parameters are valid.
    • permissions <Array<Object>>
    • aliases <?Array<String>> A list of aliases for this command.
    • name <String> The name of this command.
    • category <String> The category of this command.
    • init <Function> A function called to initialize any data the command uses.
    • run <Function> The main command function that prepares the command response.

  • returns: <Promise> Resolves when TwistyBot finishes initializing the command.

Client.add_command_directory(folder)

  • folder <String> Path to a folder of commands

  • returns: <Promise> Resolves when TwistyBot finishes initializing all commands in the folder.

This function provides a convenient way to load an organized folder of commands, with the following structure:

folder
 ├category1
 │ ├command1.js
 │ ├command2.js
 │ └command3.js
 └category2
   └command4.js

Subfolders are treated as command categories, with the name of the subfolder used as the category name. Files within the subfolder should export command options that can be passed to Client.add_command(). The filename will automatically be used as the command name, excluding the file extension. An example command folder can be found at /src/commands, which contains TwistyBot's default commands.

Client.add_default_commands()

  • returns: <Promise> Resolves when TwistyBot finishes initializing the commands.

Adds the default commands. The default commands include help, permission, and setprefix.

Client.get_command(command_name)

Finds a command by its name or alias. If no such command exists, this function returns undefined.

Client.log_error(err, message)

  • err <Error> The error that was raised.
  • message <Discord.Message> The command message that was being processed.

This function delivers a stack trace of the error to the bot's Discord error channel. You can specify this channel by passing a channel ID to the bot constructor:

let bot = new TwistyBot.Client({
	error_channel: '212345627062207890'
});

class: Command

Command.stats()

  • returns: <Object>
    • uses <Number> The number of times the command was used.
    • errors <Number> The number of times the command failed to complete (threw an error)
    • average_time_ms <Number> Average running time of the command in milliseconds

Command.reset_stats()

Clears the usage/error statistics for this command.

Command.helptext(prefix)

  • prefix <String> The command prefix to use in examples and usage.

  • returns: <String> The formatted help text

class: Config

Config.get(key)

Config.set(key, value)

  • key <String>

  • value

  • returns: <Promise> Resolves when the key is set to value

Config.clear()

  • returns: <Promise> Resolves when all keys are cleared

class: Table

  • theme <?String> Specifies the theme of the table. There are two built-in themes: 'default' and 'borderless'.

Table.align(a)

  • a <String> Specifies the alignments of each column. Valid characters are 'l' for left, 'r' for right, and 'c' fo center aligned. For example, 'llr' indicates the first two columns are left aligned, and the third column is right aligned.

  • returns: <undefined>

Table.min_width(...w)

  • w <Number> The minimum width in characters of each column.

  • returns: <undefined>

Table.push(...row)

  • row A row of table values.

  • returns: <undefined>

This function adds a new row of values to the bottom of the table.

Table.header(...row)

  • row A row of table values.

  • returns: <undefined>

This function adds a new row of center aligned values to the bottom of the table. A separator is added automatically after the row is inserted.

Table.full(value)

This function adds a full width, centered row to the bottom of the table.

Table.div()

This function adds a separator between the bottom row and the next row pushed.

Table.pop()

This function removes the most recently pushed row.

Table.empty()

This function removes all rows from the table.

Table.toString()

Stringifies the table. Does not add Discord code block tags.

Table.length

  • returns: <Number> The number of rows in the table.

Table.width

  • returns: <Number> The number of columns in the table.

Discord.js extensions

TwistyBot adds some extra functionality to the base Discord.js features. That is to say, you can access all the functions and variables of the original Discord.js classes, plus these additional functions defined by TwistyBot.

extension: Channel

Channel.friendly_name

  • returns: <String> A friendly name for the channel. For example, a DM channel with user#1234 would be returned as DM.user#1234.

extension: Guild

Guild.config

  • returns: <Config> Settings for this guild.

extension: GuildMember

GuildMember.config

  • returns: <Config> Settings for this user.

extension: Message

Message.string_content

  • returns: <String> A string representation of the message content. Embeds and file attachments are also stringified after the main message text content.

extension: User

User.config

  • returns: <Config> Settings for this user.

extension: Markdown Functions

The following are convenience functions for using Discord Markdown. They are made available as properties of the Discord.js module.

const TwistyBot = require('twistybot');
const Discord = require('discord.js');
console.log( Discord.bold('Hello world!') );

Discord.italics(text)

  • text <String> Text to format
  • returns: <String> Text formatted with italics markdown: *text*

Discord.bold(text)

  • text <String> Text to format
  • returns: <String> Text formatted with bold markdown: **text**

Discord.bold_italics(text)

  • text <String> Text to format
  • returns: <String> Text formatted with bold and italics markdown: ***text***

Discord.strikeout(text)

  • text <String> Text to format
  • returns: <String> Text formatted with strikeout markdown: ~~text~~

Discord.underline(text)

  • text <String> Text to format
  • returns: <String> Text formatted with underline markdown: __text__

Discord.underline_italics(text)

  • text <String> Text to format
  • returns: <String> Text formatted with underline and italics markdown: __*text*__

Discord.underline_bold(text)

  • text <String> Text to format
  • returns: <String> Text formatted with underline and bold markdown: __**text**__

Discord.underline_bold_italics(text)

  • text <String> Text to format
  • returns: <String> Text formatted with underline, bold, and italics markdown: __***text***__

Discord.code_block(text)

  • text <String> Text to format
  • returns: <String> Text formatted as a code block.

Discord.inline_code(text)

  • text <String> Text to format
  • returns: <String> Text formatted as an inline code block.

Discord.link(link)

This function formats a link so that it does not automatically embed a preview of the url after the message.

Discord.masked_link(text, link)

Masked links display the given text instead of the url, allowing for nicer output. Masked links can only be used inside embeds, not regular text messages. Note that masked links are referred to as "spoopy links" within Discord.

Discord.json(value)

  • value Value to be formatted
  • returns: <String>

A shortcut for making a JSON language code block using the stringified value.