Citizens-Aware

Intelligent Agentic NPCs for Minecraft with LLM Integration

🌟 Overview

Citizens-Aware is a Minecraft plugin that brings intelligent, LLM-powered NPCs to your server. Each player can create their own personal AI companion that understands natural language, performs complex actions, and interacts with the Minecraft world autonomously.

🎯 Key Highlights:

• Personal AI NPCs: Each player gets their own intelligent companion
• Complete Environmental Awareness: NPCs can see and interact with ALL nearby entities, structures, blocks, and players
• Full Command Access: NPCs inherit your permissions and can execute ANY command you have access to
• Natural Language Processing: Chat naturally with NPCs using their names - no complex syntax required
• Autonomous Intelligence: NPCs make decisions, plan actions, and execute complex multi-step tasks independently
• Real-time World Understanding: Powered by state-of-the-art LLMs via OpenRouter with live world context
• Like Playing with a Friend: Your NPC companion can do everything you can do - build, explore, fight, trade, and more!
• Seamless Integration: Built on Citizens plugin with WebSocket communication for instant responsiveness

🧠 What Makes This Special: Your AI NPC isn't just a chatbot - it's a fully aware digital companion that can:

• See every entity around you (players, mobs, animals, items)
• Access your complete command arsenal (build, teleport, give items, change weather, etc.)
• Understand spatial relationships and navigate intelligently
• Remember context and maintain coherent conversations
• Execute complex plans like "build me a house" or "collect resources while I'm away"
• Inherit your exact player permissions and capabilities

It's like having an intelligent friend who never gets tired, never gets bored, and can help with anything you need in Minecraft!

---

🏗️ Architecture

Our system consists of three main components:

• 🔧 AgenticNPCPlugin (Java/Spigot): Handles NPC management and world interaction
• 🧠 FastAPI Server (Python): Processes natural language via LLM integration
• 🔗 WebSocket Communication: Real-time bidirectional messaging

📖 View Complete Architecture Documentation →

---

✨ Features

🤖 Personal NPC System

• One NPC per Player: Create your personal AI companion with /agenticnpc create <name>
• Name-based Interaction: Simply mention your NPC's name in chat to interact
• Privacy-focused: Only you receive responses from your NPC
• Ownership Tracking: Thread-safe player-NPC relationships

🚶 Advanced Movement System

Three distinct movement types for different use cases:

• go_to_user: "Come here" - One-time movement to player location
• move_to_entity: Move to specific targets, trees, or coordinates
• npc follow: Continuous following via Citizens commands

🌳 Intelligent Tree Management

• Smart Tree Detection: Scans 15-block radius for tree clusters
• Realistic Cutting: Progressive block-by-block tree removal
• Visual Effects: Sound effects, particles, and proper NPC facing
• Inventory Management: Wood goes directly to player inventory
• Cut Tree Tracking: Prevents re-scanning of already cut trees

🛠️ Comprehensive Tool System

NPCs can perform various actions through LLM-driven tools:

• give_item / remove_item: Inventory management
• run_command: Execute server commands as console
• move_to_entity / go_to_user: Advanced movement
• cut_tree: Realistic tree cutting with effects

📡 Real-time Communication

• WebSocket Protocol: Low-latency bidirectional communication
• Rich Context: NPCs receive inventory, location, nearby structures, and trees
• Agentic Loops: LLMs can make multiple tool calls in sequence
• JSON Message Format: Structured data exchange

📊 Intelligent Data Flow

• Context-aware: Real-time inventory, location, and world state
• Performance Optimized: Structure caching and efficient scanning
• Thread-safe: Concurrent data structures for multiplayer environments
• Smart Tracking: Prevents redundant operations

---

🚀 Quick Start

Prerequisites

• Minecraft Spigot/Paper server (1.19.4+)
• Java 8+ (JDK 17 recommended)
• Maven
• Python 3.8+
• Citizens plugin
• OpenRouter API key

Installation

1. Citizens Plugin

# Download Citizens plugin and place in plugins directory
# Restart your server

2. Build AgenticNPCPlugin

cd AgenticNPCPlugin
mvn clean package
cp target/agenticnpc-1.0-SNAPSHOT.jar /path/to/your/server/plugins/
# Restart server

3. FastAPI Server

cd citizens-aware-fastapi
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp env.example.txt .env
# Edit .env and add your OpenRouter API key
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Usage

# In Minecraft
/agenticnpc create Helper

# In chat
"Helper, can you cut down that tree?"
"Helper, come here please"
"Helper, give me some diamonds"

---

📚 Documentation

📖 Core Documentation

• 🏗️ Architecture Guide - Complete system architecture with visual diagrams
• 🔧 API Reference - Comprehensive API documentation with examples
• ⚙️ Setup Guide - Detailed installation and configuration
• ✨ Features Guide - Feature overview and usage examples

🔬 Technical Documentation

• 🧪 Spigot Testing - Communication testing guide
• ⚡ Forge Testing - Alternative platform testing

📊 Visual Architecture

All documentation includes professional mermaid diagrams rendered as high-quality images:

• System Architecture Overview
• Component Relationships
• Personal NPC Workflow
• Movement System Logic
• Tree Cutting Process
• Communication Flow
• Tool System Integration
• Data Flow Optimization

---

🛠️ Project Structure

├── AgenticNPCPlugin/           # Java plugin (Maven)
│   ├── src/main/java/         # Plugin source code
│   ├── pom.xml                # Maven dependencies
│   └── target/                # Compiled JAR
├── citizens-aware-fastapi/     # Python FastAPI server
│   ├── main.py                # WebSocket endpoints
│   ├── modules/               # LLM integration modules
│   └── requirements.txt       # Python dependencies
├── docs/                      # Comprehensive documentation
│   ├── ARCHITECTURE.md        # System architecture
│   ├── API_REFERENCE.md       # Complete API docs
│   └── *.md                   # Additional guides
├── assets/                    # Visual diagrams
│   ├── *.png                  # Rendered mermaid diagrams
│   └── *.mmd                  # Source mermaid files
└── README.md                  # This file

---

🔧 Configuration

Plugin Configuration

• WebSocket URI: ws://localhost:8000/ws/minecraft
• Scan Radii: Trees (15 blocks), Blocks (8 blocks), Structures (100 blocks)
• Tree Cutting: 3x3 area, up to 15 blocks high

FastAPI Configuration

# .env file
OPENROUTER_API_KEY=your_api_key_here

Server Configuration

• Host: 0.0.0.0 (configurable)
• Port: 8000 (configurable)
• WebSocket Endpoint: /ws/minecraft

---

🎯 Commands

Administrative Commands

/agenticnpc create <name>    # Create personal NPC
/agenticnpc status           # Show system status
/agenticnpc cleartrees       # Reset cut trees registry

Citizens Integration

/npc select <name>           # Select NPC for editing
/npc follow <player>         # Make NPC follow player
/npc moveto <x> <y> <z>      # Teleport NPC

---

🔍 Troubleshooting

Common Issues

• NPCs not responding: Check WebSocket connection and NPC ownership
• Tree cutting failures: Use /agenticnpc cleartrees to reset registry
• Connection issues: Ensure FastAPI server is running on correct port

📖 Complete Troubleshooting Guide →

---

🤝 Contributing

We welcome contributions! Please see our documentation for:

• Code architecture and patterns
• Testing procedures
• Development setup

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Key permissions:

• ✅ Commercial use
• ✅ Modification
• ✅ Distribution
• ✅ Private use

Requirements:

• 📄 Include copyright notice
• 📄 Include license text

---

🌟 Acknowledgments

Built with:

• Citizens - NPC framework
• Spigot - Minecraft server platform
• FastAPI - Modern Python web framework
• OpenRouter - LLM API gateway

---

Ready to bring intelligent NPCs to your Minecraft world? Get started with our setup guide!