Monochrome

Monochrome

The main entry point into the framework. You construct this and call connect() on it to start your bot. See the monochrome demo for a full working example bot.

Constructor

new Monochrome(options)

Source:
Example
const Monochrome = require('monochrome-bot');
const path = require('path');

const bot = new Monochrome({
  botToken: require('./my-gitignored-config-file.json').myBotToken,
  botAdminIds: ['my_user_id'],
  prefixes: ['!', '@'],
  commandsDirectoryPath: path.join(__dirname, 'commands'),
  messageProcessorsDirectoryPath: path.join(__dirname, 'message_processors'),
  logDirectoryPath: path.join(__dirname, 'logs'),
  persistenceDirectoryPath: path.join(__dirname, 'persistence')
  settingsFilePath: path.join(__dirname, 'settings.js'),
  genericErrorMessage: 'Sorry, there was an error with that command. It has been logged and will be addressed.',
  missingPermissionsErrorMessage: 'I do not have permission to reply to that command in this channel.',
  discordInternalErrorMessage: 'Discord told me something\'s wrong with it. Please try again!',
  statusRotation: ['cooking dinner', 'eating dinner', 'cleaning kitchen'],
  statusRotationIntervalInSeconds: 600,
  topGg: require('./my-gitignored-config-file.json').myTopGgAPIkey,
  discordDotBotsDotGgAPIKey: require('./my-gitignored-config-file.json').myDiscordDotBotsDotGgAPIKey,
  erisOptions: { maxShards: 'auto' },
});

bot.connect();
Parameters:
Name Type Description
options Object Options to customize bot behavior.
Properties
Name Type Attributes Default Description
botToken string Your bot's token.
botAdminIds Array.<string> <optional>
 [] A list of IDs of users who are allowed to run bot admin commands.
prefixes Array.<string> <optional>
 [''] The bot's default command prefixes.
logger external:"bunyan.Logger" <optional>
 new Monochrome.ConsoleLogger() A bunyan logger, or something with the same interface. Monochrome will use addSerializers to add a 'user', 'guild', and 'channel' serializer to your logger.
storage StoragePlugin <optional>
 new Monochrome.Plugins.FPersist(path.join(process.cwd(), 'storage')) A storage plugin.
commandsDirectoryPath string <optional>
 The path of the directory (must exist) where your command modules exist. If this is omitted, no commands with be loaded.
messageProcessorsDirectoryPath string <optional>
 The path of the directory (must exist) where your message processor modules exist. If this is omitted, no message processors will be loaded.
logDirectoryPath string <optional>
 The path of the directory where logs should be stored (does not need to exist, but parent directories must exist). If this is omitted, logs will not be saved to disk.
settingsFilePath string <optional>
 The path of the Javascript file in which an array of your settings definitions exists. If this is omitted, no settings will be loaded.
genericErrorMessage string <optional>
 If your code throws an error that is caught by monochrome, this message will be sent to the channel where the command was used. The exception is message processors. Errors caught from message processors will not be broadcast to the channel. This avoids the possibility of your message processor throwing on any input and spamming errors to the channel.
missingPermissionsErrorMessage string <optional>
 If the bot fails to send a message due to missing permissions, the bot will attempt to send this message to the channel (that may fail too, if the bot has no permission to send even plain text messages in the channel). If this is omitted, no message is sent to the channel.
discordInternalErrorMessage string <optional>
 If the error handler catches a Discord internal error, the user will be shown this message (if Discord succeeds in sending it...). If this is omitted, no message is sent.
statusRotation Array.<string> <optional>
 [] An array of statuses that the bot should rotate through. The statusRotationIntervalInSeconds property is required to be set if this property is set.
statusRotationIntervalInSeconds number <optional>
 The bot will change their status on this interval (if the statusRotation has more than one status).
topGgAPIKey string <optional>
 If you have an API key from https://top.gg/ you can provide it here and your server count will be sent regularly.
discordDotBotsDotGgAPIKey string <optional>
 If you have an API key from https://discord.bots.gg/ you can provide it here and your server count will be sent regularly.
botsOnDiscordDotXyzAPIKey string <optional>
 If you have an API key from https://bots.ondiscord.xyz you can provide it here and your server count will be sent regularly.
discordBotListDotComAPIKey string <optional>
 If you have an API key from https://discordbotlist.com you can provide it here and your server count will be sent regularly.
erisOptions Object <optional>
 The options to pass directly to the Eris client. You can do things like set your shard count here. See the 'options' constructor parameter here: https://abal.moe/Eris/docs/Client

Methods

connect()

Description:
  • Connect to Discord and start listening for users to send commands to the bot.
Source:

getBlacklist() → {Blacklist}

Description:
  • Get the Blacklist, which you can use to blacklist users and manage blacklisted users.
Source:
Returns:
Type
Blacklist

getCommandManager() → {CommandManager}

Description:
  • Get the CommandManager.
Source:
Returns:
Type
CommandManager

getErisBot() → {external:"Eris.Client"}

Description:
  • Get the Eris client object. You can subscribe to events on the client, use it to lookup users, etc.
Source:
See:
Returns:
Type
external:"Eris.Client"

getLogger() → {external:"bunyan.Logger"}

Description:
  • Get the Logger, which you can use to log messages.
Source:
Returns:
Type
external:"bunyan.Logger"

getPersistence() → {Persistence}

Description:
  • Get the Persistence object, with which you can read and store persistent data.
Source:
Returns:
Type
Persistence

getSettings() → {Settings}

Description:
  • Get the Settings object, with which you can read and store persistent settings.
Source:
Returns:
Type
Settings

reload()

Description:
  • Reload your commands, message processors, and settings. You can use this to add, remove, and edit commands and other code, without having to restart your bot.
Source:

(async) stop()

Description:
  • Disconnect and stop the bot. Connect() cannot be called again and some operations may fail. You should call this as a final part of preparing to exit the process.
Source:

(async) updateUserFromREST(userId) → {external:"Eris.User"}

Description:
  • Fetches a user via the REST API and updates eris' cache with the received user data. This can be helpful for example if you don't have the presence update intent enabled, but you need to have a user's up-to-date username or avatar.
Source:
Parameters:
Name Type Description
userId String The ID of the user to fetch.
Returns:
- The user's data (or undefined if the user could not be found either via the REST API or eris' cache)
Type
external:"Eris.User"

userIsServerAdmin(msg) → {boolean}

Description:
  • Check if the sender of a message is a server admin (or bot admin).
Source:
Parameters:
Name Type Description
msg external:"Eris.Message" The Eris message. https://abal.moe/Eris/docs/Message
Returns:
Type
boolean

(async) waitForMessage(timeoutMs, messageCheck) → {external:"Eris.Message"}

Description:
  • Wait for a message to arrive.
Source:
Parameters:
Name Type Description
timeoutMs Number A timeout in milliseconds.
messageCheck function A function that takes a message and returns true if the waitee wants to accept the message. Accepting the message (returning true) ends the wait. Returning false continues waiting.
Returns:
The matching message. If none arrives and the timeout lapses, the promise will reject with a WAITER TIMEOUT error.
Type
external:"Eris.Message"