---

✨ Features at a Glance

🛡️ Defense	💰 Economy	⚔️ Raids	🏰 Upgrades
Auto Iron Golem spawning	Dynamic supply/demand prices	5 escalating waves	Wall, Watchtower, Granary, Forge
3-stage alert system (Safe → Alert → Defending)	Reputation-based discounts	Pillager to Ravager progression	Material contribution system
Night cycle door locking	Inventory trade GUI	Emerald + reputation rewards	Effects persist across restarts
Bell particles & sounds	Quest generation system	Admin start/stop/status	Unlocks additional quests & bonuses

---

📥 Installation

1. Drop VillageAI-3.0.0.jar into your plugins/ folder
2. Start the server — config auto-generates at plugins/VillageAI/config.yml
3. (Optional) Install PlaceholderAPI for scoreboard support

Requirements: Paper 1.21 · Java 21

---

🔨 Building from Source

git clone https://github.com/Duong2012G/VillageAI
cd VillageAI
mvn clean package
# Output → target/VillageAI-3.0.0.jar

Requirements: Java 21, Maven 3.8+, internet access to download Paper API.

---

📋 Commands

🔑 Admin — /villageai (alias: /vai, /village)

Command	Description
/villageai reload	Reload configuration
/villageai info	Show nearest village details
/villageai list	List all loaded villages
/villageai save	Force save all data immediately

💼 Economy — /vtrade (alias: /vt, /vshop)

Command	Description
/vtrade gui	🖥️ Open the trade inventory GUI
/vtrade trade [item] [qty]	Execute a trade via chat
/vtrade quests	List available quests
/vtrade accept <id>	Accept a quest by full UUID
/vtrade reputation	View your reputation & price tier
/vtrade prices	View current supply/demand prices
/vtrade upgrade [name]	View or contribute to village upgrades
/vtrade villagers	Show villager names & profession stats

⚔️ Raid — /villageraid (alias: /vraid)

Command	Description
/villageraid start	Start a raid at the nearest village
/villageraid stop	Stop an active raid
/villageraid status	Show current wave & mob count

---

🔐 Permissions

Permission	Default	Description
villageai.admin	OP	Access to /villageai and /villageraid
villageai.economy	Everyone	Access to /vtrade commands
villageai.upgrade	Everyone	Contribute materials to upgrades

---

🏰 Village Upgrades

Contribute materials via /vtrade upgrade <name>. Progress is shared across all players and survives server restarts.

Upgrade	💎 Cost	⚡ Effect
🧱 Wall	128 Stone + 16 Iron Ingot	Golems take 20% less damage
🗼 Watchtower	64 Oak Planks + 32 Stone	+32 blocks to detection radius
🌾 Granary	128 Wheat + 32 Oak Planks	+2 bonus quests per cycle
🔥 Forge	64 Iron Ingot + 32 Coal	All trade prices −10%

---

⭐ Reputation System

Reputation is earned through trading, quests and village interactions. It directly affects trade prices and whether golems will attack you.

🏅 Level	Score	💰 Price Modifier
🥇 Honored	≥ 100	−50%
🟢 Respected	≥ 50	−30%
🔵 Liked	≥ 25	−15%
⚪ Neutral	≥ −25	0%
🟡 Disliked	≥ −50	+30%
🔴 Despised	< −50	+50%

How to gain / lose reputation:

Action	Change
🤝 Interact with villager	+2 (5s cooldown)
💰 Complete a trade	+1
✅ Complete a quest	+5 defense · +5 economy
⚔️ Hit a villager	−25
❌ Fail a quest	−2

---

⚔️ Raid Waves

Wave	👹 Mob Types	Count
1	Pillager	3
2	Pillager · Vindicator	4
3	Pillager · Vindicator · Evoker	5
4	Ravager · Pillager · Evoker	5
5+	Ravager · Evoker · Witch	6

🏆 Reward: reward_per_wave × max_waves emeralds + +20 reputation for all nearby defenders

---

📡 PlaceholderAPI

Automatically registered when PlaceholderAPI is installed. No extra configuration needed.

Placeholder	Returns
%villageai_rep%	Your reputation at the nearest village
%villageai_state%	Village state (SAFE / ALERT / DEFENDING / NIGHT / RAID)
%villageai_nearest%	Nearest village ID
%villageai_upgrades%	Number of upgrades unlocked

---

⚙️ Configuration

Key options in plugins/VillageAI/config.yml:

village:
  check_radius: 64          # Radius to scan for hostile players (blocks)
  door_radius: 8            # Radius to close doors during alerts
  tick_interval: 40         # Ticks between village updates (20 ticks = 1s)

defense:
  max_golems: 2             # Max Iron Golems spawned per village
  alert_to_defense_delay: 10000  # ms before golems spawn after alert
  bell_sound_cooldown: 15000     # ms between bell sound alerts

reputation:
  hostile_threshold: -30    # Score at which player is treated as hostile
  damage_penalty: -25       # Reputation lost per villager hit
  interact_reward: 2        # Reputation gained per interaction (5s cooldown)

raid:
  enabled: true
  max_waves: 5
  wave_interval_seconds: 60
  reward_per_wave: 64       # Emeralds rewarded per wave cleared

autosave:
  enabled: true
  interval_minutes: 5       # How often to auto-save village data

---

📜 License

Apache 2.0 License — see LICENSE for details.

---