Minecraft Bot

An open-source Minecraft server bot written in JavaScript. Uses rcon to connect to the server and execute commands. Plugins are written in JavaScript and can be easily added to the bot. Plugins communicate through an event system, allowing for easy integration and modularity.

Currently available plugins:

• afk-commands: When a player is considered AFK, run a set of commands.
• bot-control: Ties the plugins together and configures the timeout for commands.
• death-commands: When a player dies, run a set of commands.
• initialize-commands: When the bot has connected to a server, run a set of commands.
• player-afk: Tracks the player positions and considers them AFK if they haven't moved for a configurable amount of time.
• player-death: Tracks player death location and emits an event when it changes.
• player-greeting: When a player joins the server, greet them with a message in chat.
• player-list: Lists the currently connected players and emits events when players join or leave the server.
• player-position: Tracks player positions and emits events when they change.
• rcon: Connects to the Minecraft server using rcon and executes commands.
• stats: Logs statistics about the bot at a configurable interval.

Full descriptions of each plugin are available in the docs.

Getting Started

First, install the library using npm (or your favorite Node.js package manager):

npm install -g minecraft-rcon-bot

Then, create a configuration file for the bot, as detailed below. We will assume it is called config.yaml.

Lastly, run the bot.

minecraft-rcon-bot config.yaml

Configuration File

This file will specify the plugins to use and their configurations. For example, here is one that leverages ALL of the built-in plugins. Plugin order does not matter. When there is a default value, it's commented out to show what the default is, but you can change it as needed.

Durations are parsed using 'parse-duration-ms', so you can use human-friendly duration strings like '1h', '2.5m', '1 hour 15 seconds', etc.

- import: "../plugins/bot-control.js"
  config:
      # Default timeout for commands. Timer starts when the command enters
      # the queue, not when it is sent to the server.
      # commandTimeoutDuration: 10s

- import: "../plugins/rcon.js"
  config:
      host: minecraft.example.com
      # port: 25575
      password: Super_Secret_Password
      # timeoutDuration: 5s
      # reconnectDelayDuration: 15s
      # retryConnectionAttempts: 5

- import: "../plugins/afk-commands.js"
  config:
      # Commands to initialize the server when it starts
      initCommands:
        - "team add AFK \"AFK Players\""
        - "team modify AFK color dark_gray"
      # Commands to reset a player when they join
      # Use {PLAYER} to include the player's name in the command.
      resetCommands:
        - "team leave {PLAYER}"
      # What commands to run when the player is AFK
      # Use {PLAYER} to include the player's name in the command.
      afkCommands:
        - "team join AFK {PLAYER}"
      # Use {PLAYER} to include the player's name in the command.
      backCommands:
        - "team leave {PLAYER}"

- import: "../plugins/death-commands.js"
  config:
      # Commands to issue when a player dies. Can use {DIMENSION}, {PLAYER},
      # {X}, {Y}, and {Z} in the commands.
      deathCommands:
        - "tellraw {PLAYER} {text:\"You last died at [{X}, {Y}, {Z}] in {DIMENSION}\", color: red}"

- import: "../plugins/initialize-commands.js"
  config:
      # Commands to issue when connected to a server.
      initializeCommands:
        - "gamerule playersSleepingPercentage 1"
        - "scoreboard objectives add Health health"
        - "scoreboard objectives setdisplay list Health"

- import: "../plugins/player-afk.js"
  config:
      # afkTimeoutDuration: 5m

- import: "../plugins/player-death.js"
  config:
      # How often to check for player deaths. It's often unnecessary to poll
      # rapidly.
      # updateIntervalDuration: 5s

- import: "../plugins/player-greeting.js"
  config:
    commands:
      # The messages to send when a player joins the server, or the delay to wait.
      # Use {PLAYER} to include the player's name in the message.
      - "recipe give {PLAYER} *"
      - 2000
      - "tellraw {PLAYER} {text:\"Welcome to the server!\",color:\"green\"}"
      - 1000
      - "tellraw {PLAYER} {text:\"Click here for more info and a map\",underlined:true,color:\"blue\",click_event:{action:\"open_url\",url:\"https://minecraft.rumkin.com\"}}"

- import: "../plugins/player-list.js"
  config:
      # The interval at which to update the player list.
      # updateIntervalDuration: 2s

- import: "../plugins/player-position.js"
  config:
      # The interval at which to update the player positions.
      # updateIntervalDuration: 2s

- import: "../plugins/stats.js"
  config:
      # The interval at which to update the stats.
      # updateIntervalDuration: 15m

Several plugins use lists of commands. Those accept strings, which are sent as commands, or numbers, which are treated as delays in milliseconds. For example, the following will issue the first command, wait 5 seconds, and then issue the second command:

- "tellraw {PLAYER} {text:\"You are now AFK!\"}"
- 5000
- "tellraw {PLAYER} {text:\"You are still AFK!\"}"

The above commands also use a replacement variable. In this case, {PLAYER} should be replaced with the player's name when the command is issued. The list of each plugin's supported replacement variables is documented in the plugin's documentation.