124 lines
4.6 KiB
Markdown
124 lines
4.6 KiB
Markdown
# MC Bot Town
|
|
|
|
A Minecraft bot framework for the [CoreJourney](https://corejourney.org) server, built on [mineflayer](https://github.com/PrismarineJS/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
|
|
|
|
```bash
|
|
git clone https://github.com/wmantly/mc-cj-bot.git
|
|
cd mc-cj-bot/nodejs
|
|
npm install
|
|
```
|
|
|
|
### Configuration
|
|
|
|
1. Copy and edit the secrets file:
|
|
|
|
```bash
|
|
cp conf/secrets.example.js conf/secrets.js
|
|
```
|
|
|
|
2. Add your Microsoft account credentials in `conf/secrets.js`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
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 |
|