mc_aiplayer

LLM plans. Tasks execute. Bob survives.

AIBot spawns a real server-side player that perceives the world, back-chains your goal into a complete plan, and carries it out on its own — mining, fighting, farming, surviving.

🤖 What is AIBot?

AIBot is an open-source, autonomous AI agent for Minecraft. It's a server-side Fabric mod for Minecraft 1.21.3 in which a large language model (LLM) — DeepSeek by default, or any OpenAI-compatible model — drives a real in-game player that plays the game on its own.

Give it a goal in plain English or Chinese — "mine 3 diamonds", "build a house", "get me some food" — and AIBot perceives the world, plans the dependency-correct steps, and executes them autonomously: mining, crafting, smelting, building, farming, breeding, fighting, fishing, trading, and surviving on any randomly-generated, real-terrain world.

Unlike a hard-coded bot or a script, AIBot splits the brain in two: the LLM decides what to do, and a deterministic engine reliably handles how. It is not a client-side hack or cheat — it spawns a legitimate server-side fake player (in the Carpet-mod tradition) that obeys normal game rules.

Keywords: Minecraft AI · autonomous agent · LLM agent · AI that plays Minecraft · Fabric mod · server-side bot · natural-language game AI · DeepSeek / GPT-style tool-calling agent.

✨ Why AIBot

Most "AI in games" demos either let a language model hallucinate raw actions, or hard-code a rigid script. AIBot does neither — it splits the brain in two:

• 🧠 The LLM understands intent. You say "mine 3 diamonds"; DeepSeek interprets it and picks from 62 tools.
• ⚙️ A deterministic engine guarantees execution. A backward-chaining planner expands that goal into a dependency-correct plan, 36 self-contained task state machines run it reliably, and a five-layer safety net keeps the bot alive.

The result is an agent that is flexible enough to take orders in natural language, yet robust enough to actually finish the job.

🎬 See it in action

/aibot brain say Bob mine 3 diamonds

AIBot back-chains the goal into a full plan and executes it step by step:

chop oak → crafting table → wooden pickaxe → mine stone → stone pickaxe
→ descend to Y16 → mine iron → smelt → iron pickaxe → gear up
→ staircase down to Y-59 → ⛏  mine diamonds  ✓

You never hand it a step list. If a step fails, it re-plans. If it's drowning or under attack, it bails out and survives.

🧩 Features

🏗️ Architecture

One principle: the LLM plans, deterministic tasks execute.

flowchart TB
    P["🎮 Player — natural language · /aibot · Bob panel"] --> B
    subgraph COG["Cognition & Decision"]
      B["🧠 Brain · DeepSeek LLM<br/>62 tools"] --> G["🎯 GoalPlanner<br/>backward-chaining"]
      G --> E["⚙️ GoalExecutor<br/>step state machine"]
    end
    E --> T["🔧 Task FSM ×36<br/>mine · smelt · craft · combat · farm · build …"]
    T --> A["🛠️ Action primitives + A* pathfinding"]
    A --> W["🌍 Minecraft world · Fabric 1.21.3"]
    W -->|perception| B
    S["🛡️ Safety net · every tick<br/>NavSafety → Stuck → Danger → Idle"] -. guards .-> T

🚀 Quick Start

Requirements

Build & run

git clone https://github.com/zoyluoblue/mc_aiplayer.git
cd mc_aiplayer

./gradlew build        # build the mod
./gradlew runServer    # dev server
./gradlew runClient    # dev client

Configure the LLM

Provide your DeepSeek API key via environment variable (recommended):

export DEEPSEEK_API_KEY="sk-your-key"

On first run the mod writes aibot.json to the Fabric config directory. You can also set the key, base URL and model there:

{
  "deepseek": { "baseUrl": "https://api.deepseek.com", "model": "deepseek-chat" }
}

Any OpenAI-compatible endpoint works — just point baseUrl at your provider.

🎮 Usage

/aibot spawn Bob                              # spawn an AI player
/aibot list                                   # list active bots
/aibot brain say Bob mine 3 diamonds          # natural-language goal
/aibot task assign Bob mine minecraft:stone 16
/aibot task status Bob                         # inspect / abort a task
/aibot brain status Bob

Press Alt + 0 in-game to open the Bob control panel — track health, hunger, task, brain state, token usage and inventory, and send natural-language messages directly.

🧠 How it works

📦 Project structure

src/main/java/io/github/zoyluo/aibot
├── action/        # low-level: move, mine, interact, inventory, build
├── brain/         # LLM requests, tool registry, decision coordination
├── command/       # /aibot commands
├── coordination/  # multi-bot task board & idle coordination
├── craft/         # recipes & crafting helpers
├── entity/        # the AI player entity
├── goal/          # declarative goals, planner, executor
├── mining/        # ore scan & long-range prospector
├── pathfinding/   # A* pathfinding & danger checks
├── task/          # deterministic task state machines + safety net
└── …              # log · memory · network · observe · persist · mixin

🛠️ Tech stack

Java 21 · Fabric (Loader 0.18.4, API 0.114.1+1.21.3) · Yarn 1.21.3+build.2 · Gradle · DeepSeek (OpenAI-compatible API).

🗺️ Roadmap

• Zero-to-hero goals — food (5 paths), full iron armor + sword, house, base, stockpiles
• Real-terrain reliability harness — /aibot verify · multi-seed success-rate measurement
• Unified survival layer — drowning / lava / fire / threats + corpse recovery; shaft-flood sealing
• Natural-language commander hardening — intent→tool wiring regression (tool_dispatch), long-range navigation
• Reliable deep diamond mining on random terrain
• Obsidian via water-on-lava (≥15)
• House completion under night mobs (shed-first / build-by-day)
• Multi-bot collaboration · long-term memory recall

❓ FAQ

Can an AI play Minecraft on its own? Yes. AIBot is an autonomous AI agent that plays Minecraft without human input — you give one natural-language goal and it mines, builds, farms, fights, and survives by itself on real-terrain worlds.

How does a large language model (LLM) control a Minecraft bot? The LLM only decides intent — it