# 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 |