Minecraft Civilization AI

A long-term autonomous Minecraft civilization built with Mineflayer, designed as a modular AI system capable of surviving, gathering resources, crafting, building, farming, and eventually managing an entire civilization.

Current Version: v0.1.0 – Phase 1 Foundation Complete

---

Project Vision

The goal of this project is to create a fully autonomous Minecraft AI that progresses through the game the way a human civilization would:

• Survive.
• Gather resources.
• Build infrastructure.
• Farm and breed animals.
• Mine automatically.
• Store and organize items.
• Craft tools and equipment.
• Explore the world.
• Eventually coordinate multiple bots into a functioning civilization.

The project is intentionally built in phases, with each phase producing reusable skills that higher-level AI systems can compose.

---

Current Progress

Phase 1 — Foundation (Completed)

The entire low-level skill system has been implemented and tested.

Skill	Status
Movement	✅ Complete
World Scanning	✅ Complete
Resource Detection	✅ Complete
Inventory Management	✅ Complete
Equipment Management	✅ Complete
Mining	✅ Complete
Placement	✅ Complete
Crafting	✅ Complete
Container / Storage	✅ Complete

Milestone: v0.1.0

---

Phase 1.11 — Next (In Progress)

Upcoming systems:

• Health monitoring.
• Hunger monitoring.
• Eating food.
• Death detection.
• Respawn handling.
• Farming primitives.

---

Features Implemented

Movement Skill

Reliable pathfinding wrapper around Mineflayer Pathfinder.

Features:

• Move to exact coordinates.
• Move near a position.
• Timeout protection.
• Stuck detection.
• Cancellation support.
• Structured movement results.

Example:

come
goto x y z
goto-block chest

---

World Skill

Read-only interaction with the Minecraft world.

Features:

• Block lookup.
• Target block detection.
• Nearest block search.
• Nearby block scanning.
• Block description utilities.

Uses direct world scanning for reliability.

---

Resource Skill

Locate resources within loaded chunks.

Supported functionality:

• Find nearest block of a given type.
• Search nearby resources.
• Integrates directly with Movement Skill.

---

Inventory Skill

Inventory inspection utilities.

Features:

• Count items.
• Find items.
• List inventory.
• Empty slot count.
• Held item detection.

---

Equipment Skill

Tool and armor management.

Features:

• Equip tools.
• Equip armor.
• Auto-select correct tool.
• Verification after every equip action.

---

Mining Skill

Mining utilities.

Features:

• Mine blocks.
• Verify mined block.
• Tool integration.
• Resource collection support.

---

Placement Skill

Block placement utilities.

Features:

• Place blocks.
• Place crafting tables.
• Position validation.
• Placement verification.

---

Crafting Skill

Crafting utilities.

Features:

• Open crafting table.
• Craft recipes.
• Verify crafted items.
• Inventory integration.

---

Container Skill

Storage interaction system.

Fully verified against Mineflayer container windows.

Features:

• Open nearest container.
• Close container.
• Container status.
• Read contents.
• Find specific item.
• Deposit items.
• Withdraw items.
• Verification of every transaction.

Example commands:

open-container
container-status
container-contents
container-find-item cobblestone
container-withdraw cobblestone 10
container-deposit cobblestone 10
close-container

Container transactions verify both:

• Container state.
• Player inventory state.

---

Project Structure

MinecraftCivilization/

├── docs/
│   ├── Project Plan
│   ├── Development Notes
│   └── Progress Updates
│
├── paper-plugin/
│   └── CivilizationCompat/
│       ├── src/
│       ├── gradle/
│       ├── build.gradle.kts
│       ├── settings.gradle.kts
│       ├── gradlew
│       └── gradlew.bat
│
├── src/
│   ├── skills/
│   │   ├── movement.js
│   │   ├── world.js
│   │   ├── resource.js
│   │   ├── inventory.js
│   │   ├── equipment.js
│   │   ├── mining.js
│   │   ├── placement.js
│   │   ├── crafting.js
│   │   └── container.js
│   │
│   ├── index.js
│   └── testbot.js
│
├── package.json
├── package-lock.json
├── README.md
└── .gitignore

---

Technology Stack

Component	Technology
Minecraft Bot	Mineflayer
Pathfinding	mineflayer-pathfinder
Inventory / Windows	prismarine-windows
Minecraft Data	minecraft-data
Plugin Compatibility	Paper API (Java/Kotlin Gradle Project)
Runtime	Node.js 22 LTS
Java	JDK 21

---

Installation

1. Clone the repository

git clone https://github.com/Shreyas1860/MC-CIVILISATION.git
cd MC-CIVILISATION

2. Install Node dependencies

npm install

3. Build the Paper compatibility plugin

cd paper-plugin/CivilizationCompat
.\gradlew.bat build

The compiled plugin will be generated inside:

paper-plugin/CivilizationCompat/build/libs/

4. Run the bot

From the project root:

npm start

---

Testing Commands

The project currently includes a dedicated testing harness (testbot.js) for validating every implemented skill.

Examples:

Movement

come
goto x y z
goto-block oak_log

Inventory

inventory
count cobblestone
held-item

Equipment

equip diamond_pickaxe
equip-tool stone

Mining

mine stone
mine oak_log

Placement

place crafting_table

Crafting

craft sticks 4
craft crafting_table 1

Containers

open-container
container-contents
container-find-item cobblestone
container-withdraw cobblestone 10
container-deposit cobblestone 10
close-container

Every command returns structured status information for debugging.

---

Development Principles

The project follows a strict architecture:

• Every gameplay capability is implemented as an independent Skill.
• Skills expose structured result objects instead of raw Mineflayer responses.
• Every world interaction performs verification before reporting success.
• High-level AI systems will compose skills rather than interacting with Mineflayer directly.

This keeps the project modular and testable.

---

Roadmap

Phase 1 — Foundation

• Movement
• World
• Resources
• Inventory
• Equipment
• Mining
• Placement
• Crafting
• Containers / Storage

Phase 1.11 — Survival

• Health
• Hunger
• Eating
• Death Detection
• Respawn
• Farming

Phase 2 — Autonomous Survival

• Wood gathering loop.
• Stone progression.
• Iron progression.
• Food acquisition.
• Smelting.
• Basic shelter.

Phase 3 — Civilization

• Village infrastructure.
• Resource storage system.
• Building planner.
• Farming automation.
• Animal breeding.
• Exploration system.

Phase 4+

• Multi-agent coordination.
• Economy.
• Expansion.
• Persistent memory.
• AI manager.

---

Versioning

The project uses semantic milestone tags.

Version	Milestone
v0.1.0	Phase 1 Foundation Complete
v0.2.0	Phase 1.11 Survival Complete
v0.3.0	Autonomous Survival Loop
v1.0.0	First Fully Autonomous Civilization

---

Author

Shreyas

A long-term personal project exploring autonomous AI agents inside Minecraft using Mineflayer.