API
Reading clans, members, roles, land and DTR, adjusting EXP and DTR, listening to clan events, and running the same flows the player's own commands run.
ClansService is how another plugin reads and drives ExyliaClans: who is in which clan, what they may
do there, how the clan is progressing, whether its land can be raided right now — and, when you want
it, the same actions the player's own commands run.
ExyliaAPI.get(ClansService.class).ifPresent(clans ->
clans.clanOf(player.getUniqueId())
.ifPresent(clan -> player.sendMessage("Clan: " + clan.name())));This page is for plugin developers. Server owners who only want clan data in a scoreboard or hologram can use Placeholders instead. ExyliaAPI.get returns an empty Optional while ExyliaClans is not running, so check it rather than assuming the service exists.
The artifact, the repository and the plugin.yml line are the same for every Exylia plugin and live
on the public API page.
Before you reach for it — the clan bridge#
If your question is are these two on the same side, you do not want this service.
ExyliaClans registers itself with ExyliaLib's clan bridge at priority 100 on enable. Anything that
asks net.exylia.lib.clan.Clans gets ExyliaClans' answer, without being configured to and without
knowing ExyliaClans exists — which is why an ExyliaFFA arena's friendly fire, an ExyliaCapture team
check and an ExyliaPracticeCore party check already agree with the clan a player is actually in.
if (Clans.areInSameClan(attacker.getUniqueId(), victim.getUniqueId())) return;
if (Clans.areAllied(attacker.getUniqueId(), victim.getUniqueId())) return;The bridge is deliberately small — same clan, allied, rivals, the clan a player is in, its members and
its online members — and it answers the same way on a server running a different clan plugin
altogether. Use it for relations. Use ClansService for everything the bridge does not model: roles,
progression, statistics, DTR, land, and every action below.
Everything that returns a value reads from the plugin's cache and is safe from a menu redraw or a
placeholder. Everything that returns void runs the same flow the player's own command runs —
permission checks, cooldowns, database writes and the messages the player sees — so call those on the
main thread, and no more often than a player could trigger them.
Membership#
| Method | What it does |
|---|---|
boolean isInClan(UUID player) | Whether the player belongs to any clan. |
boolean isLeader(UUID player) | Whether the player leads their clan. |
Optional<Clan> clanOf(UUID player) | Their clan. Empty when they are in none. |
Optional<Clan> clanById(String clanId) | A clan by id. Empty when no clan has it. |
Optional<Clan> clanByName(String name) | A clan by the name players type, case insensitive. Empty when no clan goes by it. |
Collection<Clan> allClans() | Every clan, as a snapshot of the cache. Fine for a leaderboard, wasteful in a loop. |
Optional<ClanMember> memberOf(UUID player) | Their membership record. Empty when they are in no clan. |
List<ClanMember> membersOf(String clanId) | Everyone in a clan. Empty when the clan does not exist. |
Optional<ClanRole> roleOf(UUID player) | Their role within their clan. Empty when they are in no clan. |
String roleNameOf(UUID player) | The role name, for display. Never null and never empty: a player in no clan reads messages.yml → placeholders.none, which ships as {muted}None. |
int memberCount(UUID player) | How many players are in that player's clan. 0 when they are in none. |
List<ClanRole> roles(String clanId) | Every rank the clan has, lightest first. Empty when the clan does not exist. Role ids belong to one clan, so this is where setRole gets its id. |
Relations#
| Method | What it does |
|---|---|
boolean areAllies(String clanIdA, String clanIdB) | Whether two clans are allied. |
boolean areRivals(String clanIdA, String clanIdB) | Whether two clans are rivals. |
boolean sameClan(UUID playerA, UUID playerB) | Whether two players share a clan. false when either is clanless, so two unaffiliated players are never treated as clanmates. |
boolean friendlyFireEnabled(UUID player) | Whether their clan lets members hurt each other. false when it is off or the player is in no clan. |
int allyCount(UUID player) | How many allies their clan has. 0 when they are in none. |
ClanRelation relation(UUID playerA, UUID playerB) | SAME_CLAN, ALLY, RIVAL or NONE, in one cache read — cheap enough for every hit. A rivalry declared by either side counts. NONE when either is clanless. |
Progression#
Everything a clan's level derives from is computed here rather than stored on the Clan record, so
reading a clan stays a cache hit.
| Method | What it does |
|---|---|
int level(String clanId) | The clan's level. 1 when the clan does not exist. |
long exp(String clanId) | Experience earned. |
long expForNextLevel(String clanId) | What the next level costs. 0 when the clan does not exist or is already at the highest level. |
int maxMembers(String clanId) | The member limit at its current level, slots granted with /clanadmin setslots included. |
int maxAlliances(String clanId) | The alliance limit at its current level. |
int maxRivals(String clanId) | The rivalry limit at its current level. |
Statistics#
| Method | What it does |
|---|---|
Optional<ClanStats> stats(String clanId) | The clan's kill, death and playtime totals. Empty when the clan does not exist. |
Raiding#
| Method | What it does |
|---|---|
boolean isRaidable(String clanId) | Whether the clan's land can be raided right now. |
DtrState dtrState(String clanId) | Where it stands in the DTR cycle. NORMAL when the clan does not exist or the server runs without DTR. |
double dtr(String clanId) | Its current deaths-till-raidable. |
double maxDtr(String clanId) | The highest DTR it can reach at its current size. Members divided by members-per-point, never below 1.0. Level does not enter into it. |
Land#
| Method | What it does |
|---|---|
Optional<ClanClaim> claimOf(String clanId) | The land the clan owns. Empty when it owns none. |
Adjustments#
Writes with no player behind them, for a plugin that rewards or punishes a clan for something it tracks itself. No rank permission is checked and nobody is told anything beyond what the plugin announces on its own. Call them on the main thread.
| Method | What it does |
|---|---|
boolean addExp(String clanId, long amount) | Adds EXP, or takes it away when negative, through the same path a kill or death does: a crossed level is announced and the caps follow. Never below zero, never past the top level. false when the clan does not exist, levels is off, or amount is zero. |
boolean adjustDtr(String clanId, double delta) | Moves the DTR, kept between min-dtr and the clan's maximum. Crossing below zero does what a death crossing it does (the land opens, the raid EXP is charged); crossing back does what regeneration does. Does not freeze regeneration. false when the clan does not exist, dtr is off, or it already sat at the limit. |
Actions#
Each of these runs the same flow the player's own command runs, permission checks and messages included. They report nothing back: the player is told what happened, and a caller that needs to know reads the state afterwards.
| Method | What it does |
|---|---|
void createClan(Player player, String name) | Creates a clan led by the player, under the name given. |
void disbandClan(Player leader) | Disbands the leader's clan. |
void leaveClan(Player player) | Removes the player from their clan. |
void invite(Player inviter, Player target) | Invites a player to the inviter's clan. |
void kick(Player actor, UUID target) | Removes a member from the actor's clan. |
void transferLeader(Player leader, UUID newLeader) | Hands leadership to another member. |
void deposit(Player player, double amount) | Moves money from the player into the clan bank. |
void withdraw(Player player, double amount) | Moves money from the clan bank to the player. |
void sendClanChat(Player player, String message) | Sends a message to the player's clan chat. |
void setHome(Player player) | Sets the clan home to where the player is standing. |
void teleportHome(Player player) | Sends the player to their clan home. |
boolean joinClan(Player player, String clanId) | Joins the clan the way /clan join does — it has to be open or have invited them, and every refusal is told to the player. Returns whether they joined. |
void setRole(Player actor, UUID target, String roleId) | Gives a member one of the clan's ranks, as the role menu does: PROMOTE or DEMOTE by direction, and the actor has to outrank both the member and the rank. Leadership moves through transferLeader, not here. |
void openMenu(Player player) | Opens /clan: the clan's overview for a member, the create-or-join screen for anybody else. |
Types#
Every record is a snapshot taken at the moment of the lookup, not a live view. The plugin replaces its objects on every change, so ask again rather than holding one across ticks.
Clan#
id, name, leader, balance, open, friendlyFire, dtr, exp. Only the stored fields —
level, member count, maximum DTR and whether the clan is raidable are methods on the service.
ClanMember#
player, clanId, roleId. A player belongs to at most one clan, so this is the whole of their clan
identity. Resolve roleId with roleOf(UUID).
ClanRole#
id, clanId, name, weight (higher outranks lower), defaultRole, permissions.
has(String permission) tests one, case insensitively. These are the plugin's own clan permissions —
they gate clan actions, not server commands, and the set grows between releases: treat an unknown name
as one this version does not have rather than as an error. See Roles.
ClanStats#
clanId, kills, deaths, playTimeSeconds, summed across every member.
kdr() returns kills per death. A clan that has never died reports its kill count rather than
infinity, because a leaderboard has to sort it and a menu has to print it.
ClanClaim#
id, clanId, world, minX, minZ, maxX, maxZ, baseY. Edges are inclusive block
coordinates and the claim spans the full height of the world.
contains(int x, int z) tests a column; contains(Location location) tests a location, world
included.
ClanRelation#
NONE, SAME_CLAN, ALLY, RIVAL. The values never overlap: two clanmates are SAME_CLAN before
anything else.
DtrState#
| Value | Meaning |
|---|---|
NORMAL | Above zero and not regenerating: the ordinary state. |
FROZEN | Recently lost a member, so DTR is held still before it recovers. |
REGENERATING | Recovering towards its maximum. |
RAIDABLE | At or below zero: the clan's land can be raided. |
Events#
Bukkit events in net.exylia.lib.api.clans.event, part of the same public API: they and the methods
added above need exylia-api v1.133.0 or newer. Each fires on the thread that made the change, which on Folia is a region thread — schedule
anything that touches the world.
| Event | Fired | Cancellable |
|---|---|---|
ClanCreateEvent | A player is founding a clan, once every check has passed and before anything is written. getPlayer(), getName(). Cancelling writes and says nothing — tell the player why. | Yes |
ClanDisbandEvent | After a clan is gone, the leader's disband or an admin's. getClanId(), getName(), getActor() (null for an admin). No leave event per member. | No |
ClanMemberJoinEvent | After a player joins: open clan, accepted invite or forcejoin. Founding is not a join. getPlayer(), getClanId(). | No |
ClanMemberLeaveEvent | After a membership is deleted. getPlayer() (a UUID, may be offline), getClanId(), getReason() (LEFT, KICKED, BANNED), getActor() (null when they left or an admin removed them). | No |
ClanRoleChangeEvent | After a member's rank changes, from any route: promote, demote, role menu, setRole, a leadership transfer, a deleted rank's members falling back. getPlayer(), getPrevious(), getRole(), isPromotion(). | No |
ClanDtrChangeEvent | After the DTR moves: a death, regeneration, an admin, adjustDtr. getPrevious(), getDtr(), plus isRaidable(), becameRaidable() and recovered(). Usually asynchronous — regeneration runs off the main thread. | No |
ClanClaimEvent | A new claim has passed every check and is about to be paid for. getPlayer(), getClaim(), getPrice(). Cancelling charges and says nothing; the player keeps the selection. Resizing does not fire it. | Yes |
ClanUnclaimEvent | After a claim is removed, by unclaiming or a disband (just before ClanDisbandEvent). getClaim(). | No |
@EventHandler
public void onJoin(ClanMemberJoinEvent event) {
event.getPlayer().sendMessage("Welcome to your new clan.");
}What it does not expose#
The service is curated rather than a mirror of the plugin. The role editor, claim writes, ally and
rival management, bans and everything under /clanadmin are left out on purpose: those are the paths that keep the log, the broadcasts, the
caches and the WorldGuard regions in step, and a public method that skipped them would be a way to
corrupt a clan quietly.
Two things cover most of what is missing without any code. The exyliaclans: actions work from any
ExyliaLib menu in any plugin — see Menus — and every
%exyliaclans_…% placeholder resolves with or without PlaceholderAPI, so a scoreboard or a hologram
reads clan state directly. See Placeholders.
If something you genuinely need is still missing, ask on Discord.
The older reflection jar#
The build also ships ExyliaClans-API.jar, a standalone reflection bridge —
net.exylia.exyliaclans.api.ExyliaClansAPI with eighteen static methods and a ClanData record. It
predates the suite-wide API and reaches the plugin by reflection rather than through a service.
Everything it does, ClansService does with real types and without reflection. It is kept so that
plugins written against it keep working; write anything new against ClansService.
Something missing on this page? Tell us on Discord