MC-Player

An AI-powered Minecraft player that uses LLMs (GPT-4, Claude, Ollama) to autonomously play the game.

Features

• Autonomous Gameplay: Survives, explores, gathers resources, crafts tools, and builds shelters
• Multiple LLM Providers: OpenAI, Anthropic Claude, or local Ollama models
• Skill System: Navigation, mining, crafting, combat, building, and inventory management
• Memory & Goals: Tracks past actions, learns from failures, and manages objectives
• Chat Interaction: Responds to player commands via in-game chat

Requirements

• Node.js 18+ (LTS recommended)
• Minecraft Java Edition 1.20.4
• API key for OpenAI, Anthropic, or local Ollama installation

Quick Start

1. Install dependencies:

   npm install

2. Configure environment:

   cp .env.example .env
   # Edit .env with your API keys and server details

3. Start a Minecraft server (singleplayer with LAN, or dedicated server)

4. Run the bot:

   npm start

Configuration

Environment Variables

Variable	Description	Default
LLM_PROVIDER	LLM provider (openai, anthropic, ollama)	openai
OPENAI_API_KEY	OpenAI API key	-
ANTHROPIC_API_KEY	Anthropic API key	-
OLLAMA_HOST	Ollama server URL	http://localhost:11434
OLLAMA_MODEL	Ollama model name	llama3.2
MC_HOST	Minecraft server host	localhost
MC_PORT	Minecraft server port	25565
MC_USERNAME	Bot username	AIPlayer
MC_VERSION	Minecraft version	1.20.4
AUTONOMOUS_MODE	Enable autonomous play	true
DEBUG	Enable debug logging	false

CLI Options

npm start -- [options]

Options:
  --profile, -p    Bot profile (default, explorer)
  --host, -h       Minecraft server host
  --port           Minecraft server port
  --username, -u   Bot username
  --provider       LLM provider
  --debug, -d      Enable debug mode
  --no-autonomous  Disable autonomous mode
  --help           Show help

Bot Profiles

Create custom profiles in src/config/profiles/:

{
  "name": "MyBot",
  "personality": "A brave adventurer...",
  "goals": ["Explore caves", "Find diamonds"],
  "survivalPriority": 0.7,
  "explorationDrive": 0.9,
  "aggressiveness": 0.5
}

Available Skills

Navigation

• goto(x, y, z) - Navigate to coordinates
• gotoPlayer(username) - Go to a player
• follow(username) - Follow a player
• stop() - Stop movement
• wander(radius) - Wander randomly
• flee(distance) - Run away from danger

Mining

• mine(x, y, z) - Mine specific block
• collect(blockName, count) - Collect block type
• findAndMine(oreName, maxCount) - Find and mine ores
• digDown(depth) - Dig down safely
• digArea(width, height, depth) - Clear an area

Crafting

• craft(itemName, count) - Craft with 2x2 grid
• craftTable(itemName, count) - Craft with crafting table
• smelt(itemName, count) - Smelt in furnace
• listCraftable() - List craftable items

Combat

• attack(entityName) - Attack an entity
• hunt(animalType, count) - Hunt animals
• defend(duration) - Defend against mobs
• equipWeapon() - Equip best weapon
• equipArmor() - Equip best armor

Building

• place(blockName, x, y, z) - Place a block
• buildWall(blockName, width, height, direction) - Build a wall
• buildFloor(blockName, width, depth) - Build a floor
• buildShelter(blockName) - Build a simple shelter
• placeTorch(x, y, z) - Place a torch

Inventory

• inventory() - List inventory
• equip(itemName, slot) - Equip an item
• drop(itemName, count) - Drop items
• storeChest(itemName, count) - Store in chest
• takeChest(itemName, count) - Take from chest
• eat(foodName) - Eat food
• toss(itemName, playerName, count) - Toss to player

Chat Commands

Talk to the bot in-game chat:

"come here" - Bot will navigate to you
"follow me" - Bot will follow you
"stop" - Stop current action
"mine some stone" - Mine nearby stone
"craft a pickaxe" - Craft if materials available
"build a shelter" - Build a basic shelter

Architecture

src/
├── index.ts          # Entry point
├── config/           # Configuration and profiles
├── llm/              # LLM provider abstraction
├── bot/              # Mineflayer bot controller
├── agent/            # AI agent core
│   ├── memory.ts     # State and history tracking
│   ├── goals.ts      # Goal management
│   ├── prompter.ts   # LLM prompt construction
│   └── self-loop.ts  # Autonomous behavior loop
└── skills/           # Action implementations

License

MIT