VillageAI

# VillageAI – Advanced Village Defense & Economy System


A comprehensive Minecraft plugin that adds dynamic village defense, economy systems, raid mechanics, and village upgrades to enhance player interaction with villagers.

—

## 🎯 Features

### ⚔️ Dynamic Defense System
– **Real-time threat detection** — Monitors hostile mobs and alerts villages
– **Iron Golem spawning** — Villages spawn golems when under attack
– **Reputation-based alerts** — Alert sensitivity depends on player reputation
– **Particle effects** — Visual feedback for defense status
– **Bell notifications** — Audio alerts with configurable cooldown

### 🏘️ Village Management
– **Automatic detection** — Finds villages by beds, doors, and bell location
– **State system** — SAFE, ALERT, NIGHT, RAID states with smooth transitions
– **Night mode** — Doors auto-close at night, better security
– **Reputation system** — Track player relationships dynamically
– **Morale buffs** — Happy villagers give Speed & Regeneration effects

### 🛒 Dynamic Economy
– **Supply & demand pricing** — Material prices fluctuate based on village supply
– **Trade reputation bonuses** — Respected players get discounts (up to 50%)
– **Inventory GUI** — Beautiful 54-slot chest interface for trading
– **Text command trades** — `/vtrade trade `
– **Quest generation** — Delivery quests reward players with emeralds
– **Price calculator** — Sophisticated algorithm balances fairness

### 🏰 Village Upgrades
– **Wall** — Costs stone + iron, reduces golem damage by 20%
– **Watchtower** — Costs planks + stone, extends detection radius by 32 blocks
– **Granary** — Costs wheat + planks, generates +2 extra quests
– **Forge** — Costs iron + coal, reduces all trade prices by 10%
– **Contribution system** — Players contribute materials to unlock upgrades
– **Persistent upgrades** — State saves across server restarts

### ⚔️ Raid System
– **5-wave escalation** — Pillagers → Vindicators → Evokers → Ravagers → Witches
– **Ring-based spawning** — Mobs appear in circular patterns around village bell
– **Dynamic difficulty** — Wave intensity increases as raid progresses
– **Rewards** — 64 emeralds per wave + reputation on complete
– **Announcements** — Alerts all nearby players of raid status
– **Admin controls** — `/villageraid start | stop | status`

### 🌙 Night Cycle Mode
– **Automatic door management** — Closes doors when sun sets
– **Enhanced security** — Reduced alert thresholds at night
– **Realistic behavior** — Matches vanilla village security

### 📡 PlaceholderAPI Support
If PlaceholderAPI is installed, use these placeholders:
– `%villageai_rep%` — Your reputation at nearest village
– `%villageai_state%` — Village state (SAFE/ALERT/NIGHT/RAID)
– `%villageai_nearest%` — Name of nearest village
– `%villageai_upgrades%` — Comma-separated list of completed upgrades

—

## 📥 Installation

### Requirements
– **Minecraft Server**: 1.21.1 or higher
– **Java**: 21 or higher
– **Server Type**: Paper, Spigot, or compatible
– **Plugins**: None required (PlaceholderAPI optional)

### Quick Start
1. Drop `VillageAI-3.3.0.jar` into your `plugins/` folder
2. Start the server — config auto-generates at `plugins/VillageAI/config.yml`
3. Restart server to reload configs (first start is safe)
4. Ready to use!

### Building from Source
“`bash
git clone https://github.com/Duong2012G/VillageAI
cd VillageAI
mvn clean package
# Output → target/VillageAI-3.3.0.jar
“`

—

## 🎮 Commands

### Admin Commands
“`
/villageai # Show plugin info
/villageai info # Details of nearest village
/villageai list # List all loaded villages
/villageai save # Force immediate save
/villageai reload # Reload configuration

/villageraid start # Begin raid on nearest village
/villageraid stop # End current raid
/villageraid status # Check raid status
“`

### Player Commands
“`
/vtrade gui # Open 54-slot trade GUI
/vtrade trade # Trade via command
/vtrade quests # List available quests
/vtrade accept # Accept delivery quest
/vtrade upgrade # Show upgrade progress
/vtrade upgrade [name] # Contribute to upgrade
“`

### Permissions
“`
villageai.admin # Access admin commands
villageai.admin # Access admin & raid commands
villageai.trade # Access trade commands
villageai.quest # Access quest commands
“`

—

## ⚙️ Configuration

### Main Config (`config.yml`)

#### Village Detection
“`yaml
village:
check_radius: 64 # Detection range for village center (blocks)
door_radius: 8 # Door clustering radius (blocks)
tick_interval: 40 # Update frequency (ticks)
“`

#### Defense Settings
“`yaml
defense:
max_golems: 2 # Max golems per village
alert_to_defense_delay: 10000 # Time before spawning golems (ms)
bell_sound_cooldown: 15000 # Bell notification cooldown (ms)
enable_particles: true # Show particles on alert
“`

#### Reputation System
“`yaml
reputation:
hostile_threshold: -30 # When villages turn hostile
decay_interval: 30000 # Reputation decay tick (ms)
passive_gain: true # Gain rep from presence
damage_penalty: -25 # Penalty for hitting villager
interact_reward: 2 # Reward for right-click
“`

#### Morale Buffs
“`yaml
features:
morale_buffs:
enabled: true
min_reputation: 50 # Reputation needed for buffs
speed_amp: 1 # Speed potion level
regen_amp: 1 # Regeneration level
“`

#### Raid System
“`yaml
raid:
enabled: true
min_players_nearby: 1 # Players needed to trigger
wave_interval_seconds: 60 # Time between waves
max_waves: 5 # Maximum raid waves
reward_per_wave: 64 # Emeralds per wave
announce_raid: true # Announce to server
“`

#### Village Upgrades
“`yaml
upgrades:
enabled: true
wall:
cost_stone: 128
cost_iron_ingot: 16
golem_damage_reduction: 0.2
watchtower:
cost_oak_planks: 64
cost_stone: 32
detection_radius_bonus: 32
granary:
cost_wheat: 128
cost_oak_planks: 32
extra_quests: 2
forge:
cost_iron_ingot: 64
cost_coal: 32
trade_price_reduction: 0.1
“`

#### Auto Save
“`yaml
autosave:
enabled: true
interval_minutes: 5 # Save frequency
“`

### Economy Config (`economy_config.yml`)

Customize village material needs and production:

“`yaml
village_needs:
daily_needs:
wheat: 20
iron_ingot: 10
oak_planks: 32
stone: 48

daily_production:
bread: 16
oak_planks: 24
stone: 32
“`

—

## 📊 Reputation System

Your reputation affects:
– **Trade prices** (up to 50% discount for honored players)
– **Village alerts** (more lenient at higher rep)
– **Morale buffs** (required for speed/regen effects)

### Reputation Tiers
| Reputation | Status | Price Multiplier | Buffs |
|———–|——–|—————–|——-|
| ≥ 100 | Honored | 0.5× (50% off) | ✅ |
| ≥ 50 | Respected | 0.7× (30% off) | ✅ |
| ≥ 25 | Liked | 0.85× (15% off) | ✅ |
| ≥ -25 | Neutral | 1.0× | ❌ |
| ≥ -50 | Disliked | 1.3× (30% markup) | ❌ |
| < -50 | Despised | 1.5× (50% markup) | ❌ | ### Reputation Changes - **+20** — Complete raid - **+2** — Right-click villager - **-25** — Hit villager - **-30+** to **-100** — Accumulate hostile actions --- ## 🏗️ Village States | State | Meaning | Behavior | |-------|---------|----------| | **SAFE** | No threats | Normal operation, morale buffs active | | **ALERT** | Hostile mobs nearby | Increased defense readiness, doors close | | **NIGHT** | Sun down | Doors auto-close, enhanced security | | **RAID** | Active raid | Spawn waves, intense defense | --- ## 📈 Performance ### Optimization Features - **Spatial indexing** — Bell locations cached by chunk (O(1) lookup) - **Async I/O** — Village data loads/saves asynchronously - **Atomic saves** — Backup + temp file + atomic rename - **Lazy loading** — Villagers loaded on demand - **Efficient queries** — Cached village lookups ### Benchmarks (Typical Server) - **20 villages**: < 0.5ms per tick overhead - **100 players**: Negligible impact - **Data save**: < 50ms (async, non-blocking) --- ## 🐛 Troubleshooting ### Village not detected - Check if village has **bell** (required) - Verify **doors** exist within 8 blocks of center - Ensure **beds** nearby (helps detection) - Check `village.check_radius` in config ### Trades not working - Verify player has required items - Check economy config is valid YAML - Run `/villageai save` to flush cache - Restart server if stuck ### Data loss on restart - Check `autosave.enabled: true` - Verify `plugins/VillageAI/` folder is writable - Check server logs for save errors - Backup `villages.yml` regularly ### Raids not triggering - Verify `raid.enabled: true` - Check `raid.min_players_nearby: 1` - Ensure village is in loaded chunks - Try `/villageraid start` manually --- ## 📝 Version History ### v3.3.1 (2026-05-16) — Critical Bug Fixes - 🔴 Fixed autosave calling `buildVillagesConfig()` on async thread (Bukkit API thread-safety violation) - 🔴 Fixed `loadVillages()` restoring villages on async thread (`server.getWorld()` must run on main thread) - 🟡 Fixed raid reward silently capped at 64 emeralds — full reward now distributed correctly in multiple stacks - 🟡 Fixed `decayReputation(boolean passiveGain)` ignoring its parameter — positive reputation now decays when `passive_gain: false` - 🟡 Fixed `VillageEconomy.analyzeVillageNeeds()` reading `economy_config.yml` from disk on every economy update; config is now cached in memory - 🟢 Fixed `openGuis` in `EconomyCommand` using non-thread-safe `HashMap` → `ConcurrentHashMap` ### v3.3.0 (2026-05-03) — Bug Fixes & Code Quality - 🐛 Fixed thread-unsafe `HashMap` in `VillageListener.interactCooldowns` → `ConcurrentHashMap` - 🐛 Fixed raid mobs spawning inside walls/underground (now uses `getHighestBlockYAt()`) - 🐛 Fixed hardcoded version string in startup log (now reads from `plugin.yml`) - 🐛 Added missing `villageai.reload` permission node to `plugin.yml` - 📝 Fixed stale version reference and wrong permission name in README ### v3.2.0 (2026-04-28) — Debugging & Permissions - 🐛 Fixed `ChunkCoord`/`VillageId` unreadable toString() output - 🐛 Fixed missing `villageai.trade` and `villageai.quest` permissions - 🐛 Fixed NPE from null `getUnlockedUpgrades()` in VillageCommand - 🔧 Clarified time unit documentation in config.yml ### v3.1.0 (2026-04-24) — Stability & Architecture - 🐛 Fixed dangerous save command (was calling onDisable + onEnable) - 🐛 Fixed economy config being ignored - 🚀 Created TradeService to eliminate code duplication - 🚀 Config-driven village economy needs - 🏗️ Improved code organization and maintainability ### v3.0.0 (2026-04-12) — Major Update - ⚔️ Added wave-based raid system - 🏰 Added village upgrade system - 🛒 Added inventory trade GUI - 🌙 Added night cycle mode - 📡 Added PlaceholderAPI integration - 🐛 Fixed multiple critical data loss bugs ### v2.2.0 (2026-03-16) — Stability - Various bug fixes and optimizations - Thread safety improvements ### v2.1.1 (2026-03-11) — Critical Fixes - Data persistence fixes - Village data loading from root keys --- ## 🤝 Contributing Found a bug or have an idea? - 📧 Issues: https://github.com/Duong2012G/VillageAI/issues - 📘 Wiki: https://github.com/Duong2012G/VillageAI/wiki --- ## 📜 License MIT License — Feel free to use and modify for your servers. --- ## 💬 Support Need help? Check out: - 📖 [Documentation Wiki](https://github.com/Duong2012G/VillageAI/wiki) - 🐛 [Known Issues](https://github.com/Duong2012G/VillageAI/issues) - 💬 [Discord Community](https://discord.gg/example) --- **Made with ❤️ for Minecraft servers by the VillageAI team** *Last updated: 2026-05-03* - **Wall** — Costs stone + iron, reduces golem damage by 20% - **Watchtower** — Costs planks + stone, extends detection radius by 32 blocks - **Granary** — Costs wheat + planks, generates +2 extra quests - **Forge** — Costs iron + coal, reduces all trade prices by 10% - **Contribution system** — Players contribute materials to unlock upgrades - **Persistent upgrades** — State saves across server restarts ### ⚔️ Raid System - **5-wave escalation** — Pillagers → Vindicators → Evokers → Ravagers → Witches - **Ring-based spawning** — Mobs appear in circular patterns around village bell - **Dynamic difficulty** — Wave intensity increases as raid progresses - **Rewards** — 64 emeralds per wave + reputation on complete - **Announcements** — Alerts all nearby players of raid status - **Admin controls** — `/villageraid start | stop | status` ### 🌙 Night Cycle Mode - **Automatic door management** — Closes doors when sun sets - **Enhanced security** — Reduced alert thresholds at night - **Realistic behavior** — Matches vanilla village security ### 📡 PlaceholderAPI Support If PlaceholderAPI is installed, use these placeholders: - `%villageai_rep%` — Your reputation at nearest village - `%villageai_state%` — Village state (SAFE/ALERT/NIGHT/RAID) - `%villageai_nearest%` — Name of nearest village - `%villageai_upgrades%` — Comma-separated list of completed upgrades --- ## 📥 Installation ### Requirements - **Minecraft Server**: 1.21.1 or higher - **Java**: 21 or higher - **Server Type**: Paper, Spigot, or compatible - **Plugins**: None required (PlaceholderAPI optional) ### Quick Start 1. Drop `VillageAI-3.2.0.jar` into your `plugins/` folder 2. Start the server — config auto-generates at `plugins/VillageAI/config.yml` 3. Restart server to reload configs (first start is safe) 4. Ready to use! ### Building from Source ```bash git clone https://github.com/Duong2012G/VillageAI cd VillageAI mvn clean package # Output → target/VillageAI-3.1.0.jar ``` --- ## 🎮 Commands ### Admin Commands ``` /villageai # Show plugin info /villageai info # Details of nearest village /villageai list # List all loaded villages /villageai save # Force immediate save /villageai reload # Reload configuration /villageraid start # Begin raid on nearest village /villageraid stop # End current raid /villageraid status # Check raid status ``` ### Player Commands ``` /vtrade gui # Open 54-slot trade GUI /vtrade trade # Trade via command
/vtrade quests # List available quests
/vtrade accept # Accept delivery quest
/vtrade upgrade # Show upgrade progress
/vtrade upgrade [name] # Contribute to upgrade
“`

### Permissions
“`
villageai.admin # Access admin commands
villageai.raid # Access raid commands
villageai.trade # Access trade commands
villageai.quest # Access quest commands
“`

—

## ⚙️ Configuration

### Main Config (`config.yml`)

#### Village Detection
“`yaml
village:
check_radius: 64 # Detection range for village center (blocks)
door_radius: 8 # Door clustering radius (blocks)
tick_interval: 40 # Update frequency (ticks)
“`

#### Defense Settings
“`yaml
defense:
max_golems: 2 # Max golems per village
alert_to_defense_delay: 10000 # Time before spawning golems (ms)
bell_sound_cooldown: 15000 # Bell notification cooldown (ms)
enable_particles: true # Show particles on alert
“`

#### Reputation System
“`yaml
reputation:
hostile_threshold: -30 # When villages turn hostile
decay_interval: 30000 # Reputation decay tick (ms)
passive_gain: true # Gain rep from presence
damage_penalty: -25 # Penalty for hitting villager
interact_reward: 2 # Reward for right-click
“`

#### Morale Buffs
“`yaml
features:
morale_buffs:
enabled: true
min_reputation: 50 # Reputation needed for buffs
speed_amp: 1 # Speed potion level
regen_amp: 1 # Regeneration level
“`

#### Raid System
“`yaml
raid:
enabled: true
min_players_nearby: 1 # Players needed to trigger
wave_interval_seconds: 60 # Time between waves
max_waves: 5 # Maximum raid waves
reward_per_wave: 64 # Emeralds per wave
announce_raid: true # Announce to server
“`

#### Village Upgrades
“`yaml
upgrades:
enabled: true
wall:
cost_stone: 128
cost_iron_ingot: 16
golem_damage_reduction: 0.2
watchtower:
cost_oak_planks: 64
cost_stone: 32
detection_radius_bonus: 32
granary:
cost_wheat: 128
cost_oak_planks: 32
extra_quests: 2
forge:
cost_iron_ingot: 64
cost_coal: 32
trade_price_reduction: 0.1
“`

#### Auto Save
“`yaml
autosave:
enabled: true
interval_minutes: 5 # Save frequency
“`

### Economy Config (`economy_config.yml`)

Customize village material needs and production:

“`yaml
village_needs:
daily_needs:
wheat: 20
iron_ingot: 10
oak_planks: 32
stone: 48

daily_production:
bread: 16
oak_planks: 24
stone: 32
“`

—

## 📊 Reputation System

Your reputation affects:
– **Trade prices** (up to 50% discount for honored players)
– **Village alerts** (more lenient at higher rep)
– **Morale buffs** (required for speed/regen effects)

### Reputation Tiers
| Reputation | Status | Price Multiplier | Buffs |
|———–|——–|—————–|——-|
| ≥ 100 | Honored | 0.5× (50% off) | ✅ |
| ≥ 50 | Respected | 0.7× (30% off) | ✅ |
| ≥ 25 | Liked | 0.85× (15% off) | ✅ |
| ≥ -25 | Neutral | 1.0× | ❌ |
| ≥ -50 | Disliked | 1.3× (30% markup) | ❌ |
| < -50 | Despised | 1.5× (50% markup) | ❌ | ### Reputation Changes - **+20** — Complete raid - **+2** — Right-click villager - **-25** — Hit villager - **-30+** to **-100** — Accumulate hostile actions --- ## 🏗️ Village States | State | Meaning | Behavior | |-------|---------|----------| | **SAFE** | No threats | Normal operation, morale buffs active | | **ALERT** | Hostile mobs nearby | Increased defense readiness, doors close | | **NIGHT** | Sun down | Doors auto-close, enhanced security | | **RAID** | Active raid | Spawn waves, intense defense | --- ## 📈 Performance ### Optimization Features - **Spatial indexing** — Bell locations cached by chunk (O(1) lookup) - **Async I/O** — Village data loads/saves asynchronously - **Atomic saves** — Backup + temp file + atomic rename - **Lazy loading** — Villagers loaded on demand - **Efficient queries** — Cached village lookups ### Benchmarks (Typical Server) - **20 villages**: < 0.5ms per tick overhead - **100 players**: Negligible impact - **Data save**: < 50ms (async, non-blocking) --- ## 🐛 Troubleshooting ### Village not detected - Check if village has **bell** (required) - Verify **doors** exist within 8 blocks of center - Ensure **beds** nearby (helps detection) - Check `village.check_radius` in config ### Trades not working - Verify player has required items - Check economy config is valid YAML - Run `/villageai save` to flush cache - Restart server if stuck ### Data loss on restart - Check `autosave.enabled: true` - Verify `plugins/VillageAI/` folder is writable - Check server logs for save errors - Backup `villages.yml` regularly ### Raids not triggering - Verify `raid.enabled: true` - Check `raid.min_players_nearby: 1` - Ensure village is in loaded chunks - Try `/villageraid start` manually --- ## 📝 Version History ### v3.1.0 (2026-04-24) — Stability & Architecture - 🐛 Fixed dangerous save command (was calling onDisable + onEnable) - 🐛 Fixed economy config being ignored - 🚀 Created TradeService to eliminate code duplication - 🚀 Config-driven village economy needs - 🏗️ Improved code organization and maintainability ### v3.0.0 (2026-04-12) — Major Update - ⚔️ Added wave-based raid system - 🏰 Added village upgrade system - 🛒 Added inventory trade GUI - 🌙 Added night cycle mode - 📡 Added PlaceholderAPI integration - 🐛 Fixed multiple critical data loss bugs ### v2.2.0 (2026-03-16) — Stability - Various bug fixes and optimizations - Thread safety improvements ### v2.1.1 (2026-03-11) — Critical Fixes - Data persistence fixes - Village data loading from root keys --- ## 🤝 Contributing Found a bug or have an idea? - 📧 Issues: https://github.com/Duong2012G/VillageAI/issues - 📘 Wiki: https://github.com/Duong2012G/VillageAI/wiki --- ## 📜 License MIT License — Feel free to use and modify for your servers. --- ## 💬 Support Need help? Check out: - 📖 [Documentation Wiki](https://github.com/Duong2012G/VillageAI/wiki) - 🐛 [Known Issues](https://github.com/Duong2012G/VillageAI/issues) - 💬 [Discord Community](https://discord.gg/example) --- **Made with ❤️ for Minecraft servers by the VillageAI team** *Last updated: 2026-04-24*

Viiru Advancements Pack

#  CallMeViiru’s Advancements pack

This datapack adds **20+ new advancements** to your game!

This pack was inspired by BlazeandCaves advancement pack.

Add this datapack to your world not in your mods folder!

Made by CallMeViiru / ViiruTech on YouTube

VexBot – PvP Against Bots

Vex Bot 1.5 – Descrption

PvP Methods ⚔️

– Sword
– Axe
– Sheild
– Crossbow & Bow
– Cobweb (Toggleable)
– Potions
– TnT Minecart PvP (Toggleable)
– Crystal PvP
– Anchor PvP
– Wind Charge Macing
– Elytra mace
– Spear Mace

Techniques 🔨
– Crit Chaining
– Combing
– Sweeping Hit
– W Tapping

Pathfinding & Ai 🎯

– Avoids Obstacles (Lava, Powderd Snow, etc)
– Allways Takes the best route
– Revenge Mode
– Follow Mode
– Priority Targeting (Preffers Low Hp/Eating targets)
– Auto Targeting (Configurable)

Difficulty System ⚖️

– Easy → Medium → Hard → Expert → Perfect
– Changes Reaction Time, Combo Chance, etc

Teams Features 👥

– Team System (Groups bots together)
– Each Team has there own indivdivdual settings
– Per-Team target lists (teams target specific people or multiple people)

Settings & GUI ⚙️

– In-game GUI — configure all bot settings without commands
– Per-team settings GUI with full toggles – Cart mode selector cycling through all 5 modes
– Settings auto-save per world — survive server restarts

Custom Potion 🧪

– Refills the kit that the potion is linked to. (By right Clicking)

Issue Tracker

https://vex-log-keeper.lovable.app

How to use

VexBot — How to Use check the tutorials at

(https://vex-log-keeper.lovable.app/tutorials)

Settings GUI

/vexbot settings — opens the main settings menu where you configure:

Difficulty — Easy / Medium / Hard / Expert / Perfect (controls reaction
speed, crits, combos)
– Auto Target — bot automatically finds and attacks nearby players
– Target Players / Bots / Mobs — what the bot will attack
– Revenge Mode — bot attacks whoever hits it
– Ignore Creative — skip creative mode players
– Use Elytra Mace — enable aerial elytra+mace drop combo
– Use Ender Pearl — bot throws ender pearl to escape when low HP

Kits (Inventory Loadouts)

1. Put the gear you want in your own inventory
2. /vexbot createkit — saves your current inventory as a kit
3. /vexbot givekit — opens GUI to give a kit to a bot
4. /vexbot deletekit — delete a saved kit
5. /vexbot kiticon — set a display icon for a kit in the menu

Teams

1. /vexbot createteam — create a team and assign bots to it via GUI
2. /vexbot teamsettings — set who the team targets (all players,
specific players, etc.)
3. /vexbot teamgivekit — give a kit to every bot in a team at once

Follow Mode

/vexbot follow — bot follows a player without attacking

/vexbot follow stop — stops following

Quick Start (Fighting Bot)

1. /vexbot spawn — spawn a bot
2. Give it gear: /vexbot givekit (or manually give items)
3. /vexbot settings → enable Auto Target + Target Players
4. Set Difficulty to your preference
5. The bot will start fighting automatically

VerseChests

# Verse Chests Plugin Description

The **Verse Chests Plugin** is a performance-optimized and feature-packed solution for adding customizable loot chests to your Minecraft PvP server. It enhances gameplay by introducing dynamic chests scattered across the map, offering unique loot and fostering competitive exploration.

## Features:
– **Dynamic Loot Chests**: Automatically spawn loot-filled chests across the map to encourage exploration and PvP engagement.
– **Custom Chest Creation**: Easily create chests by placing specific blocks on the ground, making setup quick and intuitive.
– **Advanced Loot Configuration**:
– Customize loot tables directly from configuration files or through in-game commands.
– Set item rarities and precise drop chances for balanced and rewarding gameplay.
– **Rarity & Drop Control**: Configure item rarity levels (e.g., Rare, Epic, Mythic, Legendary) and adjust probabilities for fine-tuned loot distribution.
– **Command Support**: Manage chest contents, rarity levels, and drop chances conveniently with commands.
– **Optimized Performance**: Verified for minimal server load, as proven by **Spark Profiler** testing (see screenshot below), ensuring smooth performance even on high-traffic servers.

## Benefits:
– Encourage exploration and competitiveness by offering randomized loot rewards across the map.
– Simplify chest creation and loot management with user-friendly tools and commands.
– Maintain server performance without compromising features or functionality, as verified by Spark Profiler results showing negligible impact on server threads.

—

## Spark Profiler Screenshot

The **Verse Chests Plugin** is ideal for servers aiming to create an exciting, loot-driven PvP environment with seamless customization and performance efficiency.

VerifyMC-Proxy

VerifyMC-Proxy is a companion plugin for VerifyMC that runs on your BungeeCord/Waterfall or Velocity proxy server. It intercepts player logins and verifies whitelist status via the VerifyMC backend API before allowing players to connect to your backend servers.

Features:
– Support for both BungeeCord/Waterfall and Velocity
– Real-time whitelist verification via HTTP API
– Customizable kick messages
– Multi-language support (English/Chinese)
– Auto-update configuration from remote

VelKoth

## 🚀 Features

– **Modern Architecture**: Compiled against Paper 1.21+ using Java 21, **Folia-supported Regional/Entity Schedulers**, and the Incendo Cloud V2 native Brigadier command framework.
– **Multiple Capture Modes**:
– `CAPTURE`: Traditional KoTH where one player must hold the hill uninterrupted for the duration.
– `SCORE`: Point-based KoTH where players accumulate capture seconds until they reach the target score.
– **High Performance Regions**: Both Cuboid and Cylinder regions utilise O(1) containment algorithms removing loop-based block checks for zero server TPS impact.
– **Team Plugin Integrations**: Fully supports team and faction capturing! Players in the same team, faction, or party can capture hills together without contesting. Supports 12+ plugins natively.
– **Advanced Display Visuals**: Leverages modern Paper Adventure API to push ActionBars, custom BossBars, on-screen Titles, Particle effects, and Sounds. Includes **FastBoard-powered Scoreboards** (with smart-overrides for plugins like TAB and SimpleScore) and native **Paper TextDisplay Holograms** that are fully chunk-safe.
– **Robust Storage System**: Fully asynchronous SQLite/MySQL HikariCP connection pooling storing player total wins, daily wins, and weekly wins.
– **bStats Metrics Integration**: Uses anonymous metrics tracking to keep developers informed on adoption rates and usage.
– **Scheduler Integration**: Define exactly when specific arenas should run via Cron-like syntax or simple time formats. Now supports **Dynamic Scheduling** via in-game commands.
– **Dynamic Configuration**: Built on Okaeri Configs for instant YAML hot-reloading. Every system message, GUI layout, and internal setting can be modified.
– **Comprehensive Rewards**: Execute commands, distribute ItemStacks (with overflow drop handling), or give Vault Economy money to the winners.
– **Enhanced PlaceholderAPI**: Comprehensive support for multi-arena events, absolute/specific next event countdowns, and human-readable time formatting.
– **Developer API**: Features a full suite of Bukkit Events (`KothStartEvent`, `KothWinEvent`, `KothCaptureStartEvent`, etc.) and a static `VelKothAPI` state accessor for developers.

—

## ⚙️ Dependencies

– **PaperMC** 1.21.x+
– **Java 21**
– [Vault](https://www.spigotmc.org/resources/vault.34315/) *(Optional – Required for Economy rewards)*
– [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) *(Optional – Exposes extensive placeholders)*
– `%koth_arena[_]%`, `%koth_time[_formatted][_]%`
– `%koth_owner[_]%`, `%koth_players[_]%`
– `%koth_next_arena[_]%`, `%koth_next_time[_formatted][_]%`
– **Supported Team Plugins** *(Optional – Allows team members to capture together)*
– BetterTeams, Factions (UUID/Saber), GangsPlus, Guilds, KingdomsX
– SuperiorSkyblock2, Towny Advanced, UltimateClans, Parties, AxParties
– LandClaimPlugin (Custom hook)

—

## 🛠️ Usage & Setup

### Creating an Arena

1. Grab the KoTH Wand by typing `/koth wand`.
2. Left-Click one corner of your hill, and Right-Click the opposite corner.
3. Type `/koth create ` to save the region.
4. Modify specific rules, timers, and rewards for this arena in the generated `plugins/VelKoth/arenas.yml` configuration!

### Administering Events

– Start an event manually: `/koth start `
– Pause an ongoing event (maintaining times/scores): `/koth pause `
– Stop an event completely: `/koth stop `
– Configure automatic daily/weekly events in `plugins/VelKoth/config.yml`.

—

## 🪧 Commands

VelKoth features a robust, auto-completing Brigadier command hierarchy.

| Command | Permission | Description |
| :— | :— | :— |
| `/koth help` | `velkoth.use` | View available commands |
| `/koth stats` | `velkoth.use` | View your personal KoTH wins (Daily/Weekly/All-time) |
| `/koth next ` | `velkoth.use` | See when is the next Koth gonna start |
| `/koth list` | `velkoth.admin` | View all arenas and their current status |
| `/koth wand` | `velkoth.admin` | Receive the region selection wand |
| `/koth create ` | `velkoth.admin` | Create a new arena from your wand selection |
| `/koth delete ` | `velkoth.admin` | Permanently delete an arena |
| `/koth start ` | `velkoth.admin` | Force start an arena immediately |
| `/koth pause ` | `velkoth.admin` | Pause an active capture session |
| `/koth resume ` | `velkoth.admin` | Resume a paused capture session |
| `/koth stop ` | `velkoth.admin` | Stop an active arena prematurely |
| `/koth schedule add ` | `velkoth.admin` | Add a new event to the automated schedule |
| `/koth schedule list` | `velkoth.admin` | View all currently scheduled events |
| `/koth schedule remove ` | `velkoth.admin` | Remove a scheduled event by its list index |
| `/koth set mode ` | `velkoth.admin` | Change the win condition (Hold timer or Cumulative points) |
| `/koth set time ` | `velkoth.admin` | Set the required capture time |
| `/koth set score ` | `velkoth.admin` | Set the target score for SCORE mode |
| `/koth set grace ` | `velkoth.admin` | Set the grace period before capture resets |
| `/koth reward add ` | `velkoth.admin` | Add a new win reward (supports Commands, Economy, Items) |
| `/koth reward list ` | `velkoth.admin` | View all configured rewards for an arena in detail |
| `/koth reward remove ` | `velkoth.admin` | Remove a specific reward by index |
| `/koth reward clear ` | `velkoth.admin` | Clear all rewards for an arena |
| `/koth reload` | `velkoth.admin` | Hot-reload all `.yml` configuration files |

—

## 🎁 Rewards

VelKoth supports a powerful reward system that can be managed entirely in-game or via `arenas.yml`. Rewards are granted to the winning player (or all online members of a team/faction if team hooks are active).

### Supported Reward Types

| Type | Format | Example |
| :— | :— | :— |
| **Command** | `COMMAND:` or `` | `COMMAND:give %player% netherite_ingot 1` |
| **Economy** | `ECONOMY:` | `ECONOMY:1000` (Requires Vault) |
| **Item** | `ITEM:[:]` | `ITEM:GOLD_BLOCK:3` |

### Reward Placeholders
* `%player%`: Name of the winner.
* `%arena%`: ID of the arena.

### Viewing Rewards
You can see exactly what rewards are configured for an arena using:
` /koth reward list `
This will display a numbered list of rewards with human-readable descriptions (e.g., *Command: give diamond 1*).

—

## 📜 Permissions

– **`velkoth.use`**: Default permission granted to all players allowing them to view help and check their personal statistics.
– **`velkoth.admin`**: Default OP permission granting full administrative access to edit arenas, bypass timers, and trigger events.

—

## 📦 Building from Source

To compile the standalone shadow JAR natively (including the Cloud command libraries and Okaeri configs):

“`bash
git clone https://github.com/YourName/VelKoth.git
cd VelKoth
./gradlew clean shadowJar
“`

Your compiled plugin will be deposited in `/build/libs/`.

VaultCrates

# VaultCrates

**A feature-rich, fully animated crate plugin for Paper 1.21.x**

No NMS · No legacy libraries · No external hologram plugin required

—

## ✨ Features

– **12 unique animations** — particles, sounds and visual effects for every style
– **Physical & Virtual Keys** — NBT-tagged items with anti-dupe UUID tracking
– **Pity system** — guaranteed drop after N opens per rarity
– **Reward limits** — global and per-player caps per reward
– **Key shop** — players buy keys with in-game money via `/vc shop`
– **Pouches** — right-clickable reward bags with random number ranges
– **Holograms** — floating Text Display entities, no external plugin needed
– **Placement ID system** — each placed crate gets a unique ID (`/vc remove `)
– **In-game GUI editor** — edit crates without touching YAML files
– **Reward preview** — paginated GUI with normalised drop percentages
– **Best Prizes** — guaranteed bonus reward from a separate pool
– **Bundled items** — give multiple items alongside the main reward
– **Selectable rewards** — players pick their prize from N options
– **Milestones** — bonus rewards after X total crate opens
– **Reward footer** — auto-appended lore showing reward type and rarity
– **NPC support** — Citizens, ZNPCs, ZNPCsPlus, FancyNpcs, or any entity
– **Multi-language** — English, German, French, Spanish built-in + custom locale support
– **Multi-database** — JSON (default), SQLite or MySQL
– **Developer API** — events, programmatic crate opening, key management

—

## 📋 Requirements

– **Paper** (or forks) 1.21 – 1.21.4+
– **Java 21+**

### Optional soft-dependencies
All are fully optional and loaded via reflection:

– **Vault** + economy plugin — key shop & economy commands
– **PlaceholderAPI** — placeholders in messages & holograms
– **ItemsAdder / Oraxen / Nexo** — custom block & item models
– **ExecutableItems / MMOItems** — custom items as rewards
– **Citizens / ZNPCs / ZNPCsPlus / FancyNpcs** — NPC-to-crate linking

—

## 🚀 Quick Start

1. Drop the JAR into `plugins/`
2. Restart the server
3. `/vc getcrate ExampleRound` — get a crate block
4. Place it in the world
5. `/vc key give ExampleRound 1` — give yourself a key
6. Right-click the crate!

—

## 🎬 Animations

| Name | Style |
|—|—|
| `ROUND` | Slot machine — cycles and locks on the winner |
| `ROUND2` | Mystery boxes — BARRIER boxes orbit with lightning reveal |
| `QUICK` | Slot machine — fast version (~3 s) |
| `COSMIC` | Double counter-rotating orbital rings |
| `DISPLAY` | Single item cycles and lands on the winner |
| `PYRAMID` | Three-tiered rotating pyramid |
| `CONTRABAND` | Items float up and vanish one-by-one |
| `INSTANT` | Particle burst, reward given instantly |
| `AIR_STRIKE` | Items fall from height with lightning |
| `BREAKOUT` | Items burst outward and arc back |
| `METEOR_SHOWER` | Items rain down with flame trails |
| `YIN_YANG` | Two rings converge in a yin-yang pattern |

—

## 🌐 Languages

| Code | Language |
|—|—|
| `en` | English (default) |
| `de` | German / Deutsch |
| `fr` | French / Français |
| `es` | Spanish / Español |

Drop a `messages_.yml` in the plugin folder and set `Language: ` to add any language. Regional locale codes (`en_us`, `pt_br`, etc.) are supported with automatic fallback.