# VillageAI – Advanced Village Defense & Economy System<\/p>\n
\n
\n
\n<\/p>\n
A comprehensive Minecraft plugin that adds dynamic village defense, economy systems, raid mechanics, and village upgrades to enhance player interaction with villagers.<\/p>\n
—<\/p>\n
## \ud83c\udfaf Features<\/p>\n
### \u2694\ufe0f Dynamic Defense System
\n– **Real-time threat detection** \u2014 Monitors hostile mobs and alerts villages
\n– **Iron Golem spawning** \u2014 Villages spawn golems when under attack
\n– **Reputation-based alerts** \u2014 Alert sensitivity depends on player reputation
\n– **Particle effects** \u2014 Visual feedback for defense status
\n– **Bell notifications** \u2014 Audio alerts with configurable cooldown<\/p>\n
### \ud83c\udfd8\ufe0f Village Management
\n– **Automatic detection** \u2014 Finds villages by beds, doors, and bell location
\n– **State system** \u2014 SAFE, ALERT, NIGHT, RAID states with smooth transitions
\n– **Night mode** \u2014 Doors auto-close at night, better security
\n– **Reputation system** \u2014 Track player relationships dynamically
\n– **Morale buffs** \u2014 Happy villagers give Speed & Regeneration effects<\/p>\n
### \ud83d\uded2 Dynamic Economy ### \ud83c\udff0 Village Upgrades ### \u2694\ufe0f Raid System ### \ud83c\udf19 Night Cycle Mode ### \ud83d\udce1 PlaceholderAPI Support —<\/p>\n ## \ud83d\udce5 Installation<\/p>\n ### Requirements ### Quick Start ### Building from Source —<\/p>\n ## \ud83c\udfae Commands<\/p>\n ### Admin Commands \/villageraid start # Begin raid on nearest village ### Player Commands ### Permissions —<\/p>\n ## \u2699\ufe0f Configuration<\/p>\n ### Main Config (`config.yml`)<\/p>\n #### Village Detection #### Defense Settings #### Reputation System #### Morale Buffs #### Raid System #### Village Upgrades #### Auto Save ### Economy Config (`economy_config.yml`)<\/p>\n Customize village material needs and production:<\/p>\n “`yaml daily_production: —<\/p>\n ## \ud83d\udcca Reputation System<\/p>\n Your reputation affects: ### Reputation Tiers ### Permissions —<\/p>\n ## \u2699\ufe0f Configuration<\/p>\n ### Main Config (`config.yml`)<\/p>\n #### Village Detection #### Defense Settings #### Reputation System #### Morale Buffs #### Raid System #### Village Upgrades #### Auto Save ### Economy Config (`economy_config.yml`)<\/p>\n Customize village material needs and production:<\/p>\n “`yaml daily_production: —<\/p>\n ## \ud83d\udcca Reputation System<\/p>\n Your reputation affects: ### Reputation Tiers 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<\/p>\n","protected":false},"featured_media":166280,"template":"","meta":{"_minecraft_slug":"villageai","_minecraft_project_id":"QkbM4VXn","_minecraft_author":"Duong2012G","_minecraft_license":"MIT","_minecraft_downloads":232,"_minecraft_follows":3,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"villageai.zip","_minecraft_size_bytes":832772,"_minecraft_version_count":13,"_minecraft_updated_at":"2026-05-16T12:27:55.272838Z","_minecraft_date_created":"2026-02-07T06:43:50.538388Z","_minecraft_date_modified":"2026-05-16T10:38:51.202680Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/villageai","_minecraft_icon_attachment_id":166280,"_minecraft_imported_at":"2026-06-09T18:18:05+00:00","_minecraft_import_hash":"bfe605c05273718c7ba5ffa9f14307dd","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[87,124,88,89,866,127,128,129,123],"mod_loader":[130,132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-166279","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-adventure","mod_category-bukkit","mod_category-equipment","mod_category-game-mechanics","mod_category-minigame","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-technology","mod_loader-bukkit","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n– **Supply & demand pricing** \u2014 Material prices fluctuate based on village supply
\n– **Trade reputation bonuses** \u2014 Respected players get discounts (up to 50%)
\n– **Inventory GUI** \u2014 Beautiful 54-slot chest interface for trading
\n– **Text command trades** \u2014 `\/vtrade trade
\n– **Quest generation** \u2014 Delivery quests reward players with emeralds
\n– **Price calculator** \u2014 Sophisticated algorithm balances fairness<\/p>\n
\n– **Wall** \u2014 Costs stone + iron, reduces golem damage by 20%
\n– **Watchtower** \u2014 Costs planks + stone, extends detection radius by 32 blocks
\n– **Granary** \u2014 Costs wheat + planks, generates +2 extra quests
\n– **Forge** \u2014 Costs iron + coal, reduces all trade prices by 10%
\n– **Contribution system** \u2014 Players contribute materials to unlock upgrades
\n– **Persistent upgrades** \u2014 State saves across server restarts<\/p>\n
\n– **5-wave escalation** \u2014 Pillagers \u2192 Vindicators \u2192 Evokers \u2192 Ravagers \u2192 Witches
\n– **Ring-based spawning** \u2014 Mobs appear in circular patterns around village bell
\n– **Dynamic difficulty** \u2014 Wave intensity increases as raid progresses
\n– **Rewards** \u2014 64 emeralds per wave + reputation on complete
\n– **Announcements** \u2014 Alerts all nearby players of raid status
\n– **Admin controls** \u2014 `\/villageraid start | stop | status`<\/p>\n
\n– **Automatic door management** \u2014 Closes doors when sun sets
\n– **Enhanced security** \u2014 Reduced alert thresholds at night
\n– **Realistic behavior** \u2014 Matches vanilla village security<\/p>\n
\nIf PlaceholderAPI is installed, use these placeholders:
\n– `%villageai_rep%` \u2014 Your reputation at nearest village
\n– `%villageai_state%` \u2014 Village state (SAFE\/ALERT\/NIGHT\/RAID)
\n– `%villageai_nearest%` \u2014 Name of nearest village
\n– `%villageai_upgrades%` \u2014 Comma-separated list of completed upgrades<\/p>\n
\n– **Minecraft Server**: 1.21.1 or higher
\n– **Java**: 21 or higher
\n– **Server Type**: Paper, Spigot, or compatible
\n– **Plugins**: None required (PlaceholderAPI optional)<\/p>\n
\n1. Drop `VillageAI-3.3.0.jar` into your `plugins\/` folder
\n2. Start the server \u2014 config auto-generates at `plugins\/VillageAI\/config.yml`
\n3. Restart server to reload configs (first start is safe)
\n4. Ready to use!<\/p>\n
\n“`bash
\ngit clone https:\/\/github.com\/Duong2012G\/VillageAI
\ncd VillageAI
\nmvn clean package
\n# Output \u2192 target\/VillageAI-3.3.0.jar
\n“`<\/p>\n
\n“`
\n\/villageai # Show plugin info
\n\/villageai info # Details of nearest village
\n\/villageai list # List all loaded villages
\n\/villageai save # Force immediate save
\n\/villageai reload # Reload configuration<\/p>\n
\n\/villageraid stop # End current raid
\n\/villageraid status # Check raid status
\n“`<\/p>\n
\n“`
\n\/vtrade gui # Open 54-slot trade GUI
\n\/vtrade trade
\n\/vtrade quests # List available quests
\n\/vtrade accept
\n\/vtrade upgrade # Show upgrade progress
\n\/vtrade upgrade [name] # Contribute to upgrade
\n“`<\/p>\n
\n“`
\nvillageai.admin # Access admin commands
\nvillageai.admin # Access admin & raid commands
\nvillageai.trade # Access trade commands
\nvillageai.quest # Access quest commands
\n“`<\/p>\n
\n“`yaml
\nvillage:
\n check_radius: 64 # Detection range for village center (blocks)
\n door_radius: 8 # Door clustering radius (blocks)
\n tick_interval: 40 # Update frequency (ticks)
\n“`<\/p>\n
\n“`yaml
\ndefense:
\n max_golems: 2 # Max golems per village
\n alert_to_defense_delay: 10000 # Time before spawning golems (ms)
\n bell_sound_cooldown: 15000 # Bell notification cooldown (ms)
\n enable_particles: true # Show particles on alert
\n“`<\/p>\n
\n“`yaml
\nreputation:
\n hostile_threshold: -30 # When villages turn hostile
\n decay_interval: 30000 # Reputation decay tick (ms)
\n passive_gain: true # Gain rep from presence
\n damage_penalty: -25 # Penalty for hitting villager
\n interact_reward: 2 # Reward for right-click
\n“`<\/p>\n
\n“`yaml
\nfeatures:
\n morale_buffs:
\n enabled: true
\n min_reputation: 50 # Reputation needed for buffs
\n speed_amp: 1 # Speed potion level
\n regen_amp: 1 # Regeneration level
\n“`<\/p>\n
\n“`yaml
\nraid:
\n enabled: true
\n min_players_nearby: 1 # Players needed to trigger
\n wave_interval_seconds: 60 # Time between waves
\n max_waves: 5 # Maximum raid waves
\n reward_per_wave: 64 # Emeralds per wave
\n announce_raid: true # Announce to server
\n“`<\/p>\n
\n“`yaml
\nupgrades:
\n enabled: true
\n wall:
\n cost_stone: 128
\n cost_iron_ingot: 16
\n golem_damage_reduction: 0.2
\n watchtower:
\n cost_oak_planks: 64
\n cost_stone: 32
\n detection_radius_bonus: 32
\n granary:
\n cost_wheat: 128
\n cost_oak_planks: 32
\n extra_quests: 2
\n forge:
\n cost_iron_ingot: 64
\n cost_coal: 32
\n trade_price_reduction: 0.1
\n“`<\/p>\n
\n“`yaml
\nautosave:
\n enabled: true
\n interval_minutes: 5 # Save frequency
\n“`<\/p>\n
\nvillage_needs:
\n daily_needs:
\n wheat: 20
\n iron_ingot: 10
\n oak_planks: 32
\n stone: 48<\/p>\n
\n bread: 16
\n oak_planks: 24
\n stone: 32
\n“`<\/p>\n
\n– **Trade prices** (up to 50% discount for honored players)
\n– **Village alerts** (more lenient at higher rep)
\n– **Morale buffs** (required for speed\/regen effects)<\/p>\n
\n| Reputation | Status | Price Multiplier | Buffs |
\n|———–|——–|—————–|——-|
\n| \u2265 100 | Honored | 0.5\u00d7 (50% off) | \u2705 |
\n| \u2265 50 | Respected | 0.7\u00d7 (30% off) | \u2705 |
\n| \u2265 25 | Liked | 0.85\u00d7 (15% off) | \u2705 |
\n| \u2265 -25 | Neutral | 1.0\u00d7 | \u274c |
\n| \u2265 -50 | Disliked | 1.3\u00d7 (30% markup) | \u274c |
\n| < -50 | Despised | 1.5\u00d7 (50% markup) | \u274c |\n\n### Reputation Changes\n- **+20** \u2014 Complete raid\n- **+2** \u2014 Right-click villager\n- **-25** \u2014 Hit villager\n- **-30+** to **-100** \u2014 Accumulate hostile actions\n\n---\n\n## \ud83c\udfd7\ufe0f Village States\n\n| State | Meaning | Behavior |\n|-------|---------|----------|\n| **SAFE** | No threats | Normal operation, morale buffs active |\n| **ALERT** | Hostile mobs nearby | Increased defense readiness, doors close |\n| **NIGHT** | Sun down | Doors auto-close, enhanced security |\n| **RAID** | Active raid | Spawn waves, intense defense |\n\n---\n\n## \ud83d\udcc8 Performance\n\n### Optimization Features\n- **Spatial indexing** \u2014 Bell locations cached by chunk (O(1) lookup)\n- **Async I\/O** \u2014 Village data loads\/saves asynchronously\n- **Atomic saves** \u2014 Backup + temp file + atomic rename\n- **Lazy loading** \u2014 Villagers loaded on demand\n- **Efficient queries** \u2014 Cached village lookups\n\n### Benchmarks (Typical Server)\n- **20 villages**: < 0.5ms per tick overhead\n- **100 players**: Negligible impact\n- **Data save**: < 50ms (async, non-blocking)\n\n---\n\n## \ud83d\udc1b Troubleshooting\n\n### Village not detected\n- Check if village has **bell** (required)\n- Verify **doors** exist within 8 blocks of center\n- Ensure **beds** nearby (helps detection)\n- Check `village.check_radius` in config\n\n### Trades not working\n- Verify player has required items\n- Check economy config is valid YAML\n- Run `\/villageai save` to flush cache\n- Restart server if stuck\n\n### Data loss on restart\n- Check `autosave.enabled: true`\n- Verify `plugins\/VillageAI\/` folder is writable\n- Check server logs for save errors\n- Backup `villages.yml` regularly\n\n### Raids not triggering\n- Verify `raid.enabled: true`\n- Check `raid.min_players_nearby: 1`\n- Ensure village is in loaded chunks\n- Try `\/villageraid start` manually\n\n---\n\n## \ud83d\udcdd Version History\n\n### v3.3.1 (2026-05-16) \u2014 Critical Bug Fixes\n- \ud83d\udd34 Fixed autosave calling `buildVillagesConfig()` on async thread (Bukkit API thread-safety violation)\n- \ud83d\udd34 Fixed `loadVillages()` restoring villages on async thread (`server.getWorld()` must run on main thread)\n- \ud83d\udfe1 Fixed raid reward silently capped at 64 emeralds \u2014 full reward now distributed correctly in multiple stacks\n- \ud83d\udfe1 Fixed `decayReputation(boolean passiveGain)` ignoring its parameter \u2014 positive reputation now decays when `passive_gain: false`\n- \ud83d\udfe1 Fixed `VillageEconomy.analyzeVillageNeeds()` reading `economy_config.yml` from disk on every economy update; config is now cached in memory\n- \ud83d\udfe2 Fixed `openGuis` in `EconomyCommand` using non-thread-safe `HashMap` \u2192 `ConcurrentHashMap`\n\n### v3.3.0 (2026-05-03) \u2014 Bug Fixes & Code Quality\n- \ud83d\udc1b Fixed thread-unsafe `HashMap` in `VillageListener.interactCooldowns` \u2192 `ConcurrentHashMap`\n- \ud83d\udc1b Fixed raid mobs spawning inside walls\/underground (now uses `getHighestBlockYAt()`)\n- \ud83d\udc1b Fixed hardcoded version string in startup log (now reads from `plugin.yml`)\n- \ud83d\udc1b Added missing `villageai.reload` permission node to `plugin.yml`\n- \ud83d\udcdd Fixed stale version reference and wrong permission name in README\n\n### v3.2.0 (2026-04-28) \u2014 Debugging & Permissions\n- \ud83d\udc1b Fixed `ChunkCoord`\/`VillageId` unreadable toString() output\n- \ud83d\udc1b Fixed missing `villageai.trade` and `villageai.quest` permissions\n- \ud83d\udc1b Fixed NPE from null `getUnlockedUpgrades()` in VillageCommand\n- \ud83d\udd27 Clarified time unit documentation in config.yml\n\n### v3.1.0 (2026-04-24) \u2014 Stability & Architecture\n- \ud83d\udc1b Fixed dangerous save command (was calling onDisable + onEnable)\n- \ud83d\udc1b Fixed economy config being ignored\n- \ud83d\ude80 Created TradeService to eliminate code duplication\n- \ud83d\ude80 Config-driven village economy needs\n- \ud83c\udfd7\ufe0f Improved code organization and maintainability\n\n### v3.0.0 (2026-04-12) \u2014 Major Update\n- \u2694\ufe0f Added wave-based raid system\n- \ud83c\udff0 Added village upgrade system\n- \ud83d\uded2 Added inventory trade GUI\n- \ud83c\udf19 Added night cycle mode\n- \ud83d\udce1 Added PlaceholderAPI integration\n- \ud83d\udc1b Fixed multiple critical data loss bugs\n\n### v2.2.0 (2026-03-16) \u2014 Stability\n- Various bug fixes and optimizations\n- Thread safety improvements\n\n### v2.1.1 (2026-03-11) \u2014 Critical Fixes\n- Data persistence fixes\n- Village data loading from root keys\n\n---\n\n## \ud83e\udd1d Contributing\n\nFound a bug or have an idea? \n- \ud83d\udce7 Issues: https:\/\/github.com\/Duong2012G\/VillageAI\/issues\n- \ud83d\udcd8 Wiki: https:\/\/github.com\/Duong2012G\/VillageAI\/wiki\n\n---\n\n## \ud83d\udcdc License\n\nMIT License \u2014 Feel free to use and modify for your servers.\n\n---\n\n## \ud83d\udcac Support\n\nNeed help? Check out:\n- \ud83d\udcd6 Documentation Wiki\n- \ud83d\udc1b Known Issues\n- \ud83d\udcac Discord Community\n\n---\n\n**Made with \u2764\ufe0f for Minecraft servers by the VillageAI team**\n\n*Last updated: 2026-05-03*\n- **Wall** \u2014 Costs stone + iron, reduces golem damage by 20%\n- **Watchtower** \u2014 Costs planks + stone, extends detection radius by 32 blocks\n- **Granary** \u2014 Costs wheat + planks, generates +2 extra quests\n- **Forge** \u2014 Costs iron + coal, reduces all trade prices by 10%\n- **Contribution system** \u2014 Players contribute materials to unlock upgrades\n- **Persistent upgrades** \u2014 State saves across server restarts\n\n### \u2694\ufe0f Raid System\n- **5-wave escalation** \u2014 Pillagers \u2192 Vindicators \u2192 Evokers \u2192 Ravagers \u2192 Witches\n- **Ring-based spawning** \u2014 Mobs appear in circular patterns around village bell\n- **Dynamic difficulty** \u2014 Wave intensity increases as raid progresses\n- **Rewards** \u2014 64 emeralds per wave + reputation on complete\n- **Announcements** \u2014 Alerts all nearby players of raid status\n- **Admin controls** \u2014 `\/villageraid start | stop | status`\n\n### \ud83c\udf19 Night Cycle Mode\n- **Automatic door management** \u2014 Closes doors when sun sets\n- **Enhanced security** \u2014 Reduced alert thresholds at night\n- **Realistic behavior** \u2014 Matches vanilla village security\n\n### \ud83d\udce1 PlaceholderAPI Support\nIf PlaceholderAPI is installed, use these placeholders:\n- `%villageai_rep%` \u2014 Your reputation at nearest village\n- `%villageai_state%` \u2014 Village state (SAFE\/ALERT\/NIGHT\/RAID)\n- `%villageai_nearest%` \u2014 Name of nearest village\n- `%villageai_upgrades%` \u2014 Comma-separated list of completed upgrades\n\n---\n\n## \ud83d\udce5 Installation\n\n### Requirements\n- **Minecraft Server**: 1.21.1 or higher\n- **Java**: 21 or higher\n- **Server Type**: Paper, Spigot, or compatible\n- **Plugins**: None required (PlaceholderAPI optional)\n\n### Quick Start\n1. Drop `VillageAI-3.2.0.jar` into your `plugins\/` folder\n2. Start the server \u2014 config auto-generates at `plugins\/VillageAI\/config.yml`\n3. Restart server to reload configs (first start is safe)\n4. Ready to use!\n\n### Building from Source\n```bash\ngit clone https:\/\/github.com\/Duong2012G\/VillageAI\ncd VillageAI\nmvn clean package\n# Output \u2192 target\/VillageAI-3.1.0.jar\n```\n\n---\n\n## \ud83c\udfae Commands\n\n### Admin Commands\n```\n\/villageai # Show plugin info\n\/villageai info # Details of nearest village\n\/villageai list # List all loaded villages\n\/villageai save # Force immediate save\n\/villageai reload # Reload configuration\n\n\/villageraid start # Begin raid on nearest village\n\/villageraid stop # End current raid\n\/villageraid status # Check raid status\n```\n\n### Player Commands\n```\n\/vtrade gui # Open 54-slot trade GUI\n\/vtrade trade
\n\/vtrade quests # List available quests
\n\/vtrade accept
\n\/vtrade upgrade # Show upgrade progress
\n\/vtrade upgrade [name] # Contribute to upgrade
\n“`<\/p>\n
\n“`
\nvillageai.admin # Access admin commands
\nvillageai.raid # Access raid commands
\nvillageai.trade # Access trade commands
\nvillageai.quest # Access quest commands
\n“`<\/p>\n
\n“`yaml
\nvillage:
\n check_radius: 64 # Detection range for village center (blocks)
\n door_radius: 8 # Door clustering radius (blocks)
\n tick_interval: 40 # Update frequency (ticks)
\n“`<\/p>\n
\n“`yaml
\ndefense:
\n max_golems: 2 # Max golems per village
\n alert_to_defense_delay: 10000 # Time before spawning golems (ms)
\n bell_sound_cooldown: 15000 # Bell notification cooldown (ms)
\n enable_particles: true # Show particles on alert
\n“`<\/p>\n
\n“`yaml
\nreputation:
\n hostile_threshold: -30 # When villages turn hostile
\n decay_interval: 30000 # Reputation decay tick (ms)
\n passive_gain: true # Gain rep from presence
\n damage_penalty: -25 # Penalty for hitting villager
\n interact_reward: 2 # Reward for right-click
\n“`<\/p>\n
\n“`yaml
\nfeatures:
\n morale_buffs:
\n enabled: true
\n min_reputation: 50 # Reputation needed for buffs
\n speed_amp: 1 # Speed potion level
\n regen_amp: 1 # Regeneration level
\n“`<\/p>\n
\n“`yaml
\nraid:
\n enabled: true
\n min_players_nearby: 1 # Players needed to trigger
\n wave_interval_seconds: 60 # Time between waves
\n max_waves: 5 # Maximum raid waves
\n reward_per_wave: 64 # Emeralds per wave
\n announce_raid: true # Announce to server
\n“`<\/p>\n
\n“`yaml
\nupgrades:
\n enabled: true
\n wall:
\n cost_stone: 128
\n cost_iron_ingot: 16
\n golem_damage_reduction: 0.2
\n watchtower:
\n cost_oak_planks: 64
\n cost_stone: 32
\n detection_radius_bonus: 32
\n granary:
\n cost_wheat: 128
\n cost_oak_planks: 32
\n extra_quests: 2
\n forge:
\n cost_iron_ingot: 64
\n cost_coal: 32
\n trade_price_reduction: 0.1
\n“`<\/p>\n
\n“`yaml
\nautosave:
\n enabled: true
\n interval_minutes: 5 # Save frequency
\n“`<\/p>\n
\nvillage_needs:
\n daily_needs:
\n wheat: 20
\n iron_ingot: 10
\n oak_planks: 32
\n stone: 48<\/p>\n
\n bread: 16
\n oak_planks: 24
\n stone: 32
\n“`<\/p>\n
\n– **Trade prices** (up to 50% discount for honored players)
\n– **Village alerts** (more lenient at higher rep)
\n– **Morale buffs** (required for speed\/regen effects)<\/p>\n
\n| Reputation | Status | Price Multiplier | Buffs |
\n|———–|——–|—————–|——-|
\n| \u2265 100 | Honored | 0.5\u00d7 (50% off) | \u2705 |
\n| \u2265 50 | Respected | 0.7\u00d7 (30% off) | \u2705 |
\n| \u2265 25 | Liked | 0.85\u00d7 (15% off) | \u2705 |
\n| \u2265 -25 | Neutral | 1.0\u00d7 | \u274c |
\n| \u2265 -50 | Disliked | 1.3\u00d7 (30% markup) | \u274c |
\n| < -50 | Despised | 1.5\u00d7 (50% markup) | \u274c |\n\n### Reputation Changes\n- **+20** \u2014 Complete raid\n- **+2** \u2014 Right-click villager\n- **-25** \u2014 Hit villager\n- **-30+** to **-100** \u2014 Accumulate hostile actions\n\n---\n\n## \ud83c\udfd7\ufe0f Village States\n\n| State | Meaning | Behavior |\n|-------|---------|----------|\n| **SAFE** | No threats | Normal operation, morale buffs active |\n| **ALERT** | Hostile mobs nearby | Increased defense readiness, doors close |\n| **NIGHT** | Sun down | Doors auto-close, enhanced security |\n| **RAID** | Active raid | Spawn waves, intense defense |\n\n---\n\n## \ud83d\udcc8 Performance\n\n### Optimization Features\n- **Spatial indexing** \u2014 Bell locations cached by chunk (O(1) lookup)\n- **Async I\/O** \u2014 Village data loads\/saves asynchronously\n- **Atomic saves** \u2014 Backup + temp file + atomic rename\n- **Lazy loading** \u2014 Villagers loaded on demand\n- **Efficient queries** \u2014 Cached village lookups\n\n### Benchmarks (Typical Server)\n- **20 villages**: < 0.5ms per tick overhead\n- **100 players**: Negligible impact\n- **Data save**: < 50ms (async, non-blocking)\n\n---\n\n## \ud83d\udc1b Troubleshooting\n\n### Village not detected\n- Check if village has **bell** (required)\n- Verify **doors** exist within 8 blocks of center\n- Ensure **beds** nearby (helps detection)\n- Check `village.check_radius` in config\n\n### Trades not working\n- Verify player has required items\n- Check economy config is valid YAML\n- Run `\/villageai save` to flush cache\n- Restart server if stuck\n\n### Data loss on restart\n- Check `autosave.enabled: true`\n- Verify `plugins\/VillageAI\/` folder is writable\n- Check server logs for save errors\n- Backup `villages.yml` regularly\n\n### Raids not triggering\n- Verify `raid.enabled: true`\n- Check `raid.min_players_nearby: 1`\n- Ensure village is in loaded chunks\n- Try `\/villageraid start` manually\n\n---\n\n## \ud83d\udcdd Version History\n\n### v3.1.0 (2026-04-24) \u2014 Stability & Architecture\n- \ud83d\udc1b Fixed dangerous save command (was calling onDisable + onEnable)\n- \ud83d\udc1b Fixed economy config being ignored\n- \ud83d\ude80 Created TradeService to eliminate code duplication\n- \ud83d\ude80 Config-driven village economy needs\n- \ud83c\udfd7\ufe0f Improved code organization and maintainability\n\n### v3.0.0 (2026-04-12) \u2014 Major Update\n- \u2694\ufe0f Added wave-based raid system\n- \ud83c\udff0 Added village upgrade system\n- \ud83d\uded2 Added inventory trade GUI\n- \ud83c\udf19 Added night cycle mode\n- \ud83d\udce1 Added PlaceholderAPI integration\n- \ud83d\udc1b Fixed multiple critical data loss bugs\n\n### v2.2.0 (2026-03-16) \u2014 Stability\n- Various bug fixes and optimizations\n- Thread safety improvements\n\n### v2.1.1 (2026-03-11) \u2014 Critical Fixes\n- Data persistence fixes\n- Village data loading from root keys\n\n---\n\n## \ud83e\udd1d Contributing\n\nFound a bug or have an idea? \n- \ud83d\udce7 Issues: https:\/\/github.com\/Duong2012G\/VillageAI\/issues\n- \ud83d\udcd8 Wiki: https:\/\/github.com\/Duong2012G\/VillageAI\/wiki\n\n---\n\n## \ud83d\udcdc License\n\nMIT License \u2014 Feel free to use and modify for your servers.\n\n---\n\n## \ud83d\udcac Support\n\nNeed help? Check out:\n- \ud83d\udcd6 Documentation Wiki\n- \ud83d\udc1b Known Issues\n- \ud83d\udcac Discord Community\n\n---\n\n**Made with \u2764\ufe0f for Minecraft servers by the VillageAI team**\n\n*Last updated: 2026-04-24*\n\n<\/p>\n","protected":false},"excerpt":{"rendered":"