⚔ ClanSystem

A complete clan system with a GUI for Paper 1.21.x.

Create clans, invite players, hand out roles, share a clan home and a clan ender chest, collect kills and wear your clan tag above your head. Everything runs through a single menu: /clan.

No dependencies: no Vault, no database, no shading. PlaceholderAPI is supported but optional.

🌍 English and German built in. Switch with language: en or language: de in config.yml – or add your own language file.

---

✨ Features

👑 Clans & Roles

• Three roles: Owner, Manager (up to 2) and Member, each with fixed permissions
• Member limit of 10, or 15 for VIP clans (the owner needs clan.vip), both configurable
• Name rules: 3–5 characters, letters and numbers only, automatically uppercase, with a blacklist (ADMIN, MOD, TEAM …)
• Optional: minimum XP level to create a clan and a cooldown between two creations
• Transfer ownership, promote and demote managers, kick members

🖥️ Full GUI

• /clan opens everything: clan info, members, invites, roles, home, ender chest, statistics, settings
• Leaving, disbanding and transferring ownership go through a confirmation dialog
• Every button is configurable: material, slot, name, lore, amount, glow, custom model data – or hide it completely
• Adjustable menu sizes, player heads in lists, page navigation
• Menu items can't be taken out or duplicated

✉️ Invites

• Clickable Accept and Deny buttons in chat, with hover text
• Invites expire after 120 seconds (configurable, or disable expiry)
• Invites can also be accepted or denied in the GUI
• The clan gets notified about invites, joins and declines

🏠 Clan Home

• One shared home per clan, set by the owner or a manager
• Teleport with a delay (5 seconds by default), cancelled on movement or damage
• Configurable cooldown and blocked worlds

📦 Clan Ender Chest

• Shared storage with 54 slots (double chest) for the whole clan
• Several players can open it at the same time without any duplication exploits
• Permissions are checked on every click: kicked players lose access instantly
• Specific items can be blocked
• When a clan is disbanded, the contents are deleted, dropped or given to the owner – your choice

📊 Statistics

• Kills, deaths and K/D for every player and as a total for the clan
• Kill leaderboard of the clan's members in the statistics menu
• Three sources to choose from:
  • VANILLA – Minecraft statistics, counts all previous kills retroactively (default)
  • INTERNAL – own counter, starting at installation
  • PLACEHOLDER – values from any other plugin
• Offline members are included in the clan total

🏷️ Nametags & Tab List

• Clan tag in front of the name, above the head and in the tab list, e.g. [ABC] Steve
• Fully customizable line below the name, e.g. [ABC] 25 ⚔
• Tab list sorted by clan
• Custom symbols as placeholders (%sword% ⚔, %skull% ☠, %heart% ❤, %star% ✦ …)

🎨 Clan Color

• Owners can color their clan name (16 colors + bold) – in the GUI or with /clan color
• Optional free hex colors behind a separate permission

💬 Clan Chat

• /clan chat <message> sends a message to your own clan only
• Chat spy for staff (clan.chatspy)

⚙️ Clan Settings

Every clan can toggle these in the GUI:

• Friendly fire on/off
• Allow regular members to use the clan home
• Allow regular members to use the clan ender chest
• Clan chat on/off

---

🔌 PlaceholderAPI (optional)

The integration works both ways.

ClanSystem → other plugins (scoreboard, TAB, chat, holograms …):

Placeholder	Content
%clansystem_clan%	Clan name
%clansystem_tag%	Formatted tag, e.g. [ABC]
%clansystem_role%	Role
%clansystem_members% / %clansystem_limit%	Member count / limit
%clansystem_kills% / %clansystem_deaths% / %clansystem_kd%	Player stats
%clansystem_clan_kills% / %clansystem_clan_kd%	Clan stats
%clansystem_has_clan%	true / false

Also available: owner, managers, clan_deaths, clan_count, home, vip, role_raw, clan_plain and clan_color.

Other plugins → ClanSystem: placeholders from other plugins work in nametags, clan chat, all messages and every GUI item.

---

📜 Commands

Command	Who	Description
/clan	everyone	Opens the clan menu
/clan help	everyone	Command overview
/clan create <name>	everyone	Create a clan
/clan info [clan]	everyone	Clan information
/clan members [clan]	everyone	Member list
/clan accept [clan]	invited players	Accept an invite
/clan deny [clan]	invited players	Deny an invite
/clan invite <player>	Owner, Manager	Invite a player
/clan kick <player>	Owner, Manager	Remove a member
/clan promote <player>	Owner	Promote to manager
/clan demote <player>	Owner	Demote a manager
/clan transfer <player>	Owner	Transfer ownership
/clan leave	Manager, Member	Leave the clan
/clan home	all members	Teleport to the clan home
/clan home set / delete	Owner, Manager	Set / delete the clan home
/clan enderchest	all members	Open the clan ender chest
/clan chat <message>	all members	Message your clan
/clan color <color|bold|reset>	Owner	Color the clan name
/clan delete	Owner	Disband the clan
/clan reload	Admin	Reload the configuration
/clan admin <list|info|delete|setlimit|reload>	Admin	Manage clans

Aliases: /clans and /clansystem. Tab completion works for every command.

---

🔑 Permissions

Permission	Default	Description
clan.use	everyone	Basic commands and GUI
clan.create	everyone	Create a clan
clan.vip	–	The owner's clan gets the VIP member limit
clan.chatspy	OP	Read all clan chats
clan.color.hex	OP	Free hex colors for the clan name
clan.bypass.limit	OP	Bypass the member limit and level requirement
clan.bypass.name	OP	Bypass the name rules
clan.bypass.cooldown	OP	Bypass cooldowns and the teleport delay
clan.admin	OP	All permissions above + admin commands

---

🛠️ Configuration

• config.yml – language, limits, name rules, home, ender chest, statistics, nametags, chat format and the GUI layout
• lang/en.yml and lang/de.yml – every text: messages, menu titles, button names, lore and the date format, with & color codes and hex colors (&#RRGGBB)
• Your own language: copy en.yml, translate it and set language to the file name
• /clan reload applies changes without a restart – including a language switch

Already using a nametag plugin?

ClanSystem sets clan tags through scoreboard teams. If you already use TAB or a similar plugin, turn off the built-in nametags with nametag.enabled: false and use the %clansystem_...% placeholders there instead.

---

💾 Storage & Performance

• Data is stored as YAML, one file per clan in plugins/ClanSystem/data/
• Saving runs asynchronously, with an autosave every 5 minutes (configurable)
• Items in the clan ender chest survive Minecraft updates
• Apart from the autosave, no repeating tasks run in the background

---

📋 Requirements

• Paper 1.21.x
• Java 21
• Optional: PlaceholderAPI
• Spigot and Folia are not supported

---

Made by NanoNope