Chat Commands
- Chat Commands
Installation
npm i mineflayer-chat-commands
General info
NOTE:
A similar plugin also exists: mineflayer-cmd
"chatCommands:ready"
Event fired once when you can start adding commands
bot.once("chatCommands:ready", addAllCommands);Errors
-
UnknownCommandError: Unknown command -
AccessDeniedError: Command hasonlyConsoleset totrueand someone tried to run the command from outside the console -
NotEnoughArgsError: Not enough arguments were provided for a function -
TooManyArgsError: Too many arguments were provided for a function -
InvalidArgError: An argument was invalid -
RuntimeError: An error occurred while running the command code -
StructureError: An invalid command structure was provided
Info with each error:
this.caller = {
username: "", // Username of the caller of the command
message: "", // Unparsed message that was chatted
isConsole: false, // Wether the caller was the console or not
};
this.parsedArgs = []; // Parsed arguments
this.command = Object; // The object of the command that was called
this.error = Error; // Thrown errors (Set during RuntimeError and InvalidArgError)Default commands
- help [command]
- Aliases: h
- Description: Displays the help message
- quit
- Aliases: exit
- Description: Makes the bot quit
- whitelist <add|remove> [...usernames]
- Description: Add/remove players to/from the chatCommand whitelist
- blacklist <add|remove> [...usernames]
- Description: Add/remove players to/from the chatCommand blacklist
- code [...code]
- Console only: true
- Description: Runs code from the console
Configs
allowConsole
Default: False
Wether to take console input as commands (does not require command prefix)
Set the value before loading the plugin
const chatCommands = require("mineflayer-chat-commands");
...
chatCommands.allowConsole = true;
bot.loadPlugin(chatCommands)configs.prefix
Default: "#"
The prefix for all commands
configs.chatPrefix
Default: ""
Any bot.chat that the chatCommand plugin calls will be prefixed with configs.chatPrefix, letting you keep errors and default chats to yourself
configs.chatPrefix = "/whisper MY_USERNAME";configs.whitelist
Default: []
List of usernames that are allowed to run commands
bot.chatCommands.configs.whitelist.push("MY_USERNAME");configs.blacklist
Default: []
List of usernames that are not allowed to run commands
bot.chatCommands.configs.blacklist.push("OTHER_USERNAME");configs.useDefaultErrorHandlers
Default: true
If false, the errors from runCommand will be thrown to the main program
bot.chatCommands.configs.useDefaultErrorHandlers = false;
try {
bot.chatCommands.runCommand("MY_USERNAME", "#notACommand");
} catch (err) {
console.log(err); // -> UnknownCommandError: Chat command error
}configs.allowBotChat
Default: true
Wether or not the chatCommand plugin will use bot.chat or console.log for displaying info
bot.chatCommands.configs.allowBotChat = false;
bot.chatCommands.runCommand("MY_USERNAME", "#help"); // -> Bot chat: help message...Functions & variables
allCommands
List of all commands
Avoid calling allCommands.push, as that will skip checks and the adding of internal info
const allCommandDescriptions = bot.chatCommands.allCommands.map((command) => command.description);addCommand(command)
command: command
Takes in a command and adds it to allCommands
bot.chatCommands.addCommand({
command: "hi",
code: () => {
bot.chat("Hello!");
},
});addCommands(commands)
Commands: List of commands
Adds the commands to allCommands
bot.chatCommands.addCommands([
{
command: "smallTalk",
code: () => {
bot.chat("Isn't the moon lovely?");
},
},
{
command: "bye",
code: () => {
bot.chat("Goodbye!");
},
},
]);runCommand(username, message)
username: String
message: String
Tries to run the message as a command.
Throws errors if configs.useDefaultErrorHandlers is false
bot.on("chat", (username, message) => {
if (username === bot.username) return;
bot.chatCommands.runCommand(username, message);
});getCommand(name)
name: String
Returns: command
Finds and returns the command by the command name
const helpCommand = bot.chatCommands.getCommand("help"); // -> commandgetAllNames(command)
command: command
Returns: List of strings
Returns all the names of a command (Actual name + aliases)
const helpCommandNames = bot.chatCommands.getAllNames(helpCommand); // -> ['h', 'help']commandNameToString(command)
command: command
Returns: String
Returns the command name as a formatted string (Runs argNameToString)
const helpCommandName = bot.chatCommands.commandNameToString(helpCommand); // -> "help [command]"argNameToString(arg)
arg: argument
Returns: String
Returns the argument name as a formatted string
<requiredArg> [optionalArg] [...restArg]
const helpArgName = chatCommands.argNameToString(helpCommand.args[0]); // -> "[username]"Create a command
command
Type: String
Name of the command
{
command: "fight",
}aliases
Type: List of strings
Default: []
Aliases for the command
{
aliases: ["f", "kill"],
}consoleOnly
Type: Boolean
Default: True
Wether the command can be run by only the console
Plugin will throw an AccessDeniedError if a command that is console only is called from outside the console
{
consoleOnly: true,
}description
Type: String
Default: "No description"
Description of the command
{
description: "Makes the bot fight a specified player or the closest one",
}args
Type: List of arguments
Default: []
See writing an arg
{
args: [
{
arg: "username",
optional: true,
},
],
}code(caller, args...)
caller: Object ({ username: "CALLER_USERNAME", message: "#help", isConsole: true })
Type: Function
The code that is run on command call
{
code: (_, arg1, arg2) => {
if (arg1 === "test") console.log(arg2);
},
}onFail(err)
err: NotEnoughArgsError, TooManyArgsError, or RuntimeError
Type: Function
Default: (err) => { throw err }
By default, this function would just throw the error to either the default handlers or to the main program
Allows you to write custom error messages for specific commands
{
onFail: (err) => {
console.log("Command " + err.command.command + " has failed");
},
}Create an argument
arg
Type: String
Name of the argument
{
arg: "username",
}description
Type: String
Default: "No description"
Description of the argument
{
description: "Username of the player",
}optional
Type: Boolean
Default: false
Wether or not the argument is optional
{
optional: true,
}isRest
Type: Boolean
Default: false
Wether or not the argument is a rest argument (Takes the rest of the arguments as a list)
{
isRest: true,
}testValid(arg)
arg: String, number, or boolean
Type: Function
Default () => true
Function to run on the user inputted argument to check if it is valid
If the function returns false or errors, the argument throws an InvalidArgError
{
testValid: (username) => Object.keys(bot.players).includes(username),
}onFail(err)
err: InvalidArgumentError
Type: Function
Default: (err) => { throw err }
By default, this function would just throw the error to either the default handlers or to the main program
Allows you to write custom error messages for each argument that is invalid
{
onFail: (err) => {
console.log("Unknown player:", err.arg);
console.log("Possible players:", Object.keys(bot.players).join(", "));
},
}Examples
const mineflayer = require("mineflayer");
const chatCommands = require("mineflayer-chat-commands");
const bot = mineflayer.createBot({
username: "chatCommands",
host: "localhost",
});
chatCommands.allowConsole = true;
bot.loadPlugin(chatCommands);
bot.once("chatCommands:ready", () => {
bot.chatCommands.addCommand({
command: "help",
aliases: ["h"],
description: "Runs the help command",
code: () => {
console.log("Check console for more information");
},
});
bot.chatCommands.addCommands([
{
command: "chatConfigs",
description: "Shows the chat configs",
code: () => {
for (const key in chatCommands.configs) {
bot.chat(`${key}: ${chatCommands.configs[key]}`);
}
},
},
{
command: "fight",
aliases: ["f", "kill"],
description: "Starts the pvp bot against a user or the nearest entity",
args: [
{
arg: "username",
optional: true,
testValid: (username) => Object.keys(bot.players).includes(username),
onFail: (err) => {
console.log("Unknown player:", err.arg);
console.log("Possible players:", Object.keys(bot.players).join(", "));
},
},
],
code: (_, username = null) => {
if (username) bot.pvp.attack(bot.players[username].entity);
else bot.pvp.attack(bot.nearestEntity());
},
},
{
command: "quit",
code: bot.quit,
},
]);
});
bot.on("chat", (username, message) => {
if (username === bot.username) return;
bot.chatCommands.runCommand(username, message);
});
