⚔️ VRX Clans - The Ultimate Clan & Base System

VRX Clans is a modern, highly optimized, and fully customizable clan system for Minecraft servers.
It gives your players everything they need to create clans, build protected bases, manage members, run a clan economy, complete quests, form alliances, and fight epic clan wars.

Whether you run a Hardcore PvP, Survival, Citybuild, or SMP server, VRX Clans is designed to fit your server concept with deep configuration options, GUI customization, database support, and powerful admin tools.

---

✅ Version & Compatibility

• Current Version: 1.0.3
• Server Software: Paper, Spigot, Bukkit
• Minecraft Compatibility: 1.20 up to 1.26+
• Recommended Java Version: Java 17 or newer

---

✨ Core Gameplay Features

🛡️ Dynamic Clan Bases

Clans can set their own base location and protect the area around it.

The protected radius is dynamic and can grow through:

• Clan member count
• Configured base radius
• Purchased radius upgrades

Enemy players cannot break blocks, place blocks, or interact with protected blocks inside another clan's base area.

💡 WorldGuard support prevents players from setting clan bases inside protected regions such as spawn areas or other protected zones.

---

🏦 Clan Bank & Economy

Every clan has its own internal bank account.

Players can deposit money into the clan bank, while authorized ranks can withdraw money or use the balance for upgrades, wars, and shop purchases.

Supported economy features:

• Vault economy support
• Clan deposits and withdrawals
• Clan bank GUI
• Shop purchases through the clan bank
• War wagers
• Optional upkeep/tax system

VRX Clans works with any Vault-compatible economy plugin, including:

• vrx_economy
• EssentialsX Economy
• CMI
• TheNewEconomy

---

📦 Clan Vault

Clans can unlock a shared virtual vault at a configurable level.

The vault can be used as shared storage for clan members and can expand as the clan progresses.

Features:

• Configurable unlock level
• Configurable upgrade level
• Saved vault contents
• Optimized dirty-save system
• Admin access through /clana vault <Clan>

---

📈 Clan Levels, XP & Rewards

Clans start at Level 1 and earn XP through active gameplay.

XP can be earned from:

• Breaking blocks
• Killing monsters
• Killing players
• Completing clan quests
• Admin commands

Clan level rewards can be configured directly in the config.

Supported reward options:

• Clan bank rewards
• Custom messages
• Console commands
• Placeholders such as %clan%, %level%, and %bank%

Example:

level-rewards:
  "3":
    bank: 2500.0
    message: "&aYour clan reached level &e%level% &aand received &e%bank%$&a!"
    commands: []
  "5":
    bank: 10000.0
    message: "&6Great work! Level &e%level% &6has been reached."
    commands:
      - "broadcast &bClan %clan% reached level %level%!"

---

✅ Clan Quests

Keep your players active with cooperative clan quests.

Clans can complete shared missions such as:

• Killing zombies
• Mining diamond ores
• Depositing money into the clan bank

When a quest is completed, the clan receives XP rewards.
Quests can reset automatically after a configurable interval.

---

🛒 Clan Shop, Boosters & Base Upgrades

The clan shop gives the clan bank a real purpose.

Clans can purchase:

• Radius upgrades
• XP boosters
• Haste boosters
• Speed boosters
• Strength boosters
• Base regeneration
• Base saturation

Boosters affect clan members and can be configured through the plugin settings.

---

⚙️ Dynamic Rank Permissions

Clan leaders can manage rank permissions directly through an in-game GUI.

Supported permission categories include:

• Invite players
• Access the clan vault
• Withdraw from the clan bank
• Set the clan base
• Use the clan shop
• Manage wars and diplomacy

This allows clan leaders to control their own clan structure without requiring server staff.

---

🏷️ Renameable Clan Roles

Clan roles can be renamed individually for each clan.

Leaders can customize role names through the GUI, allowing every clan to create its own internal hierarchy and style.

Default ranks include:

• Recruit
• Member
• Officer
• Co-Leader
• Leader

---

🤝 Diplomacy System

Clans can manage relationships with other clans.

Available relationship types:

• Allies
• Rivals
• Neutral

Diplomacy requests support:

• Accepting requests
• Denying requests
• Automatic expiration after a configurable timeout
• Ally and rival limits

Friendly fire between clan members or allies can be disabled in the config.

---

⚔️ Clan Wars & KDR Tracking

Bring competition to your server with clan wars.

Clans can declare war on another clan using:

/clan war <Clan> <Wager>

Once the request is accepted:

• Both clans pay the wager into the pot
• Kills are tracked during the war
• The first clan to reach the configured kill target wins
• The winner receives the full pot
• War statistics are broadcast to the server

To prevent abuse, VRX Clans includes war kill-farming protection.
Repeated kills against the same player only count again after a configurable cooldown.

---

📜 Clan Logs

Important clan actions are logged automatically.

Logged actions can include:

• Deposits
• Withdrawals
• Kicks
• Promotions
• Demotions
• War requests
• War starts
• War kills
• War endings
• Diplomacy events
• Role renames

Players can view recent clan logs using:

/clan logs

---

🏆 Leaderboards & /clan top

Players can view the best clans directly through chat.

Available categories:

/clan top level
/clan top bank
/clan top kills
/clan top kdr

If DecentHolograms is installed, admins can also create live hologram leaderboards for:

• Kills
• Level
• Bank balance

---

🏁 Seasons

Server admins can end a season using:

/clana endseason

This can:

• Reward the top clan
• Reset kill and death statistics
• Broadcast the season winner
• Send Discord webhook notifications

---

🛠️ Technical Excellence & Performance

VRX Clans is built with performance and stability in mind.

💾 SQLite & MySQL Support

The plugin supports both local and external database storage.

• SQLite for simple local setups
• MySQL for larger servers or network environments

⚡ HikariCP Connection Pooling

Database access uses HikariCP connection pooling for stable and efficient database connections, especially on MySQL setups.

🧱 Repository, Service & Cache Structure

The backend is separated into cleaner components such as repository, service, and cache layers.
This improves maintainability, performance, and future expandability.

🗺️ Optimized Region Protection

Clan base protection uses chunk-based caching to avoid scanning every clan on every block event.
This helps keep the plugin efficient even with many clans.

📦 Optimized Vault Saving

Clan vaults use a dirty-state saving system.
Vault contents are only serialized and saved when they were actually changed.

🔁 Database Migration System

VRX Clans includes a versioned migration system for database changes.
Future updates can safely add new database fields or tables without breaking existing data.

📡 Discord Webhooks

Send important clan events directly to your Discord server.

Supported webhook events can include:

• Clan creation
• Clan level-ups
• War wins

📊 PlaceholderAPI Support

Use clan data in scoreboards, tab lists, holograms, and other plugins.

Available placeholders include:

%vrxclans_has_clan%
%vrxclans_name%
%vrxclans_level%
%vrxclans_rank%
%vrxclans_members%
%vrxclans_bank%
%vrxclans_radius%

---

🎨 Customization

VRX Clans is designed to be highly configurable.

🌍 Full Localization

The plugin includes language files such as:

• en_US.yml
• de_DE.yml

Messages, prefixes, GUI text, errors, and notifications can be customized.

🖼️ GUI Customization

Menus can be customized through GUI configuration files.
You can change:

• Inventory titles
• Item materials
• Slots
• Display names
• Lore lines

⚖️ Deep Balancing

Server owners can configure important gameplay values, including:

• Clan creation cost
• Rename cost
• Max members
• Max allies/rivals
• XP values
• Level-up multiplier
• Base radius
• Teleport cost and delay
• Vault unlock levels
• Shop prices
• War minimum wager
• War kill target
• War kill-farming cooldown
• Quest targets and rewards
• Level rewards
• Upkeep/tax settings

---

⚙️ Commands

Player Commands

/clan
/clan help
/clan create <Name>
/clan rename <Name>
/clan list
/clan info [Clan]
/clan top [level|bank|kills|kdr]
/clan logs
/clan invite <Player>
/clan join
/clan leave
/clan kick <Player>
/clan promote <Player>
/clan demote <Player>
/clan disband
/clan base
/clan setbase
/clan bank
/clan deposit <Amount>
/clan withdraw <Amount>
/clan shop
/clan ally <Clan|accept|deny>
/clan rival <Clan|accept|deny>
/clan neutral <Clan|accept|deny>
/clan war <Clan> <Wager>
/clan war accept
/clan war deny

Admin Commands

Required permission:

vrxclans.admin

/clana reload
/clana save
/clana spy
/clana inspect
/clana inspect <Clan>
/clana setholo <kills|level|bank>
/clana endseason
/clana vault <Clan>
/clana eco <Clan> <add|remove|set> <Amount>
/clana addxp <Clan> <XP>
/clana setlevel <Clan> <Level>
/clana setleader <Clan> <Player>
/clana forcejoin <Clan> <Player>
/clana disband <Clan>
/clana rename <Old> <New>

---

🔑 Permissions

vrxclans.admin

Allows access to all admin commands.

vrxclans.admin.bypass

Bypasses clan base protection.

Internal clan permissions are managed by clan leaders directly in the GUI.

---

📦 Dependencies & Integrations

Required

• Paper
• Java 17+
• Vault
• A Vault-compatible economy plugin

Recommended / Optional

• PlaceholderAPI
• DecentHolograms
• WorldGuard

---

✅ Recommended Setup

For the best experience, use:

• Paper 1.20 or newer
• Java 17+
• Vault
• A Vault-compatible economy plugin
• PlaceholderAPI for scoreboards and tab lists
• DecentHolograms for live leaderboards
• WorldGuard for spawn and region protection

---

💬 Support

If you need help, please provide:

• Your server version
• Your plugin version
• Your Java version
• Console errors or full logs
• Your database type, if the issue is database-related

This makes it much easier to find and fix issues quickly.