?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacksServers
Settings
VillageAI

VillageAI

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

276
3
276
3

Compatibility

Minecraft: Java Edition

1.21.x

Platforms

Tags

Creators

Details

Licensed MIT
Published 4 months ago

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.