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

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

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.