{"id":51503001,"url":"https://github.com/zoyluoblue/mc_aiplayer","last_synced_at":"2026-07-07T21:30:44.810Z","repository":{"id":357112112,"uuid":"1234425239","full_name":"zoyluoblue/mc_aiplayer","owner":"zoyluoblue","description":"Autonomous AI agent that plays Minecraft on its own — a server-side Fabric mod (MC 1.21.3) where a DeepSeek / OpenAI-compatible LLM drives a real player to mine, build, farm, fight and survive from natural-language commands. The LLM plans; deterministic tasks execute.","archived":false,"fork":false,"pushed_at":"2026-06-29T12:34:16.000Z","size":17788,"stargazers_count":211,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-29T14:26:10.219Z","etag":null,"topics":["agent","ai","ai-agent","artificial-intelligence","autonomous-agents","deepseek","fabric","fabric-mod","game-ai","gpt","java","large-language-models","llm","llm-agent","minecraft","minecraft-1-21","minecraft-bot","minecraft-mod","npc","pathfinding"],"latest_commit_sha":null,"homepage":"https://github.com/zoyluoblue/mc_aiplayer/wiki","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zoyluoblue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-10T06:59:59.000Z","updated_at":"2026-06-29T12:34:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zoyluoblue/mc_aiplayer","commit_stats":null,"previous_names":["zoyluoblue/mc_aiplayer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zoyluoblue/mc_aiplayer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoyluoblue%2Fmc_aiplayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoyluoblue%2Fmc_aiplayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoyluoblue%2Fmc_aiplayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoyluoblue%2Fmc_aiplayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoyluoblue","download_url":"https://codeload.github.com/zoyluoblue/mc_aiplayer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoyluoblue%2Fmc_aiplayer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35243953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","ai-agent","artificial-intelligence","autonomous-agents","deepseek","fabric","fabric-mod","game-ai","gpt","java","large-language-models","llm","llm-agent","minecraft","minecraft-1-21","minecraft-bot","minecraft-mod","npc","pathfinding"],"created_at":"2026-07-07T21:30:44.074Z","updated_at":"2026-07-07T21:30:44.797Z","avatar_url":"https://github.com/zoyluoblue.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"promo/banner.png\" alt=\"AIBot — Autonomous Minecraft AI Player\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eAIBot\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eAn autonomous AI agent that plays Minecraft.\u003c/b\u003e\u003cbr\u003e\n  Tell \u003cb\u003eBob\u003c/b\u003e once, in plain language — he mines, builds, farms, fights, and survives on his own.\u003cbr\u003e\n  \u003csub\u003e\u003ci\u003eA real server-side Fabric mod — not a Python harness or a Mineflayer bot account.\u003c/i\u003e\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-64f5a0?style=flat-square\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Minecraft 1.21.3\" src=\"https://img.shields.io/badge/Minecraft-1.21.3-62B47A?style=flat-square\"\u003e\n  \u003cimg alt=\"Fabric Loader 0.18.4\" src=\"https://img.shields.io/badge/Fabric-Loader%200.18.4-DBB69B?style=flat-square\"\u003e\n  \u003cimg alt=\"Java 21\" src=\"https://img.shields.io/badge/Java-21-E76F00?style=flat-square\"\u003e\n  \u003cimg alt=\"LLM: DeepSeek\" src=\"https://img.shields.io/badge/LLM-DeepSeek-5A67F2?style=flat-square\"\u003e\n  \u003cimg alt=\"PRs welcome\" src=\"https://img.shields.io/badge/PRs-welcome-75d9ff?style=flat-square\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eEnglish\u003c/b\u003e\u0026nbsp;·\u0026nbsp;\u003ca href=\"README.zh-CN.md\"\u003e简体中文\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e **LLM plans. Tasks execute. Bob survives.**\n\u003e\n\u003e 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.\n\n## 🤖 What is AIBot?\n\n**AIBot is an open-source, autonomous AI agent for Minecraft.** It's a server-side [Fabric](https://fabricmc.net/) 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.\n\nGive 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.\n\nUnlike 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.\n\n\u003e **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.\n\n## ✨ Why AIBot\n\nMost \"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:\n\n- 🧠 **The LLM understands intent.** You say *\"mine 3 diamonds\"*; DeepSeek interprets it and picks from **62 tools**.\n- ⚙️ **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.\n\nThe result is an agent that is **flexible enough to take orders in natural language, yet robust enough to actually finish the job.**\n\n## 🧭 How AIBot is different\n\nThe LLM-in-Minecraft space has two well-known lines of work — AIBot takes a third path.\n\n| | **Skill-learning agents** *([Voyager](https://github.com/MineDojo/Voyager))* | **Mineflayer bots** *([Mindcraft](https://github.com/mindcraft-bots/mindcraft))* | **AIBot** |\n|---|---|---|---|\n| **Runs as** | Python + Mineflayer + a MC instance | Node.js + Mineflayer | **a drop-in server-side Fabric mod** |\n| **The player is** | a Mineflayer client that logs in | a Mineflayer client that logs in | **a real, server-spawned player** (Carpet-style fake player) |\n| **The LLM…** | writes \u0026 self-debugs JavaScript | can write / run JavaScript | **only plans** — emits goals \u0026 tool calls, never in the execution loop |\n| **Execution** | LLM-generated programs | LLM-generated programs | **deterministic task state machines** |\n| **Default model** | GPT-4 | multi-provider | **DeepSeek** · any OpenAI-compatible |\n\nThese are different bets, not better-or-worse. Voyager pioneered open-ended **skill discovery**; Mindcraft explores **multi-agent** social play — things AIBot deliberately doesn't chase. AIBot optimizes for the opposite: **take a goal in plain language and finish it reliably**, because the model never touches the execution loop and every task carries its own watchdog and safety net.\n\n## 🎬 See it in action\n\n```\n/aibot brain say Bob mine 3 diamonds\n```\n\nAIBot back-chains the goal into a full plan and executes it step by step:\n\n```\nchop oak → crafting table → wooden pickaxe → mine stone → stone pickaxe\n→ descend to Y16 → mine iron → smelt → iron pickaxe → gear up\n→ staircase down to Y-59 → ⛏  mine diamonds  ✓\n```\n\nYou 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**.\n\n## 📏 Measured, not marketing\n\nMost \"AI plays Minecraft\" projects show one lucky highlight reel. AIBot ships with a **reliability harness** (`/aibot verify`) that runs each goal across **many randomly-generated survival worlds** and reports real, multi-seed success rates — so capabilities are *earned*, not cherry-picked.\n\n- ✅ **Reliable today** — the full food chain (self-sufficiency **measured from 2 → 8 out of 10** across random seeds), iron gear \u0026 smelting, base-building by day, and ore mining across a battery of geometry stress-tests (pockets, walls, overhangs, deep veins, flooded shafts).\n- 🚧 **Honest about the hard parts** — deep diamond runs and 100-block bulk hauls on *arbitrary* random terrain are still climbing. You'll find them on the **roadmap** below — not dressed up as done.\n\n## 🧩 Features\n\n| | |\n|---|---|\n| 🗣️ **Natural-language control** | Plain English / Chinese commands, understood by a DeepSeek LLM wired to 62 tools. |\n| 🎯 **Goal back-chaining** | One goal → a dependency-correct multi-step plan. No manual breakdown. |\n| 🧩 **LLM + deterministic hybrid** | The model reasons; the engine executes. Flexible *and* reliable. |\n| 🎒 **9 one-shot goals** | Diamonds, a full iron armor set + sword, a house, a base (table/furnace/chest), cooked food, crops→bread, ore, item stockpiles — each from one command. |\n| 🍞 **Five food paths** | Hunt→cook, farm wheat→bread (waits for crops to grow), forage berries, infinite-water irrigation, cake, raid village fields — auto-picked by what's nearby. |\n| 🛡️ **Unified survival layer** | Drowning, lava, suffocation, stuck, threats, dark-traps — handled every tick; digs shafts that seal out flooding water. |\n| 🧍 **Human-like behavior** | Staircase mining (never straight down), no teleporting, no bunny-hopping. |\n| ⛏️ **Full survival loop** | Mine, smelt, craft, fight, hunt, farm, breed, build, fish, trade, sleep, gear up. |\n| 🔭 **Ore \u0026 tree prospecting** | Palette-level long-range scan locates resources and paths to them. |\n| 🌍 **Verified on real terrain** | A multi-seed reliability harness (`/aibot verify`) proves goals on randomly-generated worlds — not just flat test arenas. |\n| 🖥️ **Client control panel** | `Alt + 0` opens Bob's panel: health, hunger, task, tokens, inventory, chat. |\n\n## 🏗️ Architecture\n\n\u003e **One principle: the LLM plans, deterministic tasks execute.**\n\n```mermaid\nflowchart TB\n    P[\"🎮 Player — natural language · /aibot · Bob panel\"] --\u003e B\n    subgraph COG[\"Cognition \u0026amp; Decision\"]\n      B[\"🧠 Brain · DeepSeek LLM\u003cbr/\u003e62 tools\"] --\u003e G[\"🎯 GoalPlanner\u003cbr/\u003ebackward-chaining\"]\n      G --\u003e E[\"⚙️ GoalExecutor\u003cbr/\u003estep state machine\"]\n    end\n    E --\u003e T[\"🔧 Task FSM ×36\u003cbr/\u003emine · smelt · craft · combat · farm · build …\"]\n    T --\u003e A[\"🛠️ Action primitives + A* pathfinding\"]\n    A --\u003e W[\"🌍 Minecraft world · Fabric 1.21.3\"]\n    W --\u003e|perception| B\n    S[\"🛡️ Safety net · every tick\u003cbr/\u003eNavSafety → Stuck → Danger → Idle\"] -. guards .-\u003e T\n```\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003e164\u003c/b\u003e classes · \u003cb\u003e30K\u003c/b\u003e LOC · \u003cb\u003e62\u003c/b\u003e tools · \u003cb\u003e36\u003c/b\u003e task state machines · \u003cb\u003e9\u003c/b\u003e goal types · \u003cb\u003e5\u003c/b\u003e-layer safety net\u003c/sub\u003e\u003c/p\u003e\n\n## 🚀 Quick Start\n\n### Requirements\n\n| Component | Version |\n|---|---|\n| Minecraft | `1.21.3` |\n| Fabric Loader | `0.18.4+` |\n| Fabric API | `0.114.1+1.21.3` |\n| Yarn Mappings | `1.21.3+build.2` |\n| Java | `21` |\n\n### Build \u0026 run\n\n```bash\ngit clone https://github.com/zoyluoblue/mc_aiplayer.git\ncd mc_aiplayer\n\n./gradlew build        # build the mod\n./gradlew runServer    # dev server\n./gradlew runClient    # dev client\n```\n\n### Configure the LLM\n\nProvide your DeepSeek API key via environment variable (recommended):\n\n```bash\nexport DEEPSEEK_API_KEY=\"sk-your-key\"\n```\n\nOn first run the mod writes `aibot.json` to the Fabric config directory. You can also set the key, base URL and model there:\n\n```json\n{\n  \"deepseek\": { \"baseUrl\": \"https://api.deepseek.com\", \"model\": \"deepseek-chat\" }\n}\n```\n\n\u003e Any OpenAI-compatible endpoint works — just point `baseUrl` at your provider.\n\n## 🎮 Usage\n\n```mcfunction\n/aibot spawn Bob                              # spawn an AI player\n/aibot list                                   # list active bots\n/aibot brain say Bob mine 3 diamonds          # natural-language goal\n/aibot task assign Bob mine minecraft:stone 16\n/aibot task status Bob                         # inspect / abort a task\n/aibot brain status Bob\n```\n\nPress **`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.\n\n## 🧠 How it works\n\n| Layer | Package | Role |\n|---|---|---|\n| **Brain** | `brain` | DeepSeek tool-calling loop; turns intent into goals \u0026 actions |\n| **Goal engine** | `goal` | `Goal` → `GoalPlanner` (back-chaining) → `GoalExecutor` (FSM) |\n| **Tasks** | `task` | 36 self-contained state machines, each with its own watchdog |\n| **Action / Pathfinding** | `action` · `pathfinding` | `BlockMiner`, `DigNav`, `ActionPack`; A* with stand-ability checks |\n| **Knowledge** | `craft` · `mining` | recipes, mining/smelt chains, tool tiers, ore \u0026 tree prospector |\n| **Safety net** | `task` · `coordination` | `BotTickCoordinator`: NavSafety → Stuck → Danger → Goal → Idle |\n| **Entity** | `entity` | `AIPlayerEntity` — a real server-side fake player |\n\n## 📦 Project structure\n\n```text\nsrc/main/java/io/github/zoyluo/aibot\n├── action/        # low-level: move, mine, interact, inventory, build\n├── brain/         # LLM requests, tool registry, decision coordination\n├── command/       # /aibot commands\n├── coordination/  # multi-bot task board \u0026 idle coordination\n├── craft/         # recipes \u0026 crafting helpers\n├── entity/        # the AI player entity\n├── goal/          # declarative goals, planner, executor\n├── mining/        # ore scan \u0026 long-range prospector\n├── pathfinding/   # A* pathfinding \u0026 danger checks\n├── task/          # deterministic task state machines + safety net\n└── …              # log · memory · network · observe · persist · mixin\n```\n\n## 🛠️ Tech stack\n\n**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).\n\n## 🗺️ Roadmap\n\n- [x] Zero-to-hero goals — food (5 paths), full iron armor + sword, house, base, stockpiles\n- [x] Real-terrain reliability harness — `/aibot verify` · multi-seed success-rate measurement\n- [x] Unified survival layer — drowning / lava / fire / threats + corpse recovery; shaft-flood sealing\n- [ ] Natural-language commander hardening — intent→tool wiring regression (`tool_dispatch`), long-range navigation\n- [ ] Reliable deep diamond mining on random terrain\n- [ ] Obsidian via water-on-lava (≥15)\n- [ ] House completion under night mobs (shed-first / build-by-day)\n- [ ] Multi-bot collaboration · long-term memory recall\n\n## ❓ FAQ\n\n**Can an AI play Minecraft on its own?**\nYes. 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.\n\n**How does a large language model (LLM) control a Minecraft bot?**\nThe LLM only decides *intent* — it emits tool calls like `mine_ore` or `build_house` from a 62-tool API. A deterministic engine then back-chains the goal into a dependency-correct plan and runs it with 36 self-contained task state machines, so the bot is flexible enough to take orders yet reliable enough to finish them.\n\n**Is AIBot a hack, cheat, or client mod?**\nNo. AIBot is a **server-side** Fabric mod that spawns a legitimate fake player (in the Carpet-mod tradition) and plays by normal game rules. There is no client-side injection or x-ray.\n\n**Which LLMs / AI models does it support?**\nDeepSeek out of the box, and **any OpenAI-compatible endpoint** (GPT-style chat + tool-calling) — just point the `baseUrl` at your provider in `aibot.json`.\n\n**What Minecraft version and mod loader does it need?**\nMinecraft **1.21.3** on **Fabric** (Loader 0.18.4+, Fabric API 0.114.1+1.21.3), Java 21.\n\n**Can I command the bot in natural language?**\nYes — English or Chinese, via chat, the `/aibot brain say` command, or the in-game control panel (`Alt + 0`).\n\n**Is it open source?**\nYes, released under the MIT License.\n\n## 🤝 Contributing\n\nIssues and PRs are welcome! When touching Minecraft / Fabric API code, mind version compatibility — this project pins **Yarn 1.21.3+build.2**. Verify method signatures before changing item components, eating, fuel registration, mining speed, furnace inventory, or client networking.\n\n```bash\n./gradlew clean build   # please make sure this passes before opening a PR\n```\n\n## 📜 License\n\nReleased under the [MIT License](LICENSE). © 2026 zoyluo.\n\n## 🙏 Acknowledgements\n\nBuilt on [Fabric](https://fabricmc.net/). Natural-language reasoning powered by [DeepSeek](https://www.deepseek.com/). Inspired by the Carpet-mod fake-player tradition.\n\n---\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003eLLM plans · Tasks execute · Bob survives\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoyluoblue%2Fmc_aiplayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoyluoblue%2Fmc_aiplayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoyluoblue%2Fmc_aiplayer/lists"}