here

2026-02-22 20:27:09 -05:00
parent 7b326a112e
commit 92024c8a64
37 changed files with 6785 additions and 3344 deletions
@@ -0,0 +1,123 @@
+# 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 |