Referencedev

API

Reading clans, members, roles, land and DTR, 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())));

Adding it to your project

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.

Queries are cheap, actions are not

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.

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.

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.
`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.

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.

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.

`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.

What it does not expose

ExyliaClans publishes no events, and the service is curated rather than a mirror of the plugin. Menu openers, 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 fifteen 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