MC Bot Town

A Minecraft bot framework for the CoreJourney server, built on mineflayer. Manages multiple bots with a plugin system, automated storage management via shulker boxes, AI chat personalities, and a web UI for inventory browsing.

Setup

git clone https://github.com/wmantly/mc-cj-bot.git
cd mc-cj-bot/nodejs
npm install

Configuration

Copy and edit the secrets file:

cp conf/secrets.example.js conf/secrets.js

Add your Microsoft account credentials in conf/secrets.js:

module.exports = {
  mc: {
    bots: {
      bot_name: {
        username: "email@example.com",
        password: "password",
        auth: "microsoft",
      }
    }
  }
};

The base config (conf/base.js) is merged with secrets and an optional conf/development.js override.

Running

cd nodejs
npm start

The bot(s) will connect to the configured server and load their plugins.

Project Structure

nodejs/
  index.js                      # Entry point
  conf/
    base.js                     # Base configuration (server, storage, AI)
    secrets.js                  # Credentials (gitignored)
  model/
    minecraft.js                # CJbot class — core bot wrapper, pathfinding, chat, commands
  controller/
    mc-bot.js                   # Registers plugins, creates bot instances, connects
    commands/                   # Chat command modules
      default.js                # Admin commands (help, summon, dismiss, load/unload plugins)
      storage.js                # Storage commands (scan, withdraw, deposit, organize)
      trade.js                  # Trade window handling
      invite.js                 # Teleport invite handling
      fun.js                    # Fun/misc commands
    storage/                    # Storage plugin
      index.js                  # Storage class — deposit, withdraw, organize, hotbar restock
      database.js               # SQLite database (chests, shulkers, items, trades, permissions)
      scanner.js                # Discovers chests, reads shulker NBT
      shulker-handler.js        # Physical shulker operations (take, place, open, break, return)
      web.js                    # Express web UI for browsing inventory
    ai.js                       # AI chat plugin loader
    ai/                         # AI providers (Gemini, Ollama)
    craft.js                    # Crafting plugin
    swing.js                    # Auto-swing plugin
    tp.js                       # Teleport plugin
    guardianFarm.js             # Guardian farm automation
    goldFarm.js                 # Gold farm automation
    auto-eat.js                 # Auto-eat plugin
  utils/
    index.js                    # sleep, nextTick helpers

Plugin System

Plugins are classes registered with CJbot.pluginAdd(PluginClass) in mc-bot.js. Each bot specifies which plugins to load in its config via pluginsWanted. Plugins receive the bot instance and must implement:

constructor({ bot, ...opts }) — receive bot reference and config
init() — called when the bot is ready (async)
unload() — cleanup when disconnecting or unloading

Plugins are loaded/unloaded at runtime via chat commands (.load botName PluginName, .unload botName PluginName).

Storage System

The storage plugin manages a shulker-box-based item storage system:

Chests are discovered by scanning nearby blocks and tracked in SQLite
Shulker boxes inside chests are the storage units — one item type per shulker
Deposits: items received via trade are sorted into matching or empty shulkers
Withdrawals: items are pulled from shulkers and held for player pickup via /trade
Organize: loose items sitting directly in chests are moved into shulkers
Hotbar restock: periodically refills configured items from storage
Web UI: browse inventory at http://localhost:3000

The database is the source of truth — the bot is the only actor that interacts with chests.

Configuration Reference

Key settings in conf/base.js:

Setting	Description
`mc.host`	Minecraft server address
`mc.bots`	Bot accounts and their plugin configs
`storage.dbPath`	SQLite database path
`storage.scanRadius`	Block radius for chest discovery
`storage.hotbarItems`	Items to auto-restock (name, min, target)
`storage.webPort`	Web UI port (default 3000)
`storage.craftingTablePos`	Fixed crafting table position or null to search
`ai.provider`	AI provider: `"gemini"` or `"ollama"`
`ai.baseUrl`	Ollama server URL
`ai.model`	Model name for AI chat

4.6 KiB Raw Permalink Blame History