VillageAI - Advanced Village Defense & Economy System

A comprehensive Minecraft plugin that adds dynamic village defense, economy systems, raid mechanics, and village upgrades to enhance player interaction with villagers.

🎯 Features

⚔️ Dynamic Defense System

Real-time threat detection — Monitors hostile mobs and alerts villages
Iron Golem spawning — Villages spawn golems when under attack
Reputation-based alerts — Alert sensitivity depends on player reputation
Particle effects — Visual feedback for defense status
Bell notifications — Audio alerts with configurable cooldown

🏘️ Village Management

Automatic detection — Finds villages by beds, doors, and bell location
State system — SAFE, ALERT, NIGHT, RAID states with smooth transitions
Night mode — Doors auto-close at night, better security
Reputation system — Track player relationships dynamically
Morale buffs — Happy villagers give Speed & Regeneration effects

🛒 Dynamic Economy

Supply & demand pricing — Material prices fluctuate based on village supply
Trade reputation bonuses — Respected players get discounts (up to 50%)
Inventory GUI — Beautiful 54-slot chest interface for trading
Text command trades — /vtrade trade <material> <quantity>
Quest generation — Delivery quests reward players with emeralds
Price calculator — Sophisticated algorithm balances fairness

🏰 Village Upgrades

Wall — Costs stone + iron, reduces golem damage by 20%
Watchtower — Costs planks + stone, extends detection radius by 32 blocks
Granary — Costs wheat + planks, generates +2 extra quests
Forge — Costs iron + coal, reduces all trade prices by 10%
Contribution system — Players contribute materials to unlock upgrades
Persistent upgrades — State saves across server restarts

⚔️ Raid System

5-wave escalation — Pillagers → Vindicators → Evokers → Ravagers → Witches
Ring-based spawning — Mobs appear in circular patterns around village bell
Dynamic difficulty — Wave intensity increases as raid progresses
Rewards — 64 emeralds per wave + reputation on complete
Announcements — Alerts all nearby players of raid status
Admin controls — /villageraid start | stop | status

🌙 Night Cycle Mode

Automatic door management — Closes doors when sun sets
Enhanced security — Reduced alert thresholds at night
Realistic behavior — Matches vanilla village security

📡 PlaceholderAPI Support

If PlaceholderAPI is installed, use these placeholders:

%villageai_rep% — Your reputation at nearest village
%villageai_state% — Village state (SAFE/ALERT/NIGHT/RAID)
%villageai_nearest% — Name of nearest village
%villageai_upgrades% — Comma-separated list of completed upgrades

📥 Installation

Requirements

Minecraft Server: 1.21.1 or higher
Java: 21 or higher
Server Type: Paper, Spigot, or compatible
Plugins: None required (PlaceholderAPI optional)

Quick Start

Drop VillageAI-3.2.0.jar into your plugins/ folder
Start the server — config auto-generates at plugins/VillageAI/config.yml
Restart server to reload configs (first start is safe)
Ready to use!

Building from Source

git clone https://github.com/Duong2012G/VillageAI
cd VillageAI
mvn clean package
# Output → target/VillageAI-3.1.0.jar

🎮 Commands

Admin Commands

/villageai                              # Show plugin info
/villageai info                         # Details of nearest village
/villageai list                         # List all loaded villages
/villageai save                         # Force immediate save
/villageai reload                       # Reload configuration

/villageraid start                      # Begin raid on nearest village
/villageraid stop                       # End current raid
/villageraid status                     # Check raid status

Player Commands

/vtrade gui                             # Open 54-slot trade GUI
/vtrade trade <material> <qty>          # Trade via command
/vtrade quests                          # List available quests
/vtrade accept <quest-uuid>             # Accept delivery quest
/vtrade upgrade                         # Show upgrade progress
/vtrade upgrade [name]                  # Contribute to upgrade

Permissions

villageai.admin                         # Access admin commands
villageai.raid                          # Access raid commands
villageai.trade                         # Access trade commands
villageai.quest                         # Access quest commands

⚙️ Configuration

Main Config (`config.yml`)

Village Detection

village:
  check_radius: 64              # Detection range for village center (blocks)
  door_radius: 8                # Door clustering radius (blocks)
  tick_interval: 40             # Update frequency (ticks)

Defense Settings

defense:
  max_golems: 2                 # Max golems per village
  alert_to_defense_delay: 10000 # Time before spawning golems (ms)
  bell_sound_cooldown: 15000    # Bell notification cooldown (ms)
  enable_particles: true        # Show particles on alert

Reputation System

reputation:
  hostile_threshold: -30        # When villages turn hostile
  decay_interval: 30000         # Reputation decay tick (ms)
  passive_gain: true            # Gain rep from presence
  damage_penalty: -25           # Penalty for hitting villager
  interact_reward: 2            # Reward for right-click

Morale Buffs

features:
  morale_buffs:
    enabled: true
    min_reputation: 50          # Reputation needed for buffs
    speed_amp: 1                # Speed potion level
    regen_amp: 1                # Regeneration level

Raid System

raid:
  enabled: true
  min_players_nearby: 1         # Players needed to trigger
  wave_interval_seconds: 60     # Time between waves
  max_waves: 5                  # Maximum raid waves
  reward_per_wave: 64           # Emeralds per wave
  announce_raid: true           # Announce to server

Village Upgrades

upgrades:
  enabled: true
  wall:
    cost_stone: 128
    cost_iron_ingot: 16
    golem_damage_reduction: 0.2
  watchtower:
    cost_oak_planks: 64
    cost_stone: 32
    detection_radius_bonus: 32
  granary:
    cost_wheat: 128
    cost_oak_planks: 32
    extra_quests: 2
  forge:
    cost_iron_ingot: 64
    cost_coal: 32
    trade_price_reduction: 0.1

Auto Save

autosave:
  enabled: true
  interval_minutes: 5           # Save frequency

Economy Config (`economy_config.yml`)

Customize village material needs and production:

village_needs:
  daily_needs:
    wheat: 20
    iron_ingot: 10
    oak_planks: 32
    stone: 48
  
  daily_production:
    bread: 16
    oak_planks: 24
    stone: 32

📊 Reputation System

Your reputation affects:

Trade prices (up to 50% discount for honored players)
Village alerts (more lenient at higher rep)
Morale buffs (required for speed/regen effects)

Reputation Tiers

Reputation	Status	Price Multiplier	Buffs
≥ 100	Honored	0.5× (50% off)	✅
≥ 50	Respected	0.7× (30% off)	✅
≥ 25	Liked	0.85× (15% off)	✅
≥ -25	Neutral	1.0×	❌
≥ -50	Disliked	1.3× (30% markup)	❌
< -50	Despised	1.5× (50% markup)	❌

Reputation Changes

+20 — Complete raid
+2 — Right-click villager
-25 — Hit villager
-30+ to -100 — Accumulate hostile actions

🏗️ Village States

State	Meaning	Behavior
SAFE	No threats	Normal operation, morale buffs active
ALERT	Hostile mobs nearby	Increased defense readiness, doors close
NIGHT	Sun down	Doors auto-close, enhanced security
RAID	Active raid	Spawn waves, intense defense

📈 Performance

Optimization Features

Spatial indexing — Bell locations cached by chunk (O(1) lookup)
Async I/O — Village data loads/saves asynchronously
Atomic saves — Backup + temp file + atomic rename
Lazy loading — Villagers loaded on demand
Efficient queries — Cached village lookups

Benchmarks (Typical Server)

20 villages: < 0.5ms per tick overhead
100 players: Negligible impact
Data save: < 50ms (async, non-blocking)

🐛 Troubleshooting

Village not detected

Check if village has bell (required)
Verify doors exist within 8 blocks of center
Ensure beds nearby (helps detection)
Check village.check_radius in config

Trades not working

Verify player has required items
Check economy config is valid YAML
Run /villageai save to flush cache
Restart server if stuck

Data loss on restart

Check autosave.enabled: true
Verify plugins/VillageAI/ folder is writable
Check server logs for save errors
Backup villages.yml regularly

Raids not triggering

Verify raid.enabled: true
Check raid.min_players_nearby: 1
Ensure village is in loaded chunks
Try /villageraid start manually

📝 Version History

v3.1.0 (2026-04-24) — Stability & Architecture

🐛 Fixed dangerous save command (was calling onDisable + onEnable)
🐛 Fixed economy config being ignored
🚀 Created TradeService to eliminate code duplication
🚀 Config-driven village economy needs
🏗️ Improved code organization and maintainability

v3.0.0 (2026-04-12) — Major Update

⚔️ Added wave-based raid system
🏰 Added village upgrade system
🛒 Added inventory trade GUI
🌙 Added night cycle mode
📡 Added PlaceholderAPI integration
🐛 Fixed multiple critical data loss bugs

v2.2.0 (2026-03-16) — Stability

Various bug fixes and optimizations
Thread safety improvements

v2.1.1 (2026-03-11) — Critical Fixes

Data persistence fixes
Village data loading from root keys

🤝 Contributing

Found a bug or have an idea?

📧 Issues: https://github.com/Duong2012G/VillageAI/issues
📘 Wiki: https://github.com/Duong2012G/VillageAI/wiki

📜 License

MIT License — Feel free to use and modify for your servers.

💬 Support

Need help? Check out:

Made with ❤️ for Minecraft servers by the VillageAI team

Last updated: 2026-04-24

VillageAI