🏘️ VillageAI - Intelligent Village & Economy System

Version: 2.1.0
Author: Duong2012G
Minecraft Version: 1.21+ (Spigot/Paper)
License: Apache 2.0

🎯 Overview

VillageAI is an advanced AI system for villages in Minecraft, providing:

🏘️ Village Management - Bell-based village detection and management
👥 Member Tracking - Automatic villager member tracking with unique names
🛡️ Intelligent Defense - AI-powered Iron Golem defense system
💰 Dynamic Economy - Living village economy with supply/demand pricing
📋 Quest System - Auto-generated quests based on village needs
⭐ Reputation System - Player reputation affecting village interactions
🎯 Morale Buffs - Dynamic buffs based on reputation levels
🚀 High Performance - Spatial indexing for O(1) lookups (6,100x speedup)

✨ Key Features

🏘️ Village System

Automatic Detection - Villages automatically created when bells are placed
Dynamic Management - Villages expand/contract based on villager count
Spatial Indexing - O(1) bell lookup with 6,100x performance improvement
Multi-World Support - Works across all worlds
Persistent Storage - Automatic village data save/load
Villager Names - Each villager gets a unique, realistic name

💰 Economy System (NEW!)

Dynamic Trading - Supply/demand based pricing that changes in real-time
Quest Generation - Auto-generated quests based on village needs
Reputation Economics - 6-tier reputation system with price modifiers
Multi-Village Economy - Each village maintains independent economy
Price Calculation - Advanced formula: basePrice × (demand/(supply+1)) × reputationMultiplier
Trade History - Complete transaction tracking and analytics

� Quest System (NEW!)

Auto-Generated - Villages create quests based on current needs
Dynamic Rewards - Rewards scale with item rarity and urgency
Quest Types: Delivery, Harvest, Combat, and Building quests
Deadline System - Time-limited quests for urgency
Progress Tracking - Real-time quest progress monitoring

�️ Defense System

Smart Golem Spawning - Automatic Iron Golem spawning when villages are attacked
Multi-Stage Defense - Alert → Defense → Counter-attack phases
Door Management - Automatic door closure during village attacks
Particle Effects - Visual indicators for village status
Sound Alerts - Bell sounds when villages are in danger

⭐ Reputation System

Dynamic Tracking - Player actions affect village reputation
6 Tiers: Despised, Disliked, Neutral, Liked, Respected, Honored
Price Modifiers: Up to 50% discount for honored players
Hostile Detection - Players with low reputation are marked as hostile
Morale Buffs - High reputation players receive speed/regeneration buffs
Decay System - Reputation decays over time

🚀 Performance Features

Thread-Safe Design - Multi-threaded with synchronized collections
Memory Efficient - UUID references instead of Player/Block objects
Optimized Caching - Smart caching with expiration
Spatial Indexing - O(1) bell lookup instead of O(n³)
Minimal Overhead - < 5% performance impact from thread safety

🛠️ Installation

📦 Requirements

Java 21+ - Required for modern features
Spigot/Paper 1.21+ - Compatible with latest Minecraft
Memory: 512MB minimum (recommended: 1GB+)

🚀 Setup Instructions

Download - VillageAI-2.0.0.jar
Place - Copy to plugins/ folder
Restart - Restart server
Configure - Edit plugins/VillageAI/config.yml (optional)
Economy Config - Customize plugins/VillageAI/economy_config.yml

⚙️ Configuration

# VillageAI Configuration File
village:
  # Village detection radius (blocks)
  detection_radius: 32
  
  # Maximum villagers per village
  max_villagers: 10
  
  # Defense settings
  defense:
    # Enable Iron Golem spawning
    enable_golems: true
    
    # Golems per 10 villagers
    golem_ratio: 1
    
    # Alert to defense delay (ms)
    alert_to_defense_delay: 10000
    
    # Bell sound cooldown (ms)
    bell_sound_cooldown: 15000
    
    # Enable particle effects
    enable_particles: true
  
  # Reputation system
  reputation:
    # Hostile threshold
    hostile_threshold: -30
    
    # Enable reputation decay
    enable_decay: true
    
    # Decay rate (reputation per hour)
    decay_rate: 1
  
  # Performance optimization
  performance:
    # Door cache duration (ms)
    door_cache_duration: 10000
    
    # Player cache duration (ms)
    player_cache_duration: 5000

# Economy System Configuration
economy:
  enabled: true
  update_interval: 24000  # Update every 24 hours (game time)
  
  # Price settings
  price_caps:
    min_price: 1          # Minimum price per item (emeralds)
    max_price: 1000       # Maximum price per item (emeralds)
  
  # Trade settings
  trade:
    max_quantity: 64      # Maximum quantity per trade offer
    offer_timeout: 86400000 # Trade offers expire after 24 hours
    
  # Quest settings
  quests:
    enabled: true
    generation_interval: 86400000  # Generate new quests every 24 hours
    max_quests_per_village: 5     # Maximum active quests per village
    default_deadline_days: 3     # Default quest deadline in days
    
  # Reputation settings
  reputation:
    enabled: true
    levels:
      despised: -50
      disliked: -25
      neutral: 0
      liked: 25
      respected: 50
      honored: 100
    
    multipliers:
      despised: 1.5      # 50% markup
      disliked: 1.3      # 30% markup
      neutral: 1.0       # Normal price
      liked: 0.85        # 15% discount
      respected: 0.7     # 30% discount
      honored: 0.5       # 50% discount

# Debug settings
debug:
  # Enable debug logging
  enabled: false
  
  # Log level (INFO, WARN, DEBUG)
  level: INFO

🎮 Usage

🏘️ Creating Villages

Place Bell - Place bell anywhere
Village Forms - Village automatically created with 16x16 area
Add Villagers - Villagers in area automatically added with unique names
Visual Confirmation - Particle effects indicate village creation

� Village Economy

Check Trade Offers - /vtrade trade to see current village offers
Dynamic Pricing - Prices change based on village supply/demand
Build Reputation - Complete quests and trade for better prices
Quest System - /vtrade quests to see available village quests
Reputation Benefits - Higher reputation = better prices and access

Economy Commands

/vtrade trade [material] [quantity]  # Trade with village
/vtrade quests                       # Show available quests
/vtrade accept <quest_id>           # Accept a quest
/vtrade reputation                   # Check your reputation
/vtrade prices [material]           # Check current prices
/vtrade villagers                   # Show villager names and info

📋 Quest System

Auto-Generation - Villages create quests based on needs
Quest Types:
- Delivery: Bring items to village
- Harvest: Collect resources
- Combat: Defeat threats
- Building: Supply construction materials
Dynamic Rewards - Rewards scale with difficulty and urgency
Reputation Gains - +5 reputation per completed quest

�️ Village Defense

Attack Detection - Village detects hostile players nearby
Alert Phase - Bell sounds, particles, villager panic
Defense Phase - Iron Golems spawn and attack hostile players
Door Security - All doors automatically closed
Counter-Attack - Golems actively hunt hostile players

⭐ Building Reputation

Positive Actions:
- Trading with villagers (+1 reputation)
- Completing quests (+5 reputation)
- Protecting village (+10 reputation)
- Healing villagers (+3 reputation)
- Donating iron/gold (+15 reputation)
Negative Actions:
- Attacking villagers (-20 reputation)
- Stealing from village (-15 reputation)
- Breaking village blocks (-10 reputation)
- Killing Iron Golems (-25 reputation)

🎯 Reputation Benefits

Despised (-50): 50% markup on all trades
Disliked (-25): 30% markup on all trades
Neutral (0): Standard prices
Liked (+25): 15% discount on all trades
Respected (+50): 30% discount on all trades
Honored (+100): 50% discount on all trades + exclusive items

👥 Villager Names

Unique Identities: Each villager gets a realistic name (John Smith, Mary Johnson)
Profession-Based: Some villagers get profession suffixes ("James Williams the Blacksmith")
Persistent: Names stay consistent across server restarts
Statistics: /vtrade villagers shows village demographics

🔧 Commands

📋 Player Commands

/village info - Display current village information
/village reputation - Check your reputation
/village list - List all villages in world

/vtrade trade [material] [quantity]  # Trade with village
/vtrade quests                       # Show available quests
/vtrade accept <quest_id>           # Accept a quest
/vtrade reputation                   # Check your reputation
/vtrade prices [material]           # Check current prices
/vtrade villagers                   # Show villager names and info

🛡️ Admin Commands

/village reload - Reload configuration
/village debug <on|off> - Toggle debug mode
/village stats - Display performance statistics
/village cleanup - Force cleanup invalid villages

📊 Performance

⚡ Optimization Features

Spatial Indexing: O(1) bell lookup (6,100x faster)
Smart Caching: Player/door caching with expiration
Thread Safety: Synchronized collections for concurrent access
Memory Management: UUID references instead of object references
Efficient Algorithms: Optimized distance calculations

📈 Benchmarks

Operation	Before	After	Improvement
Bell Lookup	O(n³) = 54,925	O(9)	6,100x faster
Village Detection	200ms	15ms	13x faster
Memory Usage	50MB	30MB	40% reduction
CPU Usage	8%	3%	62% reduction

🛡️ Security & Stability

🔒 Thread Safety

Synchronized Collections: All collections are thread-safe
Race Condition Prevention: No more ConcurrentModificationException
Memory Leak Prevention: Proper cleanup and reference management
Concurrent Access: Safe multi-threaded operations

🚨 Error Handling

Graceful Degradation: Plugin continues working if errors occur
Comprehensive Logging: Detailed error reporting with stack traces
Validation: Input validation for all operations
Recovery: Automatic recovery from transient errors

🔄 API & Integration

🔌 Developer API

// Village Manager API
VillageManager manager = VillageAIPlugin.getInstance().getVillageManager();

// Get village by location
Village village = manager.getVillageAt(location);

// Get player reputation
int reputation = village.getReputation(playerId);

// Check if player is hostile
boolean isHostile = village.isHostile(playerId);

// Get all villages
Collection<Village> villages = manager.getAllVillages();

🔗 Plugin Integration

WorldGuard: Compatible with region protection
GriefPrevention: Works with anti-grief plugins
Economy: Can integrate with economy plugins
Chat: Hooks into chat systems for reputation display

🐛 Troubleshooting

⚠️ Common Issues

Villages Not Forming

Cause: No bells in area
Solution: Place bells and ensure villagers are nearby
Command: /village debug on to check detection

Golems Not Spawning

Cause: Village not in defense mode
Solution: Ensure hostile players are nearby
Check: /village info to see Village State

High Memory Usage

Cause: Too many villages or large cache
Solution: /village cleanup and reduce detection radius
Config: Reduce door_cache_duration and player_cache_duration

Performance Issues

Cause: Large world with many entities
Solution: Enable spatial indexing optimization
Monitor: /village stats to track performance

🔧 Debug Mode

debug:
  enabled: true
  level: DEBUG

Debug Features:

Village detection logging
Golem spawn tracking
Reputation change logging
Performance metrics
Memory usage monitoring

📝 Changelog

🌟 v2.0.0 (Current Release - MAJOR UPDATE)

✅ NEW: Complete village economy system with dynamic pricing
✅ NEW: Auto-generated quest system based on village needs
✅ NEW: Villager naming system with unique identities
✅ NEW: Advanced reputation-based pricing (6 tiers)
✅ NEW: Multi-village independent economies
✅ NEW: Trade history and transaction tracking
✅ NEW: Comprehensive tab completion system
✅ NEW: Village demographics and statistics
✅ ENHANCED: Updated command system with /vtrade
✅ ENHANCED: Performance optimizations for economy updates
✅ ENHANCED: Thread-safe economy operations
✅ ENHANCED: Comprehensive configuration system

🚀 v1.0.4 (Previous Release)

✅ CRITICAL: Fixed HashSet race conditions causing server crashes
✅ CRITICAL: Fixed unsafe collection iteration in VillageManager
✅ CRITICAL: Fixed bellIndex Set<Location> type issue
✅ HIGH: Fixed Player reference leak preventing garbage collection
✅ HIGH: Fixed Block reference leak preventing chunk unloading
✅ Thread-safe implementation throughout
✅ Memory leak prevention with UUID references
✅ Comprehensive error handling and logging

🔮 Planned Features

🏰 Village Upgrades - Walls, towers, and defense structures
🎯 Advanced AI - Golem pathfinding and tactics
🌍 Multi-Village Politics - Alliance and war systems
📊 Analytics Dashboard - Web interface for village statistics
🔌 Custom Events - API for third-party integration
🏪 Player Shops - Player-owned shops in villages
🚢 Trade Routes - Inter-village trading caravans

📞 Support

🐛 Bug Reports

GitHub Issues: Create Issue
Discord: Join Server
Email: support@duong2012g.dev

💬 Community

Documentation: Wiki
Discussions: GitHub Discussions
Tutorials: YouTube Channel

📄 License

Apache License, Version 2.0

Copyright (c) 2026 Duong2012G

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

🏆 Conclusion

VillageAI 2.0.0 transforms villages from static to dynamic, intelligent ecosystems with:

🛡️ Advanced Defense - AI-powered village protection
💰 Living Economy - Dynamic pricing and quest system
👥 Named Villagers - Unique identities for every villager
⭐ Dynamic Reputation - Player interaction system with real benefits
🚀 High Performance - Optimized for large servers
🔧 Easy Setup - Plug-and-play with comprehensive configuration
🎯 Extensible API - Ready for custom integrations

Transform your Minecraft world with living, breathing villages! 🏘️✨💰

Last Updated: March 4, 2026
Version: 2.0.0