ClanCL

ClanCL is a fast, lightweight Minecraft Paper plugin that enables players to form clans, share resources and economy, and display custom clan tags across the server.

---

✨ Features

• Custom Clan Tags: Fully dynamic clan tags with PlaceholderAPI support.
• Shared Clan Chest: Secure, multi-slot shared inventory (/clan chest) for clan members to share items.
• Clan Bank System: Integrated economy through Vault so clans can deposit, withdraw, and manage shared funds.
• Member & Role Management: Flexible invite systems, kicks, and bans.
• PlaceholderAPI Integration: Ready out of the box for TAB, InteractiveChat, DecentHolograms, and modern chat formatters (LPC, EssentialsX, etc.).
• Dynamic Display Names: Automatically updates player display names on clan events (join, leave, create, tag change).
• Comprehensive Admin Control: Full administrative suite to inspect chests, modify balances, and manage any clan forcibly.
• Clean & Customizable Configs: Clean YAML configurations with multi-line help menus (usage: |-).

---

💻 Commands & Permissions

Player Commands (/clan)

(Player command access is managed via in-clan role permissions rather than server permission nodes)

Clan Management

• /clan create <name> <tag> - Create a new clan. The name is formatted as Xxxxx and the tag in uppercase.
• /clan invite <player> - Invite a player to join your clan (Default: Captain+).
• /clan join <tag> - Accept a pending clan invitation.
• /clan leave - Leave your current clan (Leaders cannot leave without disbanding or transferring ownership).
• /clan disband <name> <tag> - Request clan deletion (Leader only).
• /clan confirm disband - Confirm clan deletion (expires after 60 seconds).

Members & Ranks

• /clan kick <player> - Kick a member from the clan (Default: Captain+).
• /clan ban <player> - Kick and blacklist a player from joining (Default: Co-Leader+).
• /clan unban <player> - Remove a player from the clan blacklist (Default: Co-Leader+).
• /clan promote <player> - Promote a clan member (Default: Captain+).
• /clan demote <player> - Demote a clan member (Default: Captain+).

Bank, Home & Chest

• /clan bank - View the current clan bank balance.
• /clan bank deposit <amount> - Deposit money into the clan bank (whole numbers only). Available to all members.
• /clan bank withdraw <amount> - Withdraw money from the clan bank (whole numbers only) (Default: Co-Leader+).
• /clan sethome - Set the clan home location (Default: Co-Leader+).
• /clan home - Teleport to the clan home (3-second warmup, cancels on movement).
• /clan chest - Open the shared clan chest (Default: Veteran+).

Diplomacy & PvP

• /clan ally <tag> - Send an alliance request to another clan.
• /clan accept ally <tag> - Accept a pending alliance request.
• /clan deny ally <tag> - Reject a pending alliance request.
• /clan unally <tag> - Break an alliance with a clan.
• /clan enemy <tag> - Declare another clan as an enemy (no acceptance required).
• /clan unenemy <tag> - Remove a clan from the enemy list.
• /clan pvp - Toggle friendly fire within your clan.
• /clan pvp ally <tag> - Toggle friendly fire with an allied clan. (All diplomacy commands default to Co-Leader+)

Chat & Info

• /clan chat - Toggle exclusive clan-only chat channel.
• /clan chatally - Toggle alliance-wide chat channel.
• /clan online - List online clan members.
• /clan menu - Open the main clan GUI menu (also /clan).
• /clan info [tag] - Open the GUI menu for your clan or another clan.

---

Admin Commands (/adminclan or /aclan)

(Hidden from tab-complete and execution if the user lacks staff permissions)

Clan & Member Management

• /adminclan disband <name> <tag> - Forcefully disband a clan (bank balance is transferred to the admin). clancl.admin.disband
• /adminclan kick <user> <tag> - Forcefully kick a player from a clan. clancl.admin.kick
• /adminclan ban <user> <tag> - Ban a player from joining a specific clan. clancl.admin.ban
• /adminclan unban <user> <tag> - Unban a player from a clan. clancl.admin.unban

Chest & Economy

• /adminclan viewchest <tag> - Inspect a clan chest.
  • Read-only inspection: clancl.mod.viewchest
  • Full management control: clancl.admin.viewchest
• /adminclan deposit <amount> <tag> - Force deposit money into a clan bank. clancl.admin.deposit
• /adminclan withdraw <amount> <tag> - Force withdraw money from a clan bank. clancl.admin.withdraw

Admin Chat Spy

• /adminclan spy <tag> - Monitor private clan and ally channels for a specific clan (stackable). clancl.admin.spy
• /adminclan spyall - Monitor all clan and alliance chat channels globally. clancl.admin.spy
• /adminclan cancelspy - Stop spying on all channels (automatically cleared on disconnect). clancl.admin.spy

System & Maintenance

• /adminclan backup create - Create a database backup. clancl.admin.backup
• /adminclan backup restore <filename> - Restore a database backup. clancl.admin.backup
• /adminclan export - Export all clan data to JSON format. clancl.admin.export
• /adminclan import <filename.json> - Import clan data from JSON (overwrites current data). clancl.admin.import
• /adminclan reload - Reload configurations and language files. clancl.admin.reload

---

Permissions Structure

1. Server Permission Nodes (LuckPerms / GroupManager)

Server permissions only govern administrative commands (/adminclan). Standard /clan commands are controlled internally by clan ranks.

• clancl.bypass.cooldowntp - bypass to immediately teleport home /clan home.
• clancl.staff - Base staff permission required to see or autocomplete /adminclan. Automatically granted by any child permission below.
• clancl.admin.* - Full administrative access (includes all clancl.admin.* and clancl.mod.* permissions). Default: OP.
  • clancl.admin.viewchest - Full control over any clan chest.
  • clancl.admin.withdraw - Force withdraw funds from clan banks.
  • clancl.admin.deposit - Force deposit funds into clan banks.
  • clancl.admin.disband - Force disband clans.
  • clancl.admin.kick - Force kick players from clans.
  • clancl.admin.ban - Force ban players from clans.
  • clancl.admin.unban - Force unban players from clans.
  • clancl.admin.backup - Create and restore database backups.
  • clancl.admin.export - Export plugin data to JSON.
  • clancl.admin.import - Import plugin data from JSON.
  • clancl.admin.reload - Reload configs and language files.
  • clancl.admin.spy - Access to spy, spyall, and cancelspy commands.
• clancl.mod.* - Moderator permission node.
  • clancl.mod.viewchest - Read-only inspection of clan chests.

🔌 PlaceholderAPI Placeholders

All placeholders return empty ("") if the player is not in a clan (configurable in placeholders.no-clan).

Player's Clan Info

• %clancl_name% — Displays the player's clan name.
• %clancl_tag% — Displays formatted tag with rank prefix (e.g., &7[&6**STAFF&7]&r).
• %clancl_tag_raw% — Raw clan tag without brackets or color codes.
• %clancl_level% — Current clan level.
• %clancl_points% — Progress points toward the next level.
• %clancl_total_points% — Total lifetime clan points accumulated.
• %clancl_clan_kills% — Total lifetime kills accumulated by all clan members.
• %clancl_bank% — Raw bank balance integer.
• %clancl_bank_formatted% — Formatted bank balance (e.g., 50.000).
• %clancl_members% — Total member count.
• %clancl_members_online% — Online member count.

Player Stats within Clan

• %clancl_role% — Translated role name with color codes.
• %clancl_role_symbol% — Role symbol prefix (**, *, +, ~, -).
• %clancl_kills% — Individual player kills.
• %clancl_deaths% — Individual player deaths.

Allies & Enemies

• %clancl_ally_1% to %clancl_ally_5% — Name of the allied clan at specified slot. Add _tag for the tag (e.g., %clancl_ally_1_tag%).
• %clancl_enemy_1% to %clancl_enemy_10% — Name of the enemy clan at specified slot. Add _tag for the tag (e.g., %clancl_enemy_1_tag%). (Unassigned slots return NONE by default)

Clan Leaderboards (Top 1–10)

Global rankings sorted by level, lifetime points, and name. Placeholders do not depend on the executing player and update every 5 minutes (or instantly upon clan creation/disbandment). Unassigned slots return Not found.

• %clancl_top_N_name% — Name of the Top N clan.
• %clancl_top_N_tag% — Tag of the Top N clan.
• %clancl_top_N_level% — Level of the Top N clan.
• %clancl_top_N_points% — Total lifetime points of the Top N clan.

(Example usage: %clancl_top_1_name%, %clancl_top_10_level%)

---

🖼️ Images

!This image shows the plugin's main menu, displaying basic information for each clan.

---

⚙️ Requirements & Compatibility

• Server Software: Paper / Purpur / Folia (1.21.1 or higher)
• Java Version: Java 21+

Dependencies:

• Vault + Economy provider (EssentialsX, EconomyManager, etc.) for bank functionality.
• PlaceholderAPI (Obligatory for chat, TAB, and hologram tags).
• LuckPerms (Recommended)
• Tested Chat Formatters: LPC (Simple Chat Formatter), InteractiveChat. (optional)

---

📥 Installation

1. Download the latest ClanCL-1.1.8.jar.
2. Place the file in your server's plugins/ directory.
3. Ensure Vault and PlaceholderAPI are installed.
4. Restart your server.
5. Configure plugins/ClanCL/config.yml to your liking!