VillageAI

# VillageAI Plugin **Version:** 3.3.2 **API:** Paper 1.21 / Java 21 **Author:** Duong2012G VillageAI transforms vanilla Minecraft villages into living, reactive communities. Villages defend themselves, manage their own supply-and-demand economy, issue quests, and dynamically react to player reputation — all without any external dependencies. --- ## Features | System | Description | |---|---| | **State machine** | Villages cycle through SAFE → ALERT → DEFENDING → NIGHT / RAID automatically | | **Spatial bell index** | O(1) village lookups via ChunkCoord index — no full-scan on chunk events | | **Economy** | Supply/demand pricing with per-player reputation multipliers (−50 % to +50 %) | | **Raids** | Configurable multi-wave raids with mob variety and emerald rewards | | **Upgrades** | WALL · WATCHTOWER · GRANARY · FORGE — each adds tangible gameplay effects | | **Quests** | 24-hour DeliveryQuest cycle with deadlines; reward on villager interaction | | **Trade GUI** | 54-slot chest GUI with live price display and discount/markup indicators | | **Villager names** | Custom name tags per villager showing profession and health | | **Async storage** | Atomic file save (write-temp → rename) with automatic backup | --- ## Installation 1. Ensure you are running **Paper 1.21** (or a compatible fork) with **Java 21**. 2. Drop `VillageAI-3.3.2.jar` into your server's `plugins/` folder. 3. Start (or restart) the server — do **not** use `/reload`. 4. Configuration files are generated in `plugins/VillageAI/` on first run. > **Note:** PlugMan hot-reload is not officially supported. Always use a full server restart when updating the plugin. --- ## Building from Source ```bash # Clone / unzip the source, then: mvn clean package -DskipTests # The shaded jar will be at: target/VillageAI-3.3.2.jar ``` Requirements: Java 21, Maven 3.8+. --- ## Commands | Command | Permission | Description | |---|---|---| | `/villageai info` | `villageai.info` | Show status of the nearest village | | `/villageai list` | `villageai.admin` | List all loaded villages | | `/villageai reload` | `villageai.admin` | Reload config (hot) | | `/villageai debug` | `villageai.admin` | Toggle debug output | | `/villageai raid start` | `villageai.admin` | Force-start a raid | | `/villageai raid stop` | `villageai.admin` | Force-stop a raid | | `/vtrade` | `villageai.trade` | Open trade GUI for the nearest village | | `/vtrade buy <item> ` | `villageai.trade` | Buy directly via command | | `/vtrade sell <item> ` | `villageai.trade` | Sell directly via command | | `/vquest list` | `villageai.quest` | View active quests | | `/vquest accept <id>` | `villageai.quest` | Accept a quest | --- ## Permissions ```yaml villageai.info: true # All players villageai.trade: true # All players villageai.quest: true # All players villageai.admin: op # Operators only ``` --- ## Configuration Overview Key settings in `config.yml`: ```yaml village: check_radius: 64 # Hostile-player detection radius (blocks) door_radius: 8 # Door-scan radius for night/alert tick_interval: 40 # Village tick rate (ticks, default 2 s) defense: max_golems: 2 # Max iron golems per village alert_to_defense_delay: 10000 # ms before spawning golems bell_sound_cooldown: 15000 # ms between bell rings reputation: hostile_threshold: -30 # Rep below this triggers golem targeting interact_reward: 2 # Rep gained per villager right-click damage_penalty: -25 # Rep lost per villager attack raid: max_waves: 5 wave_interval_seconds: 60 reward_per_wave: 64 # Emeralds per completed wave night: enabled: true close_doors_at_night: true ``` --- ## Bug Fixes in 3.3.2 Six bugs were resolved in this release — see (CHANGELOG.md) for full details: - **** `TradeService.executeTrade()` validated trades but never transferred items - **** Double-spend possible via rapid double-click in Trade GUI - **** `getNearestVillage()` crashed with `IllegalArgumentException` on multi-world servers - **** `tradeHistory` list grew without bound — memory leak on long-running servers - **** Quest duplicates generated when 24-hour timer fired with identical quest active - **** `onEntityDeath` O(n) village scan replaced with O(1) reverse-lookup map - **** `closeAllDoors()` block scan replaced with cached door list --- ## Data Storage Village data is saved to `plugins/VillageAI/villages/` as YAML, one file per village. Saves are performed asynchronously using an atomic write pattern (write to `.tmp` → rename to final file) to prevent data corruption on crash. A `.bak` backup of the previous save is kept alongside each file. --- ## License This plugin is provided as-is for educational and server-operator use. Redistribution or resale without permission from the author is not