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

# 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> [qty]	villageai.trade	Buy directly via command
/vtrade sell <item> [qty]	villageai.trade	Sell directly via command
/vquest list	villageai.quest	View active quests
/vquest accept <id>	villageai.quest	Accept a quest

---

Permissions

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:

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:

• [Critical] TradeService.executeTrade() validated trades but never transferred items
• [Critical] Double-spend possible via rapid double-click in Trade GUI
• [Medium] getNearestVillage() crashed with IllegalArgumentException on multi-world servers
• [Medium] tradeHistory list grew without bound — memory leak on long-running servers
• [Medium] Quest duplicates generated when 24-hour timer fired with identical quest active
• [Performance] onEntityDeath O(n) village scan replaced with O(1) reverse-lookup map
• [Performance] 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 permitted.