Home

zMClans Wiki

Modern, high-performance, fully configurable clan plugin for Paper / Purpur 1.20+ (Java 21).

Introduction

zMClans is a modern clan plugin for Paper/Purpur servers. It offers full clan management, ranks, alliances, rivalries, homes, private chat, leveling, statistics, and a data-driven GUI system — all configurable through YAML.

Requirements & Installation

Requirements

Server: Paper, Purpur, or compatible forks (API 1.20+; supports 1.20, 1.20.6, 1.21+).
Java: Java 21 or higher.
Optional: Vault (economy), PlaceholderAPI (placeholders in chat, scoreboards, tablists).

Installation

Download zMClans-1.0.0.jar from target/.
Drop it into your server's plugins/ folder.
Start/restart the server to generate plugins/zMClans/.
Edit config.yml, ranks.yml, guis/, and langs/ as needed.
Run /zmclan reload to apply changes without restarting.

Features

Full clan management: create, invite, accept, deny, leave, kick, disband.
Public join: clans can enable open join; players use /clan join <clan> without invitation.
Alliances & rivalries: mutual ally requests, rivalries, relationship removal, per-level limits.
Ally interactions: shared homes, ally chat, ally PvP toggles.
Hierarchical rank system: custom ranks with priorities and permissions (ranks.yml).
Named clan homes:
- Create, visit, delete multiple homes per clan; limits per level.
- Configurable warmup with real-time movement cancellation (camera rotation ignored).
- Configurable cooldown with bypass permission.
- Ally-shared home visibility and access controlled by rank permissions.
Private clan chat: uses Paper's AsyncChatEvent, toggle or direct message, fully configurable format.
Friendly fire: melee and projectile protection; toggle via /clan ff or settings GUI; separate ally PvP toggle.
Async invitation system: auto-expiry in a separate thread, duplicate/size/other-clan validation, configurable notifications.
Points, levels & leaderboard:
- Points for create, join, kills, deaths, rank changes (levels.yml).
- Visual + chat feedback for points and level-ups; global announcements for clan creation/disband.
- Paginated leaderboard with filters: members, points, kills, KDR, deaths.
- Member, home, ally and rival capacity per level.
Individual & clan stats: kills, deaths, KDR persisted per player and clan.
Admin tools: query clans/members, manage leadership, edit points, reload.
Tag & color customization (/clan modtag <tag>):
- Adventure MiniMessage (gradients, safe decorations).
- Hex and legacy codes.
- Validation counts only visible text; enforces clan.tag.min-length and clan.tag.max-length.
- Blocks click/hover/command injections — only colors and visual styles allowed.
Decoupled GUIs: fully data-driven YAML menus.

Player Commands

Root: /clan — aliases: /c, /clans

Command	Description	Permission	Rank Perm
`/clan` (`menu`, `gui`)	Opens the main menu	`zmclan.player.menu`	—
`/clan create <name> [tag/modtag]`	Creates a clan (tag optional)	`zmclan.player.create`	—
`/clan info [clan]`	Clan info	`zmclan.player.info`	—
`/clan list`	Leaderboard menu	`zmclan.player.list`	—
`/clan invite <player>`	Invites a player	`zmclan.player.invite`	`INVITE`
`/clan invites`	Received invitations GUI	`zmclan.player.invites`	—
`/clan accept [clan]`	Accepts a pending invite	`zmclan.player.accept`	—
`/clan deny [clan]`	Denies a pending invite	`zmclan.player.deny`	—
`/clan join <clan>`	Joins a clan with open invitations	`zmclan.player.join`	—
`/clan members`	Members GUI	`zmclan.player.members`	—
`/clan setrank <player> <rank>`	Sets a member's rank	`zmclan.player.rank`	`PROMOTE`
`/clan kick <player>`	Kicks a member	`zmclan.player.kick`	`KICK`
`/clan leave`	Leaves the clan	`zmclan.player.leave`	—
`/clan disband [confirm]`	Disbands the clan	`zmclan.player.disband`	`DISBAND`
`/clan home [name]`	No name: opens GUI; name: teleport	`zmclan.player.homes` / `zmclan.player.home`	`USE_HOME`
`/clan homes`	Homes GUI	`zmclan.player.homes`	—
`/clan sethome [name]`	Creates/updates a home	`zmclan.player.sethome`	`SET_HOME`
`/clan delhome\|deletehome <name>`	Deletes a home	`zmclan.player.delhome`	`SET_HOME`
`/clan chat [message]`	Toggles or sends clan chat	`zmclan.player.chat`	`USE_CHAT`
`/clan ff`	Toggles friendly fire	`zmclan.player.settings`	`EDIT_SETTINGS`
`/clan desc <text>`	Changes description	`zmclan.player.description`	`EDIT_DESCRIPTION`
`/clan modtag <tag>`	Changes tag/colors (gradients/hex)	`zmclan.player.modtag`	`MODTAG`
`/clan settings`	Settings GUI	`zmclan.player.settings`	`EDIT_SETTINGS`
`/clan ally add <clan>`	Sends an ally request	`zmclan.player.relations`	`EDIT_SETTINGS`
`/clan ally accept\|deny\|cancel <clan>`	Manages ally requests	`zmclan.player.relations`	`EDIT_SETTINGS`
`/clan ally remove <clan>`	Removes ally / cancels request	`zmclan.player.relations`	`EDIT_SETTINGS`
`/clan rival add\|remove <clan>`	Manages rivalries	`zmclan.player.relations`	`EDIT_SETTINGS`
`/clan relation remove <clan>`	Removes ally or rivalry	`zmclan.player.relations`	`EDIT_SETTINGS`
`/clan stats`	Opens consolidated clan info	`zmclan.player.info`	—
`/clan help`	Shows command help	`zmclan.player.help`	—

All zmclan.player.* nodes are denied by default. Use zmclan.player as the parent node to grant all player features.

Special Player Permissions

zmclans.clan.bypass.cooldown — skips home teleport cooldown.
zmclans.clan.bypass.cost — skips clan creation cost.

Admin Commands

Root: /zmclan — aliases: /zmclans, /clanadmin

Each subcommand requires its specific admin permission (denied by default). zmclans.admin is the parent node for full access. YAML CMD_CONSOLE: actions additionally require zmclans.admin.console.

Command	Permission	Description
`/zmclan help`	`zmclans.admin.help`	Lists admin commands
`/zmclan reload`	`zmclans.admin.reload`	Reloads config, langs, ranks, GUIs
`/zmclan list [page]`	`zmclans.admin.list`	Paginated clan list (10/page)
`/zmclan members <clan> [page]`	`zmclans.admin.members`	Members, ranks, online status
`/zmclan info <clan>`	`zmclans.admin.info`	Clan details
`/zmclan disband\|delete <clan>`	`zmclans.admin.disband`	Disbands a clan
`/zmclan setleader <clan> <player>`	`zmclans.admin.setleader`	Transfers leadership
`/zmclan points <add\|set\|remove> <clan> <amount>`	`zmclans.admin.points`	Updates points & level

Clan Ranks & Permissions

Defined in ranks.yml. Hierarchy is driven by priority (higher = stronger). A member cannot kick or promote someone with equal or higher priority.

Available Rank Permissions

USE_HOME — use /clan home
USE_CHAT — clan private chat
INVITE — invite players
KICK — kick lower ranks
PROMOTE — change lower ranks
SET_HOME — set clan homes
EDIT_DESCRIPTION — edit description
EDIT_SETTINGS — manage settings (open invites, public join, shared homes, ally options)
TRANSFER_LEADER — transfer ownership
DISBAND — disband the clan
MODTAG — modify tag & colors

Default Ranks

member (Priority 1) — USE_HOME, USE_CHAT
officer (Priority 2) — above + INVITE
admin (Priority 3) — above + KICK, PROMOTE, SET_HOME, EDIT_DESCRIPTION, MODTAG
leader (Priority 4) — protected (is-leader: true), all permissions

GUIs & YAML Configuration

Menus live in guis/ and follow a DeluxeMenus-like convention.

Menu Files

general.yml — no-clan menu (clan_start) and main menu (clan_main)
members.yml — paginated member list
member_manage.yml — per-member panel (promote, demote, kick, transfer)
clanlist.yml — paginated clan ranking/browser
invite.yml — online player picker for invites (1-click)
invites.yml — received invites (Left = accept, Right = deny)
settings.yml — clan settings panel
clan_info.yml — clan info & stats
homes.yml — homes management (incl. ally-shared)
confirm.yml — generic confirmation menu

Item Properties

material — Bukkit material (e.g. EMERALD, playerhead)
slot — single slot (0–53)
slots — list/range for filler items
display-name / display_name — visible name (supports &#RRGGBB and &a)
lore — list of lore lines
glow — true / false
item-flags / item_flags — Bukkit flags
action — see below
require-rank-permission / require_rank_permission — hides item without permission

Action Types

CLOSE — close inventory
CANCEL — return to previous/main menu
PAGE_NEXT / PAGE_PREV — pagination
OPEN_GUI:<name> — open another menu
CREATE_CLAN — show clan creation instructions
SHOW_HELP — show command help
TOGGLE_CHAT — toggle clan chat
CLAN_HOME_OR_SETHOME — Left = teleport, Right = set home
TOGGLE_SETTING:<key> — e.g. friendly_fire, open_invitations
MEMBER_PROMOTE, MEMBER_DEMOTE, MEMBER_KICK, MEMBER_TRANSFER_LEADER
CMD_PLAYER:<command> — run as player
CMD_CONSOLE:<command> — run from console

Notifications (`notifications.yml`)

Each event toggles title, actionbar, and sound independently. Titles support title, subtitle, fade-in, stay, fade-out. Sounds use org.bukkit.Sound names with volume and pitch.

Included events:

Progression: clan-points-earned, clan-levelup, clan-create, clan-disband
Members: member-promote, member-demote, member-kick, member-join, member-leave, member-joined, member-left, member-kicked, transfer-leader
Invitations: invite-sent, invite-received, invite-accepted
Homes & allies: home-teleport, home-set, ally-accepted

Global creation/disband announcements and points/level messages are in the language file, not here.

Languages & Placeholders

Language (`config.yml`)

Set language: "ES" or "EN" — loads from plugins/zMClans/langs/:

lang_ES.yml — full Spanish
lang_EN.yml — full English

Both files share identical keys and support &#RRGGBB hex colors.

Main Config Files

config.yml — name/tag validation, cost, invites, homes, chat, leaderboard cache, storage, economy, relation colors
levels.yml — level formula, point deltas, per-level limits, informative rewards
ranks.yml — ranks, priorities, formats, permissions
notifications.yml — titles, actionbars, sounds per event
guis/*.yml — menus

Built-in Placeholders (messages & GUIs)

{player}, {clan}, {tag}, {leader}, {rank}
{members}, {points}, {created_at}
{home_location}
{friendly_fire_status}, {chat_status}
{creation_cost}, {max}
Extended in menus: {homes_count}, {allies_count}, {rivals_count}

PlaceholderAPI

With PlaceholderAPI installed, the plugin registers %zmclans_...% and relational %rel_zmclans_relation_...% expansions.

1. Identification & State

%zmclans_hasclan% — true/false
%zmclans_hasclan_formated% — formatted tag if in clan
%zmclans_hasclan_formated_nocolor% — clean tag
%zmclans_clan% / %zmclans_name% — clan name
%zmclans_clanid% — clan UUID

2. Tags & ModTags

%zmclans_modtag% — styled tag (or clan name if no custom tag)
%zmclans_tag% / %zmclans_tag_color% / %zmclans_tag_formated%
%zmclans_tag_nocolor% / %zmclans_tag_formated_nocolor%

3. Leadership & Members

%zmclans_leader% / %zmclans_leader_formated%
%zmclans_is_leader% — true/false
%zmclans_members% / %zmclans_count_members%
%zmclans_onlinemembers% / %zmclans_count_onlinemembers%
%zmclans_slots% / %zmclans_slots_total%

4. Points & Ranking

%zmclans_points% — formatted with thousands separator
%zmclans_points_unformated% — raw number
%zmclans_current_position% / %zmclans_top% — clan position

Top / Ranking Placeholders (New Format)

%zmclans_top_<metric>_<position>_name%    → clan name at position
%zmclans_top_<metric>_<position>_value%   → metric value at position
%zmclans_top_<metric>_<position>_tag%     → clan tag at position

Available metrics: points, kills, kdr, deaths, members Positions: 1, 2, 3, … (any positive integer)

Examples:

%zmclans_top_points_1_name% → name of the #1 clan by points
%zmclans_top_points_1_value% → points of the #1 clan
%zmclans_top_points_1_tag% → tag of the #1 clan
%zmclans_top_kdr_3_value% → KDR of the #3 clan in KDR ranking
%zmclans_top_kills_2_tag% → tag of the #2 clan by kills
%zmclans_top_deaths_1_name% → name of the #1 clan by deaths
%zmclans_top_members_5_value% → member count of the #5 clan by size

5. Settings & States

%zmclans_desc% / %zmclans_desc_color% / %zmclans_desc_nocolor%
%zmclans_is_ff% / %zmclans_global_ff% — true/false
%zmclans_is_ff_formated% — ON/OFF
%zmclans_isopen% / %zmclans_isopen_formated%
%zmclans_chat_active% / %zmclans_chat_active_formatted%

6. Home & Dates

%zmclans_hashome% — true/false
%zmclans_home% — world (100, 64, -200)
%zmclans_home_world%, %zmclans_home_x%, %zmclans_home_y%, %zmclans_home_z%
%zmclans_creation_date% — YYYY-MM-DD
%zmclans_creation_hours% — unix timestamp

7. Player Info in Clan

%zmclans_player_role% — rank ID
%zmclans_player_role_formated% — colored rank name
%zmclans_player_role_prefix% — rank prefix
%zmclans_player_joindate%
%zmclans_player_permissions_amount%
%zmclans_player_kills%, %zmclans_player_deaths%, %zmclans_player_kdr%

8. Cross-Lookup

%zmclans_search_player_clan:<player>% — clan name of the given player

9. Relational Placeholders

%rel_zmclans_relation_relboolean_member% — same clan
%rel_zmclans_relation_relboolean_ally% — allies
%rel_zmclans_relation_relboolean_rival% — rivals
%rel_zmclans_relation_relboolean_neutral% — neutral / no clan
%rel_zmclans_relation_relcolor% / %rel_zmclans_relation_reltext% — configured color for sameclan, ally, rival, neutral
%rel_zmclans_relation_reltext_coloured% — legacy color codes
%rel_zmclans_relation_reltype% — returns sameclan, ally, rival, neutral

Storage

Native SQLite and MySQL support via HikariCP.

storage:
  type: "SQLITE"           # or "MYSQL"
  auto-save-interval: 5    # minutes between auto-saves

  sqlite:
    file: "database/clans.db"

  mysql:
    host: "localhost"
    port: 3306
    database: "zmclans"
    username: "root"
    password: "password"
    pool-size: 10
    useSSL: false
    allowPublicKeyRetrieval: true

Performance: auto-saves run asynchronously to reduce main-thread load.
Write ordering: queued SQL mutations use a single writer (keeps create → disband order).
Shutdown/reload: waits for queued writes to finish, then performs a final save before closing the pool.
Migrations: additive only — adds missing columns without replacing tables or deleting records.

Leveling & Server Settings

Progression (`levels.yml`)

Level is calculated from points: base-points * (level ^ exponent) between start-level and max-level. progression.enabled: false fixes the level at start-level.

progression.points defines deltas for create-clan, join-member, kill, death, promote-member, demote-member. Negative values subtract (clan total never goes below 0). Admin point changes use the same level-up and notification flow.

progression.level-limits.<level> configures members, homes, allies, rivals. Missing levels fall back to the nearest lower entry. Limits are enforced in operations, not just GUIs. progression.rewards entries are informative — they do not execute commands or give items.

Homes, Invitations & Leaderboard

home.max-homes — fallback home limit
home.teleport-cooldown, home.teleport-warmup, home.cancel-on-move
invitations.expire-seconds — expiry (0 = never)
invitations.block-if-in-clan — block invites to players already in a clan
leaderboard.refresh-interval — cache TTL in seconds (min 1)
relations.ally-request-expire-seconds — ally request expiry
relations.max-per-clan — ally/rival fallback if levels.yml has no entry

Reducing a limit does not delete existing data. Clans keep homes/relations they already have but can't add more until below the limit.

Economy

clan.creation-cost — creation price
economy.enabled — enable/disable charging
economy.mode — VAULT, CUSTOM, or NONE
- VAULT — requires Vault + economy provider
- CUSTOM — requires PlaceholderAPI, a balance-placeholder, and take-command (supports {player} and {amount})
- NONE — no charge
economy.allow-cost-bypass — enables zmclans.clan.bypass.cost for operators

Creation is rejected if the integration is missing, balance is insufficient, or withdrawal fails. No clan is created without a successful charge.

Public API & Events

Facade: dev.zm.clan.api.ZMClansAPI — obtained via zMClans#getAPI(). Add zMClans as provided when compiling.

Plugin candidate = Bukkit.getPluginManager().getPlugin("zMClans");
if (candidate instanceof zMClans clans && clans.isEnabled()) {
    ZMClansAPI api = clans.getAPI();
    api.getClanByPlayer(player.getUniqueId()).ifPresent(clan ->
        player.sendMessage(clan.name() + " | level " + clan.level() + " | KDR " + clan.kdr()));
}

The API exposes immutable snapshots of clans, members, and homes. Lookups by UUID / name / player, member & leaderboard queries, rank permission checks, clan creation, rank assignment, and point changes.

All calls must run on the main thread. The API does not expose SQL connections.

Bukkit Events (`dev.zm.clan.api.event`)

ClanCreatedEvent
ClanMemberJoinEvent
ClanMemberLeaveEvent
ClanPointsChangeEvent
ClanLevelChangeEvent

Compatibility Notes

The leader cannot leave their own clan — transfer leadership or disband.
/clan stats is a legacy alias that opens the consolidated info view (no separate stats menu).
Database migrations are additive and preserve existing data.
Requires Paper API 1.20+ and Java 21. Vault and PlaceholderAPI are optional unless the configured economy mode requires them.
Update checks require a valid resource identifier; they are not needed for the plugin to work.