VillageAI
Intelligent village defense system. Villages centered on bells automatically detect nearby villagers. Friendly players gain reputation by trading. Hostile players lose reputation by attacking villagers. When hostile players are nearby reputation drops belo
232
Quick challenge
How far can you run before the mobs catch you?
Minecraft check
Confirm your run
Complete the quick check to get your code.
VillageAI
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
- Bell notifications — Monitors hostile mobs and alerts villages - Bell notifications — Villages spawn golems when under attack - Bell notifications — Alert sensitivity depends on player reputation - Bell notifications — Visual feedback for defense status - Bell notifications — Audio alerts with configurable cooldown
🏘️ Village Management
- Morale buffs — Finds villages by beds, doors, and bell location - Morale buffs — SAFE, ALERT, NIGHT, RAID states with smooth transitions - Morale buffs — Doors auto-close at night, better security - Morale buffs — Track player relationships dynamically - Morale buffs — Happy villagers give Speed & Regeneration effects
🛒 Dynamic Economy
- Price calculator — Material prices fluctuate based on village supply - Price calculator — Respected players get discounts (up to 50%) - Price calculator — Beautiful 54-slot chest interface for trading - Price calculator — `/vtrade trade <material> <quantity>` - Price calculator — Delivery quests reward players with emeralds - Price calculator — Sophisticated algorithm balances fairness
🏰 Village Upgrades
- Persistent upgrades — Costs stone + iron, reduces golem damage by 20% - Persistent upgrades — Costs planks + stone, extends detection radius by 32 blocks - Persistent upgrades — Costs wheat + planks, generates +2 extra quests - Persistent upgrades — Costs iron + coal, reduces all trade prices by 10% - Persistent upgrades — Players contribute materials to unlock upgrades - Persistent upgrades — State saves across server restarts
⚔️ Raid System
- Admin controls — Pillagers → Vindicators → Evokers → Ravagers → Witches - Admin controls — Mobs appear in circular patterns around village bell - Admin controls — Wave intensity increases as raid progresses - Admin controls — 64 emeralds per wave + reputation on complete - Admin controls — Alerts all nearby players of raid status - Admin controls — `/villageraid start | stop | status`
🌙 Night Cycle Mode
- Realistic behavior — Closes doors when sun sets - Realistic behavior — 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
- Plugins: 1.21.1 or higher - Plugins: 21 or higher - Plugins: Paper, Spigot, or compatible - Plugins: None required (PlaceholderAPI optional)
Quick Start
1. Drop `VillageAI-3.3.0.jar` into your `plugins/` folder 2. Start the server — config auto-generates at `plugins/VillageAI/config.yml` 3. Restart server to reload configs (first start is safe) 4. Ready to use!
Building from Source
```bash git clone https://github.com/Duong2012G/VillageAI cd VillageAI mvn clean package
Output → target/VillageAI-3.3.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.admin # Access admin & raid commands villageai.trade # Access trade commands villageai.quest # Access quest commands ```
---
⚙️ Configuration
Main Config (`config.yml`)
Village Detection
```yaml 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
```yaml 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
```yaml 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
```yaml 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
```yaml 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
```yaml 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
```yaml autosave: enabled: true interval_minutes: 5 # Save frequency ```
Economy Config (`economy_config.yml`)
Customize village material needs and production:
```yaml 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: - Morale buffs (up to 50% discount for honored players) - Morale buffs (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
- -100 — Complete raid - -100 — Right-click villager - -100 — Hit villager - -100 to -100 — Accumulate hostile actions
---
🏗️ Village States
| State | Meaning | Behavior | |-------|---------|----------| | RAID | No threats | Normal operation, morale buffs active | | RAID | Hostile mobs nearby | Increased defense readiness, doors close | | RAID | Sun down | Doors auto-close, enhanced security | | RAID | Active raid | Spawn waves, intense defense |
---
📈 Performance
Optimization Features
- Efficient queries — Bell locations cached by chunk (O(1) lookup) - Efficient queries — Village data loads/saves asynchronously - Efficient queries — Backup + temp file + atomic rename - Efficient queries — Villagers loaded on demand - Efficient queries — Cached village lookups
Benchmarks (Typical Server)
- Data save: < 0.5ms per tick overhead - Data save: Negligible impact - Data save: < 50ms (async, non-blocking)
---
🐛 Troubleshooting
Village not detected
- Check if village has beds (required) - Verify beds 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.3.1 (2026-05-16) — Critical Bug Fixes
- 🔴 Fixed autosave calling `buildVillagesConfig()` on async thread (Bukkit API thread-safety violation) - 🔴 Fixed `loadVillages()` restoring villages on async thread (`server.getWorld()` must run on main thread) - 🟡 Fixed raid reward silently capped at 64 emeralds — full reward now distributed correctly in multiple stacks - 🟡 Fixed `decayReputation(boolean passiveGain)` ignoring its parameter — positive reputation now decays when `passive_gain: false` - 🟡 Fixed `VillageEconomy.analyzeVillageNeeds()` reading `economy_config.yml` from disk on every economy update; config is now cached in memory - 🟢 Fixed `openGuis` in `EconomyCommand` using non-thread-safe `HashMap` → `ConcurrentHashMap`
v3.3.0 (2026-05-03) — Bug Fixes & Code Quality
- 🐛 Fixed thread-unsafe `HashMap` in `VillageListener.interactCooldowns` → `ConcurrentHashMap` - 🐛 Fixed raid mobs spawning inside walls/underground (now uses `getHighestBlockYAt()`) - 🐛 Fixed hardcoded version string in startup log (now reads from `plugin.yml`) - 🐛 Added missing `villageai.reload` permission node to `plugin.yml` - 📝 Fixed stale version reference and wrong permission name in README
v3.2.0 (2026-04-28) — Debugging & Permissions
- 🐛 Fixed `ChunkCoord`/`VillageId` unreadable toString() output - 🐛 Fixed missing `villageai.trade` and `villageai.quest` permissions - 🐛 Fixed NPE from null `getUnlockedUpgrades()` in VillageCommand - 🔧 Clarified time unit documentation in config.yml
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: - 📖 Documentation Wiki - 🐛 Known Issues - 💬 Discord Community
---
Made with ❤️ for Minecraft servers by the VillageAI team
*Last updated: 2026-05-03* - Persistent upgrades — Costs stone + iron, reduces golem damage by 20% - Persistent upgrades — Costs planks + stone, extends detection radius by 32 blocks - Persistent upgrades — Costs wheat + planks, generates +2 extra quests - Persistent upgrades — Costs iron + coal, reduces all trade prices by 10% - Persistent upgrades — Players contribute materials to unlock upgrades - Persistent upgrades — State saves across server restarts
⚔️ Raid System
- Admin controls — Pillagers → Vindicators → Evokers → Ravagers → Witches - Admin controls — Mobs appear in circular patterns around village bell - Admin controls — Wave intensity increases as raid progresses - Admin controls — 64 emeralds per wave + reputation on complete - Admin controls — Alerts all nearby players of raid status - Admin controls — `/villageraid start | stop | status`
🌙 Night Cycle Mode
- Realistic behavior — Closes doors when sun sets - Realistic behavior — 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
- Plugins: 1.21.1 or higher - Plugins: 21 or higher - Plugins: Paper, Spigot, or compatible - Plugins: None required (PlaceholderAPI optional)
Quick Start
1. Drop `VillageAI-3.2.0.jar` into your `plugins/` folder 2. Start the server — config auto-generates at `plugins/VillageAI/config.yml` 3. Restart server to reload configs (first start is safe) 4. Ready to use!
Building from Source
```bash 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
```yaml 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
```yaml 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
```yaml 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
```yaml 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
```yaml 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
```yaml 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
```yaml autosave: enabled: true interval_minutes: 5 # Save frequency ```
Economy Config (`economy_config.yml`)
Customize village material needs and production:
```yaml 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: - Morale buffs (up to 50% discount for honored players) - Morale buffs (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
- -100 — Complete raid - -100 — Right-click villager - -100 — Hit villager - -100 to -100 — Accumulate hostile actions
---
🏗️ Village States
| State | Meaning | Behavior | |-------|---------|----------| | RAID | No threats | Normal operation, morale buffs active | | RAID | Hostile mobs nearby | Increased defense readiness, doors close | | RAID | Sun down | Doors auto-close, enhanced security | | RAID | Active raid | Spawn waves, intense defense |
---
📈 Performance
Optimization Features
- Efficient queries — Bell locations cached by chunk (O(1) lookup) - Efficient queries — Village data loads/saves asynchronously - Efficient queries — Backup + temp file + atomic rename - Efficient queries — Villagers loaded on demand - Efficient queries — Cached village lookups
Benchmarks (Typical Server)
- Data save: < 0.5ms per tick overhead - Data save: Negligible impact - Data save: < 50ms (async, non-blocking)
---
🐛 Troubleshooting
Village not detected
- Check if village has beds (required) - Verify beds 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: - 📖 Documentation Wiki - 🐛 Known Issues - 💬 Discord Community
---
Made with ❤️ for Minecraft servers by the VillageAI team
*Last updated: 2026-04-24*
