👑 CrownClans

A GUI-focused clan system for Minecraft Survival, SMP, PvP and roleplay servers.

CrownClans gives players a reason to form teams and develop them over time. Create a clan, recruit members, earn points, unlock shared storage, manage a treasury, negotiate alliances, declare wars and sell resources to rotating buyers.

The plugin uses in-game inventory menus for most actions. Players do not need to memorize a long list of commands: /clan or /c opens the interface appropriate for their current situation.

No client-side mod is required. Players use normal Minecraft inventories, chat prompts and commands.

---

🚀 How it works for players

Before joining a clan

A player without a clan opens /clan and sees a starting menu with options to:

• Create a clan for a configurable amount of money.
• Browse clans by joining method.
• View the clan leaderboard and public clan information.
• Use the global buyer to sell available resources.

When browsing clans, the player can choose between three joining methods:

Joining method	What happens
Open	The player joins immediately if the clan has room
Application	A request is sent; clan staff can accept or reject it in the GUI
Paid	The player pays the clan's entry fee; the fee is added to the clan treasury

Clan creation costs 5,000 by default. A new clan's paid-entry fee starts at 1,000 by default. Both values can be changed in config.yml.

Names may contain Minecraft color codes such as &a. The default visible name length is 2–6 letters or digits; formatting codes do not count as visible characters.

After joining a clan

The same /clan command opens a clan dashboard instead of the starting menu. From there, members can access:

• Clan name, current level, points and points needed for the next level.
• Treasury balance and its current capacity.
• Member list and personal statistics.
• Shared clan storage.
• Allies, enemies and other clan relations.
• Clan home.
• Clan buyer and global buyer.
• Resource donations and clan leaderboard.
• Management settings when their clan role allows it.

When a menu needs a name or number, it asks the player to enter the value in chat. Enter cancel to abandon that prompt.

---

🏆 Clan levels, points and storage

CrownClans has 9 clan levels. The server owner can edit the total point requirement for every level. Higher levels increase the treasury capacity and open more shared storage.

Level	Default treasury capacity	Shared storage slots
1	100,000	9
2	250,000	18
3	500,000	27
4	1,000,000	36
5	2,000,000	45
6	3,500,000	54
7	5,000,000	63
8	7,500,000	72
9	10,000,000	81

The storage has up to two pages. One clan member may edit it at a time; other members can still open a read-only view. This helps prevent two players from changing the same stored items simultaneously.

Default combat points

Action	Points
Kill a player from an enemy clan	+150
Kill a neutral player	+35
Kill an ally	−100
Kill a clanmate	−150

All of these values are configurable. A 30-minute repeat-victim cooldown applies by default so the same opponent cannot be farmed for points continuously.

Members can also donate ordinary resources through the GUI:

Donated resource	Default points per item
Diamond	3
Ancient Debris	15
Netherite Ingot	30

The clan buyer can additionally award points when valuable resources are sold to it. Players can see their own kills, deaths, K/D ratio, time in the clan and online time in the dashboard.

---

🤝 Diplomacy and PvP

Alliances require agreement. One clan sends a proposal, and the other clan accepts it. A clan can also end an existing alliance.

Wars begin immediately when an authorized clan member declares one. The server announces the declaration in chat. Ending a war is different: both clans must confirm peace before the war ends.

Clan staff can configure:

• PvP between members of the same clan.
• PvP between allied clans.
• Whether clanmates and allies receive colored name highlighting.
• Whether nearby enemies receive colored name highlighting.

Enemy highlighting only applies within a configurable radius of 7 blocks by default and requires line of sight. It changes name colors through scoreboard teams; it is not a glowing outline around player models.

---

🏠 Clan home and banner

Each clan can have one clan home. A Deputy or Owner can set or delete it. All clan members can use /clanhome once a home exists.

Teleportation uses a boss bar with a 5-second countdown by default. Its color changes as the teleport approaches. Server owners may configure movement and damage to cancel the teleport.

The Owner can customize the clan banner in a GUI:

• Base color.
• Border color.
• Accent color.
• Banner pattern.

Other players can see a temporary banner above the leader without permanently replacing the leader's armor. An animated version of the clan banner appears at the clan home.

---

💰 Economy and rotating buyers

CrownClans can use either its built-in economy or an economy connected through Vault.

• With a registered Vault economy provider, clan payments use that provider.
• Without one, CrownClans uses its internal balances.
• The default starting internal balance is 10,000 per new player.
• Vault by itself does not provide an economy; another plugin must register the actual balance provider.

Global buyer

The global buyer displays up to 18 offers by default. A player sells a listed resource, and the payment goes directly to that player. Each offer has its own remaining stock.

Clan buyer

Every clan receives its own selection of up to 15 offers. The items and prices may differ from those offered to other clans. Payment from these sales goes into the clan treasury, subject to its capacity.

The clan buyer also has a sales multiplier. It begins at x1, reaches x1.5 after 1,000 items sold with the default settings, and eventually reaches x10 after 350,000 items sold. Multiplier steps can be edited in the configuration.

Both buyers rotate their offers every 5 hours by default. Prices are randomized within configured limits, and each offer has a finite stock. Valuable materials can be configured with smaller stock ranges than common materials.

Normal clicks sell up to 64 matching items. Shift-clicking attempts to sell more, limited by the player's inventory, the offer's stock and, for clan sales, available treasury space. Custom items with item metadata are excluded from buyer sales.

---

👥 Roles and management rights

Clan roles determine who can manage the clan. They are separate from Bukkit permissions.

Role	What the player can do
Member	View the dashboard and members, use unlocked storage and clan home, deposit money, donate resources and use buyers
Officer	Member actions plus invitations, application review, kicking lower-ranked members and selected clan highlighting settings
Deputy	Officer actions plus diplomacy, entry mode and fee changes, friendly-fire settings, and setting or deleting the clan home
Owner	Full management: withdraw treasury money, rename the clan, assign roles, transfer leadership, edit the banner and disband the clan

An Officer cannot kick another Officer, Deputy or Owner. Only the Owner can assign roles or transfer ownership.

The treasury is designed for group contributions: all members can deposit, while only the Owner can withdraw. Other clans can see a public clan profile, but the management interface is restricted to authorized members.

---

🔌 Platforms and versions

Platform	Current verification
Paper 1.21.11	Tested in-game on Java 21
Folia 26.2	Plugin startup checked on Java 25; multiplayer gameplay testing is pending
Paper 26.3 build 41 alpha	Plugin startup checked on Java 25; full gameplay testing is pending
Spigot / Bukkit / Purpur	Built against Spigot API 1.21.11; separate live tests are pending
BungeeCord	Command bridge is included; a live proxy test is pending

The JAR targets Java 21. The Java version used to start your server must also meet the requirements of that particular Minecraft server build.

BungeeCord setup

Install the same CrownClans JAR on both the proxy and the game server. The proxy bridge forwards /clan, /c and /clanhome to the connected game server.

Clan state is held on the game server. This beta does not synchronize live clan data between multiple independent game servers, even if those servers point to the same SQL database.

---

🧩 Optional integrations

Plugin	Required?	Purpose
Vault	No	Connects clan payments to an external economy
Vault-compatible economy provider	Only if you want Vault economy	Supplies the player's actual balance
PlaceholderAPI	No	Enables CrownClans values in compatible scoreboards, TAB displays and other plugins

CrownClans works without these integrations by using its built-in economy and its own GUI. With PlaceholderAPI installed, the crownclans expansion registers automatically; there is no separate eCloud expansion to download.

---

🎮 Commands

Most player actions also have GUI buttons.

Command	Function
/clan, /c	Open the starting menu or clan dashboard
/clan create <name>	Create a clan
/clan join <clan>	Join or apply, depending on the clan's entry mode
/clan apply <clan>	Alternative to the join action
/clan invite <player>	Invite a player
/clan kick <player>	Remove a lower-ranked member
/clan leave	Leave a clan
/clan disband	Disband a clan as its Owner
/clan deposit <amount>	Put money into the treasury
/clan withdraw <amount>	Withdraw money as the Owner
/clan ally <clan>	Propose or accept an alliance
/clan break <clan>	End an alliance
/clan war <clan>	Declare war
/clan peace <clan>	Propose or confirm peace
/clan rename <name>	Rename a clan as its Owner
/clan fee <amount>	Change the paid-entry fee
/clanhome	Teleport to the clan home
/clanhome set <name>	Set and name the clan home
/clanhome delete	Delete the clan home
/clan storage status	Show the active storage type
/clan storage migrate <TYPE>	Copy clan data to another storage type

---

🔐 Bukkit permissions

CrownClans currently has two permission nodes:

Permission	Default	Effect
crownclans.use	Everyone	Allows /clan, /c, their subcommands and proxy command forwarding
crownclans.admin	Operators	Allows storage status and storage migration commands

LuckPerms example:

/lp group default permission set crownclans.use true
/lp group admin permission set crownclans.admin true

The admin permission controls storage administration; it does not replace in-clan roles. /clanhome has no separate Bukkit permission node: teleporting requires membership and an existing home, while setting or deleting it requires Deputy or Owner.

---

📊 PlaceholderAPI and scoreboard

CrownClans placeholders can be used by a scoreboard plugin if that plugin processes PlaceholderAPI placeholders.

For example, inside an appropriate scoreboard lines: section:

lines:
  - "&fClan: &e%crownclans_name%"
  - "&fLevel: &a%crownclans_level%"
  - "&fPoints: &6%crownclans_points%"
  - "&6#1 &f%crownclans_top_1_name% &7- &e%crownclans_top_1_points%"
  - "&6#16 &f%crownclans_top_16_name% &7- &e%crownclans_top_16_points%"

The surrounding scoreboard syntax depends on the scoreboard plugin you use.

Placeholder	Output
%crownclans_name%	Clan name without colors; нет if the player has no clan
%crownclans_name_colored%	Clan name with color codes
%crownclans_has_clan%	true or false
%crownclans_level%	Player's clan level, or 0 without a clan
%crownclans_points%	Player's clan points
%crownclans_rank%	Player's clan leaderboard position
%crownclans_members%	Number of clan members
%crownclans_treasury%	Treasury balance
%crownclans_kills%, %crownclans_deaths%, %crownclans_kd%	Player statistics
%crownclans_top_count%	Number of existing clans
%crownclans_top_16%	Formatted line for the clan in position 16
%crownclans_top_16_name%	Name of the clan in position 16
%crownclans_top_16_points%	Points of the clan in position 16

Replace 16 with another positive position, such as 1, 10 or 25. Top entries also support _level, _members, _leader and _treasury. If a requested position does not exist, the default output is —.

The missing-clan text, missing-top text and complete top-line format can all be changed in config.yml.

---

⚙️ Configuration examples

Edit the named entries in the generated files. These examples are excerpts, not replacements for the entire configuration. Restart the server after editing.

Example 1 — faster progression for a smaller server

Edit plugins/CrownClans/config.yml:

clan:
  creation-cost: 2500
  rename-cost: 750
  max-name-length: 6
  level-total-xp: [0, 500, 1800, 4000, 8000, 15000, 25000, 40000, 60000]
  capacities: [100000, 250000, 500000, 1000000, 2000000, 3500000, 5000000, 7500000, 10000000]

combat:
  enemy-kill-xp: 150
  neutral-kill-xp: 35
  ally-kill-xp: -100
  same-clan-kill-xp: -150
  repeat-victim-cooldown-seconds: 1800

This makes clan creation and leveling more accessible while retaining the original treasury progression. The level list contains nine total point thresholds, starting with 0 for level 1.

Example 2 — buyer stock and prices

Edit specific entries in the existing buyer.goods list:

buyer:
  rotate-hours: 5
  global-offers: 18
  clan-offers: 15
  price-random-factor-min: 0.80
  price-random-factor-max: 1.20
  goods:
    STONE: '5:5000:9000'
    DIAMOND: '250:200:500'
    NETHERITE_INGOT: '1800:20:65'

Each item uses base price:minimum stock:maximum stock. For example, a diamond has a base price of 250 and a randomly generated stock between 200 and 500. The random price factors can then move its actual price below or above the base.

Edit the listed entries inside your existing file if you want to retain its other materials.

Example 3 — buyer multiplier

The multiplier-steps list in config.yml uses total items sold:multiplier:

buyer:
  multiplier-steps:
    - '0:1.0'
    - '1000:1.5'
    - '5000:2.0'
    - '15000:3.0'
    - '40000:4.0'
    - '80000:5.0'
    - '140000:6.0'
    - '220000:7.5'
    - '300000:9.0'
    - '350000:10.0'

A clan starts at x1. With these settings, selling a total of 1,000 items unlocks x1.5, and 350,000 items unlocks x10. The plugin caps the resulting multiplier at x10.

Example 4 — customize text and teleportation

Edit plugins/CrownClans/config.yml:

placeholders:
  no-clan: 'нет'
  no-top: '—'
  top-format: '{rank}. {clan} | {points} points'

home:
  delay-seconds: 5
  cancel-on-move: true
  cancel-on-damage: true

top-format accepts {rank}, {clan}, {points}, {level} and {members}. For example, changing no-clan to 'No Clan' changes what %crownclans_name% displays for a clanless player.

---

🌍 Languages

English and Russian are included. Select one in plugins/CrownClans/config.yml:

language: en

To create another translation:

1. Copy plugins/CrownClans/lang/en.yml to a new file such as lang/de.yml.
2. Translate the displayed values.
3. Preserve the original keys and variables such as {0} and {1}.
4. Set language: de in config.yml and restart the server.

Missing translation keys fall back to English.

---

🗄️ Data storage

CrownClans provides 11 storage types:

Local storage	Server or custom storage
FLATFILE, SQLITE, H2, HSQLDB	MYSQL, MARIADB, POSTGRESQL, SUPABASE, SQLSERVER, ORACLE, CUSTOM_JDBC

The default is FLATFILE. To use SQLite, edit plugins/CrownClans/storage.yml:

type: SQLITE

A MySQL setup uses the connection settings in the same file:

type: MYSQL
host: localhost
port: 3306
database: crownclans
username: crownclans
password: 'replace-with-your-password'

SUPABASE uses PostgreSQL with SSL. CUSTOM_JDBC requires a compatible JDBC URL and, if needed, a driver JAR placed in the plugin folder.

Moving existing data

1. Back up the current clan data.
2. Configure the target database connection.
3. Run /clan storage migrate <TYPE> while players are not changing clan data.
4. Confirm that the copy succeeded.
5. Change type in storage.yml and restart the server.

The migration command does not overwrite a non-empty destination and does not automatically switch the active storage type. Local FLATFILE, SQLITE, H2 and HSQLDB storage have been covered by save-and-reopen tests; remote databases still need testing in individual server environments.

---

📦 Installation

1. Place the CrownClans JAR in your game server's plugins/ directory.
2. Start the server once to generate config.yml, storage.yml and language files.
3. Adjust prices, progression, storage and language for your server.
4. Restart the server.
5. Optionally install Vault with an economy provider and PlaceholderAPI.
6. If using BungeeCord command forwarding, place the same JAR on the proxy too.

Beta status: Paper 1.21.11 gameplay and PlaceholderAPI integration were tested. Folia 26.2 and Paper 26.3 alpha passed startup checks. Gameplay testing on Spigot, Bukkit, Purpur and BungeeCord is still pending. Name highlighting uses scoreboard teams, so a separate scoreboard plugin's existing name-tag teams may take priority.

---