Amelia 2.0: The Pinnacle Autonomous Mineflayer Agent

Amelia is a highly advanced, multi-agent AI system for Minecraft built on top of the Mineflayer framework. Unlike traditional scripted bots, Amelia (and her sibling bots like Diana) are driven by Large Language Models (LLMs) that give them conversational awareness, autonomous goal-setting, and robust decision-making capabilities.

With Amelia 2.0, the architecture supports spawning multiple independent bot instances, all manageable via a stunning Glassmorphism WebUI dashboard.

(Preview image placeholder)

---

🌟 Key Features

• True Multi-Bot Architecture: Spawn and manage multiple AI bots (Amelia, Diana, etc.) simultaneously in the same Node.js process. Each bot has a fully isolated Brain, Perception, and state machine so they can perform completely different tasks in parallel without stepping on each other's toes.
• Intelligent Name-Based Chat Routing: Bots automatically know when they are being addressed. If a player says "Diana, come here", Amelia ignores it. If a generic command is given, the bots can cooperate.
• Glassmorphism WebUI Dashboard: A professional, responsive localhost:3000 control panel. Monitor live bot logs, inventory, health, toggle behavior modes, and spawn/kill bot instances with a single click.
• Autonomous Self-Prompter: Bots don't just wait for orders. When given a long-term goal like "gather 64 iron ore", their SelfPrompter mechanism automatically breaks down the task, queries their environment, and executes continuous actions until the goal is met.
• Local GGUF & Remote API Support: Connect bots to remote OpenAI-compatible APIs (like LLM7.io) or run completely offline using local GGUF models (like Qwen2.5) via node-llama-cpp.
• Speech-to-Text Voice Control: Push-to-talk integration using Python allows you to speak natural language commands directly to the bots.

---

🛠️ Setup & Installation

Prerequisites

• Node.js: v18 or higher recommended.
• Python: For the Voice STT module (optional).
• Minecraft Server: A running Minecraft Java Edition server (e.g., Paper/Spigot) configured to allow offline/cracked accounts (online-mode=false in server.properties).

1. Clone & Install

git clone https://github.com/JoePlayer911/amelia.git
cd amelia
npm install

2. Configure API Keys

By default, the bots use the LLM7.io API. You must create a file named llm7ioAPIkey.txt in the root directory. If you plan to use multiple bots at once, place each unique API key on a new line in this file. The BotManager will automatically distribute one key to each spawned bot to prevent rate-limiting.

sk-your-first-api-key
sk-your-second-api-key

3. (Optional) Setup Voice Control

Install the necessary Python requirements:

pip install SpeechRecognition pyaudio keyboard

4. (Optional) Local LLM Setup

If you prefer running offline, place a GGUF model (e.g., qwen2.5-3b-instruct-q5_0.gguf) in the models/ directory and select "Local GGUF Model" when running the startup script.

---

🚀 How to Run

Simply execute the included batch file:

./start.bat

The script will launch an interactive menu asking:

1. Which AI Brain to use (API vs Local).
2. Whether to enable Voice Control.
3. Whether to enable insecure Dynamic Code Generation.

Once started, the system will connect the primary bot (Amelia) to the Minecraft server on localhost:25565 and start the WebUI. Open your browser to http://localhost:3000 to access the dashboard.

---

🧠 Codebase Architecture & Function Reference

The codebase is highly modularized to separate basic server communication from AI reasoning and state management.

bot.js

The main entry point. It handles the mineflayer instance creation, initializes the WebUI server, and intercepts in-game chat.

• BotManager Registration: Every bot created (including the main one) is registered into the botManager to keep track of running instances.
• Name-Based Routing: The bot.on('chat') listener filters messages. It checks the OWNER_NAMES array and botManager.getActiveBots(). If a message explicitly contains a specific bot's name, only that bot's Brain receives it.

src/botManager.js

A centralized factory for managing multiple bots.

• spawnBot(name): Instantiates a new mineflayer bot, assigns it an available API key from llm7ioAPIkey.txt, and initializes its dedicated Brain, Perception, and state.
• killBot(name): Gracefully disconnects a bot and frees up its API key.

src/brain.js

The core LLM decision engine.

• agentLoop(): The heartbeat of the AI. It formats the bot's current Context (health, inventory, nearby blocks) and passes it to the LLM alongside recent conversation history. The LLM responds with natural language and JSON <tool> actions.
• Anti-Runaway Throttle: Prevents bots from getting stuck in endless back-and-forth chat loops with each other by forcing them to yield to human players after 2 consecutive bot-to-bot messages.
• Memory Tracking: Automatically summarizes old conversation logs and stores important long-term data in memory.json.

src/agentState.js

Handles multi-world persistent memory storage (memory.json and narrative.json). Note: In Amelia 2.0, instance-specific transient state (like current task, targets, and thinking state) was migrated out of this file and is now attached directly to bot.state to ensure multi-bot thread safety.

src/perception.js

An event-driven monitor that constantly watches the bot's surroundings.

• Detects incoming attacks (under_attack), low health (health_low), and aggressive mobs (threat_detected), instantly emitting events that interrupt the Brain and trigger self-defense modes.

src/modes.js

A background ticker that handles repetitive, reflexive behaviors so the LLM doesn't have to waste tokens on them.

• self_defense: Automatically equips weapons and fights back if attacked.
• item_collecting: Automatically walks towards and picks up dropped items nearby.
• torch_placing: Drops torches when light levels get too low.
• unstuck: Detects if the bot is trapped or moving against a wall and attempts to jump/navigate out.

src/selfPrompter.js

The autonomous goal engine. When given a high-level task via the set_goal tool, the SelfPrompter acts as an internal "user", continually prompting the Brain to evaluate its progress and take the next logical step until the goal is completed.

---

🧰 Skill Reference (src/skills/)

The bots have access to a vast array of "tools" (skills) they can invoke via JSON. Each file in src/skills/ maps to specific actions:

Navigation (navigation.js)

• follow (target): Uses pathfinder to seamlessly track and follow a player.
• goto (x, y, z): Navigates to absolute coordinates.
• goto_loc (name): Navigates to a named location stored in the bot's memory.
• moveAway (distance): Retreats in the opposite direction of current threats.

World Interaction (world.js)

• collect (block, amount): Safely locates, pathfinds to, and mines specific blocks. Features smart tree detection to avoid breaking player-built wooden houses.
• place (block): Places a block from inventory into the world.
• dig (block): Breaks a specific block instance.
• sleep / wakeup: Interacts with beds to skip the night.

Inventory & Crafting (inventory.js, crafting.js)

• inventory: Queries current inventory state.
• equip (item, destination): Equips armor or tools.
• toss / drop_all: Discards unwanted items.
• givePlayer (item, player, amount): Walks to a player and tosses items to them.
• consume (food): Eats food to restore health/hunger.
• deposit / withdraw: Manages items in nearby chests.
• craft (item, count): Calculates recipes and crafts items, automatically using nearby crafting tables if required.

Combat (combat.js)

• attack (target): Engages in melee combat using the mineflayer-pvp plugin.
• shoot (target): Uses bows/crossbows for ranged attacks.
• guard: Patches around a location defending it from hostile mobs.

---

🤝 Contributing

We welcome contributions! To add a new skill to Amelia:

1. Create a new function inside the appropriate src/skills/*.js file.
2. Ensure your function reads and modifies the instance-specific bot.state (not a global state).
3. Add the JSON schema for your new tool to the SYSTEM_PROMPT in bot.js.
4. Submit a Pull Request!

📄 License

This project is licensed under the MIT License.