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

Ensure you are running Paper 1.21 (or a compatible fork) with Java 21.
Drop VillageAI-3.3.2.jar into your server's plugins/ folder.
Start (or restart) the server — do not use /reload.
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.

VillageAI

📖About VillageAI