❤
npm
Sign UpSign In

mineflayer-chat-commands

1.0.3 • Public • Published

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 has onlyConsole set to true and 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"); // -> command

getAllNames(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);
});

Readme

Keywords

Package Sidebar

Install

npm i mineflayer-chat-commands

Repository

github.com/WhoTho/mineflayer-chat-commands

Homepage

github.com/WhoTho/mineflayer-chat-commands#readme

Weekly Downloads

7

Version

1.0.3

License

ISC

Unpacked Size

42.9 kB

Total Files

8

Last publish

Collaborators

  • whotho
Try on RunKit
Report malware