Architecture

Agent Systems

🤖 Agent Systems#

Agent Modes (Tick-Based Reactive)#

Modes run every game tick (~50ms). Priority = list order. First mode wins.

Mode Trigger Behavior
self_preservation fire/lava/drowning/low HP flee, place water, dodge falling blocks
hunting hunger low find and kill food animals
cowardice takes damage + low HP flee from attacker
self_defense takes damage + HP ok fight back
unstuck stuck >40 ticks force move, look around, unstuck
item_collecting nearby item on ground auto-collect dropped items
torch_placing low light level nearby place torches
idle_staring nothing to do look at nearby entity
cheat_mode allow_insecure_coding: true exec raw code
auto_eat hungry eat from inventory

Modes can interrupt: ['all'] or specific modes. Use execute(mode, agent, fn) to fire actions without blocking the tick loop.

Command System#

Query Commands (read-only, instant)#

!stats !inventory !nearbyBlocks !craftable !entities !time !weather !positions !savedPlaces !goal !task

Action Commands (async, interruptible)#

!goToPlayer !followPlayer !goToCoordinates !goToPlace !attack !attackPlayer !collectBlocks !craftRecipe !smeltItem !placeHere !equip !discard !eat !newAction !stop !setMode !task !startConversation !endConversation

Command Parsing#

  • Regex: !(\w+)(?:\((args)\))?
  • Types: string int float boolean BlockName ItemName BlockOrItemName
  • Domain validation: [min, max, '[]'] interval syntax
  • Blacklist via settings.blocked_actions + task.blocked_actions

!newAction(description) — Dynamic Code#

LLM writes mineflayer JS, linted + sandboxed, injected with full $CODE_DOCS context (RAG via skill embedding similarity).

Cooperation Framework — 5 Levels# 

COOP_LEVEL=1  BroadcastAgent  — chat-based intent broadcasting
COOP_LEVEL=2  RequestAgent    — REQ/RES protocol via chat
COOP_LEVEL=3  NegotiationAgent— default; propose/accept/reject
COOP_LEVEL=4  EmergentAgent   — reputation + vocabulary building
COOP_LEVEL=5  CollectiveAgent — hive-mind coordination

Level 1: Broadcast 🗣️#

Bots shout intentions. “I am mining wood.” Avoids collision, basic awareness.

Level 2: Request/Response 📨#

Direct commands. “Hey Bob, give me 5 iron.” Resource sharing, task delegation.

Level 3: Negotiation 🤝#

Multi-turn bargaining. “I’ll build the wall if you mine the stone.” Conflict resolution.

Level 4: Emergent Protocol 🧬#

Bots invent shorthand via frequency analysis. “M@100,64,100” instead of full coordinates.

Level 5: Collective Intelligence 🐝#

Swarm voting. Weighted consensus algorithms for strategic decisions.

Protocol Format (Chat-Based)# 

@TargetBot REQ:abc123 action {"params": ...}
@OriginBot RES:abc123 {"success": true, "result": ...}

Timeout: 30s per request. Reputation map tracks per-bot trust.

Reputation System 🏦#

  • +Score: Successful trade, fulfilled request
  • -Score: Betrayal, failed task
  • Low reputation bots are ignored in negotiations

Hivemind Toggle 🧠#

  • Individual Mode: Bots act on their own personality/goals
  • Hive Mode: Bots pause, pool observations, calculate global optimal plan, execute assigned sub-tasks

Mineflayer Stack#

Core Plugins#

Plugin Role
mineflayer Minecraft bot protocol client
mineflayer-pathfinder A* navigation: GoalBlock GoalNear GoalFollow GoalXZ
mineflayer-pvp Basic PVP/PVE combat
mineflayer-collectblock Smart block collection with pathfinding
mineflayer-armor-manager Auto equip best armor
mineflayer-auto-eat Auto eat when hungry
minecraft-data Block/item/entity data per version
prismarine-item Item parsing + crafting
vec3 3D vector math

Key Pathfinder Patterns# 

const { pathfinder, Movements, goals: { GoalNear, GoalBlock } } = require('mineflayer-pathfinder')
bot.loadPlugin(pathfinder)
const defaultMove = new Movements(bot)
defaultMove.canDig = true
defaultMove.allowSprinting = true
bot.pathfinder.setMovements(defaultMove)
bot.pathfinder.setGoal(new GoalNear(x, y, z, range))
bot.pathfinder.stop()  // cancel navigation

Custom Movements# 

defaultMove.blocksCantBreak.add(bot.registry.blocksByName['chest'].id)
defaultMove.blocksToAvoid.add(bot.registry.blocksByName['lava'].id)
defaultMove.liquidCost = 3
defaultMove.maxDropDown = 4

Agent Profile Format# 

{
  "name": "AgentName",
  "model": { "api": "openrouter", "model": "google/gemini-2.5-flash" },
  "code_model": "optional separate model for codegen",
  "vision_model": "optional separate model for vision",
  "embedding": { "api": "openrouter", "model": "text-embedding-3-small" },
  "conversing": "system prompt with $VARs",
  "coding": "coding system prompt",
  "personality": "You are a focused survival assistant.",
  "modes": { "self_preservation": true, "hunting": true },
  "cooldown": 0,
  "max_tokens": null
}

Supported APIs#

openrouter · openai · anthropic · google · groq · ollama · mistral · deepseek · xai · cerebras · huggingface · vllm · replicate · novita · hyperbolic · azure

Base Profiles (merged priority: default < base < individual)#

  • profiles/defaults/_default.json — base defaults
  • profiles/defaults/survival.json — survival mode
  • profiles/defaults/assistant.json — assistant mode
  • profiles/defaults/creative.json — creative mode
  • profiles/defaults/god_mode.json — unlimited power mode