API
Leer clanes, miembros, rangos, terrenos y DTR, ajustar EXP y DTR, escuchar eventos de clan, y ejecutar los mismos flujos que ejecutan los comandos del jugador.
ClansService es la forma en que otro plugin lee y maneja ExyliaClans: quién está en qué clan, qué
puede hacer ahí, cómo progresa el clan, si su terreno se puede raidear ahora mismo — y, cuando lo
quieras, las mismas acciones que ejecutan los comandos del propio jugador.
ExyliaAPI.get(ClansService.class).ifPresent(clans ->
clans.clanOf(player.getUniqueId())
.ifPresent(clan -> player.sendMessage("Clan: " + clan.name())));Esta página es para desarrolladores de plugins. Si solo quieres datos de clan en un scoreboard o un holograma, usa los Placeholders. ExyliaAPI.get devuelve un Optional vacío mientras ExyliaClans no está en marcha, así que compruébalo en vez de dar por hecho que el service existe.
El artefacto, el repositorio y la línea del plugin.yml son los mismos para todos los plugins de
Exylia y están en la página de la API pública.
Antes de usarlo — el puente de clanes#
Si tu pregunta es ¿están estos dos en el mismo bando?, no quieres este service.
ExyliaClans se registra en el puente de clanes de ExyliaLib con prioridad 100 al activarse. Todo lo que
le pregunte a net.exylia.lib.clan.Clans recibe la respuesta de ExyliaClans, sin estar configurado
para ello y sin saber que ExyliaClans existe — por eso el friendly fire de una arena de ExyliaFFA, una
comprobación de equipo de ExyliaCapture y una de party de ExyliaPracticeCore ya coinciden con el clan
real del jugador.
if (Clans.areInSameClan(attacker.getUniqueId(), victim.getUniqueId())) return;
if (Clans.areAllied(attacker.getUniqueId(), victim.getUniqueId())) return;El puente es pequeño a propósito — mismo clan, aliados, rivales, el clan de un jugador, sus miembros y
sus miembros conectados — y responde igual en un servidor que use otro plugin de clanes distinto.
Úsalo para las relaciones. Usa ClansService para todo lo que el puente no modela: rangos, progresión,
estadísticas, DTR, terrenos y todas las acciones de abajo.
Todo lo que devuelve un valor lee de la caché del plugin y es seguro desde el redibujado de un menú o
desde un placeholder. Todo lo que devuelve void ejecuta el mismo flujo que el comando del propio
jugador — comprobaciones de permiso, cooldowns, escrituras en base de datos y los mensajes que ve el
jugador —, así que llámalo en el hilo principal y no más seguido de lo que un jugador podría
provocarlo.
Pertenencia#
| Método | Qué hace |
|---|---|
boolean isInClan(UUID player) | Si el jugador pertenece a algún clan. |
boolean isLeader(UUID player) | Si el jugador lidera su clan. |
Optional<Clan> clanOf(UUID player) | Su clan. Vacío si no está en ninguno. |
Optional<Clan> clanById(String clanId) | Un clan por id. Vacío si ningún clan lo tiene. |
Optional<Clan> clanByName(String name) | Un clan por el nombre que escriben los jugadores, sin distinguir mayúsculas. Vacío si ningún clan se llama así. |
Collection<Clan> allClans() | Todos los clanes, como snapshot de la caché. Vale para una tabla, sobra dentro de un bucle. |
Optional<ClanMember> memberOf(UUID player) | Su registro de pertenencia. Vacío si no está en ningún clan. |
List<ClanMember> membersOf(String clanId) | Todos los miembros de un clan. Vacío si el clan no existe. |
Optional<ClanRole> roleOf(UUID player) | Su rango dentro del clan. Vacío si no está en ninguno. |
String roleNameOf(UUID player) | El nombre del rango, para mostrar. Nunca null ni vacío: un jugador sin clan devuelve messages.yml → placeholders.none, que viene como {muted}None. |
int memberCount(UUID player) | Cuántos jugadores hay en el clan de ese jugador. 0 si no está en ninguno. |
List<ClanRole> roles(String clanId) | Todos los rangos del clan, del más ligero al más pesado. Vacía si el clan no existe. Los ids de rango son de un solo clan, así que de aquí saca setRole su id. |
Relaciones#
| Método | Qué hace |
|---|---|
boolean areAllies(String clanIdA, String clanIdB) | Si dos clanes son aliados. |
boolean areRivals(String clanIdA, String clanIdB) | Si dos clanes son rivales. |
boolean sameClan(UUID playerA, UUID playerB) | Si dos jugadores comparten clan. false si alguno no tiene clan, así que dos jugadores sin clan nunca cuentan como compañeros. |
boolean friendlyFireEnabled(UUID player) | Si su clan deja que los miembros se hagan daño. false si está apagado o si el jugador no tiene clan. |
int allyCount(UUID player) | Cuántos aliados tiene su clan. 0 si no está en ninguno. |
ClanRelation relation(UUID playerA, UUID playerB) | SAME_CLAN, ALLY, RIVAL o NONE, en una sola lectura de caché — lo bastante barato para cada golpe. Cuenta una rivalidad declarada por cualquiera de los dos lados. NONE si alguno no tiene clan. |
Progresión#
Todo lo que se deriva del nivel se calcula aquí en vez de guardarse en el record Clan, para que leer
un clan siga siendo un acierto de caché.
| Método | Qué hace |
|---|---|
int level(String clanId) | El nivel del clan. 1 si el clan no existe. |
long exp(String clanId) | La experiencia acumulada. |
long expForNextLevel(String clanId) | Lo que cuesta el siguiente nivel. 0 si el clan no existe o ya está en el nivel máximo. |
int maxMembers(String clanId) | El tope de miembros en su nivel actual, con los huecos dados con /clanadmin setslots. |
int maxAlliances(String clanId) | El tope de alianzas en su nivel actual. |
int maxRivals(String clanId) | El tope de rivalidades en su nivel actual. |
Estadísticas#
| Método | Qué hace |
|---|---|
Optional<ClanStats> stats(String clanId) | Las kills, muertes y tiempo jugado del clan. Vacío si el clan no existe. |
Raideo#
| Método | Qué hace |
|---|---|
boolean isRaidable(String clanId) | Si el terreno del clan se puede raidear ahora mismo. |
DtrState dtrState(String clanId) | En qué punto del ciclo de DTR está. NORMAL si el clan no existe o el servidor va sin DTR. |
double dtr(String clanId) | Su DTR actual. |
double maxDtr(String clanId) | El DTR máximo que puede alcanzar con su tamaño actual. Miembros entre members-per-point, nunca por debajo de 1.0. El nivel no entra en el cálculo. |
Terrenos#
| Método | Qué hace |
|---|---|
Optional<ClanClaim> claimOf(String clanId) | El terreno del clan. Vacío si no tiene ninguno. |
Ajustes#
Escrituras sin un jugador detrás, para un plugin que premia o castiga a un clan por algo que lleva él mismo. No se comprueba ningún permiso de rango ni se avisa a nadie más allá de lo que el plugin anuncia por su cuenta. Llámalos en el hilo principal.
| Método | Qué hace |
|---|---|
boolean addExp(String clanId, long amount) | Suma EXP, o la quita si es negativa, por el mismo camino que una baja o una muerte: un nivel cruzado se anuncia y los topes lo siguen. Nunca baja de cero ni pasa del último nivel. false si el clan no existe, levels está apagado o amount es cero. |
boolean adjustDtr(String clanId, double delta) | Mueve el DTR, entre min-dtr y el máximo del clan. Cruzar por debajo de cero hace lo que hace una muerte al cruzarlo (el terreno se abre, se cobra la EXP del raideo); volver a cruzar hace lo que hace la regeneración. No congela la regeneración. false si el clan no existe, dtr está apagado o ya estaba en el límite. |
Acciones#
Cada una de estas ejecuta el mismo flujo que el comando del propio jugador, con sus comprobaciones de permiso y sus mensajes. No informan nada de vuelta: al jugador se le dice qué pasó, y quien necesite saberlo lee el estado después.
| Método | Qué hace |
|---|---|
void createClan(Player player, String name) | Crea un clan liderado por el jugador, con el nombre dado. |
void disbandClan(Player leader) | Disuelve el clan del líder. |
void leaveClan(Player player) | Saca al jugador de su clan. |
void invite(Player inviter, Player target) | Invita a un jugador al clan de quien invita. |
void kick(Player actor, UUID target) | Expulsa a un miembro del clan de quien actúa. |
void transferLeader(Player leader, UUID newLeader) | Cede el liderazgo a otro miembro. |
void deposit(Player player, double amount) | Mueve dinero del jugador al banco del clan. |
void withdraw(Player player, double amount) | Mueve dinero del banco del clan al jugador. |
void sendClanChat(Player player, String message) | Manda un mensaje al chat del clan del jugador. |
void setHome(Player player) | Fija el home del clan donde está parado el jugador. |
void teleportHome(Player player) | Manda al jugador al home de su clan. |
boolean joinClan(Player player, String clanId) | Entra en el clan como lo hace /clan join: tiene que estar abierto o haberle invitado, y cada negativa se le dice al jugador. Devuelve si entró. |
void setRole(Player actor, UUID target, String roleId) | Da a un miembro uno de los rangos del clan, como el menú de rangos: PROMOTE o DEMOTE según la dirección, y el que actúa tiene que superar en peso al miembro y al rango. El liderazgo se mueve con transferLeader, no aquí. |
void openMenu(Player player) | Abre /clan: el resumen del clan para un miembro, la pantalla de crear o unirse para cualquier otro. |
Tipos#
Cada record es un snapshot del momento de la consulta, no una vista viva. El plugin reemplaza sus objetos en cada cambio, así que vuelve a preguntar en vez de guardarte uno entre ticks.
Clan#
id, name, leader, balance, open, friendlyFire, dtr, exp. Solo los campos guardados: el
nivel, el número de miembros, el DTR máximo y si el clan es raideable son métodos del service.
ClanMember#
player, clanId, roleId. Un jugador pertenece como mucho a un clan, así que esto es toda su
identidad de clan. Resuelve roleId con roleOf(UUID).
ClanRole#
id, clanId, name, weight (más alto manda sobre más bajo), defaultRole, permissions.
has(String permission) comprueba uno, sin distinguir mayúsculas. Son los permisos de clan del propio
plugin — regulan acciones dentro del clan, no comandos del servidor — y el conjunto crece entre
versiones: trata un nombre desconocido como uno que esta versión no tiene, no como un error. Ver
Rangos.
ClanStats#
clanId, kills, deaths, playTimeSeconds, sumados entre todos los miembros.
kdr() devuelve kills por muerte. Un clan que nunca murió devuelve su número de kills en vez de
infinito, porque una tabla tiene que ordenarlo y un menú tiene que imprimirlo.
ClanClaim#
id, clanId, world, minX, minZ, maxX, maxZ, baseY. Los bordes son coordenadas de bloque
inclusivas y el terreno abarca toda la altura del mundo.
contains(int x, int z) comprueba una columna; contains(Location location) comprueba una ubicación,
mundo incluido.
ClanRelation#
NONE, SAME_CLAN, ALLY, RIVAL. Los valores no se solapan: dos compañeros de clan son SAME_CLAN
antes que cualquier otra cosa.
DtrState#
| Valor | Significado |
|---|---|
NORMAL | Por encima de cero y sin regenerar: el estado habitual. |
FROZEN | Perdió un miembro hace poco, así que el DTR queda congelado antes de recuperarse. |
REGENERATING | Recuperándose hacia su máximo. |
RAIDABLE | En cero o por debajo: el terreno del clan se puede raidear. |
Eventos#
Eventos de Bukkit en net.exylia.lib.api.clans.event, parte de la misma API pública: ellos y los métodos
añadidos arriba necesitan exylia-api v1.133.0 o posterior. Cada uno se lanza en el hilo que hizo el
cambio, que en Folia es un hilo de región: programa todo lo que toque el mundo.
| Evento | Se lanza | Cancelable |
|---|---|---|
ClanCreateEvent | Un jugador está fundando un clan, una vez pasadas todas las comprobaciones y antes de escribir nada. getPlayer(), getName(). Cancelarlo no escribe ni dice nada: dile tú al jugador por qué. | Sí |
ClanDisbandEvent | Después de que un clan desaparece, lo disuelva el líder o un admin. getClanId(), getName(), getActor() (null para un admin). No hay evento de salida por miembro. | No |
ClanMemberJoinEvent | Después de que un jugador entra: clan abierto, invitación aceptada o forcejoin. Fundar no es entrar. getPlayer(), getClanId(). | No |
ClanMemberLeaveEvent | Después de borrar una membresía. getPlayer() (un UUID, puede estar desconectado), getClanId(), getReason() (LEFT, KICKED, BANNED), getActor() (null si se fue solo o lo sacó un admin). | No |
ClanRoleChangeEvent | Después de que cambia el rango de un miembro, por cualquier camino: ascenso, descenso, menú de rangos, setRole, un traspaso de liderazgo, los miembros de un rango borrado que pasan a otro. getPlayer(), getPrevious(), getRole(), isPromotion(). | No |
ClanDtrChangeEvent | Después de que se mueve el DTR: una muerte, la regeneración, un admin, adjustDtr. getPrevious(), getDtr(), más isRaidable(), becameRaidable() y recovered(). Normalmente asíncrono: la regeneración corre fuera del hilo principal. | No |
ClanClaimEvent | Un terreno nuevo pasó todas las comprobaciones y está a punto de pagarse. getPlayer(), getClaim(), getPrice(). Cancelarlo no cobra ni dice nada; el jugador conserva la selección. Redimensionar no lo lanza. | Sí |
ClanUnclaimEvent | Después de quitar un terreno, al liberarlo o en una disolución (justo antes de ClanDisbandEvent). getClaim(). | No |
@EventHandler
public void onJoin(ClanMemberJoinEvent event) {
event.getPlayer().sendMessage("Welcome to your new clan.");
}Lo que no expone#
El service está curado, no es un espejo del plugin. El editor de rangos, las escrituras de terreno, la gestión de aliados y rivales, los baneos y
todo lo que está bajo /clanadmin quedan afuera a propósito: esos son los caminos que mantienen en
sintonía el log, los avisos, las cachés y las regiones de WorldGuard, y un método público que se los
saltara sería una forma de corromper un clan en silencio.
Dos cosas cubren casi todo lo que falta sin escribir código. Las acciones exyliaclans: funcionan
desde cualquier menú de ExyliaLib, de cualquier plugin — ver Menús
— y todos los %exyliaclans_…% se resuelven con o sin PlaceholderAPI, así que un scoreboard o un
holograma leen el estado del clan directamente. Ver Placeholders.
Si de verdad te falta algo, pídelo en Discord.
El jar de reflexión antiguo#
La build publica además ExyliaClans-API.jar, un puente por reflexión independiente:
net.exylia.exyliaclans.api.ExyliaClansAPI, con dieciocho métodos estáticos y un record ClanData. Es
anterior a la API común de la suite y llega al plugin por reflexión en vez de por un service.
Todo lo que hace, ClansService lo hace con tipos reales y sin reflexión. Se mantiene para que los
plugins escritos contra él sigan funcionando; escribe lo nuevo contra ClansService.
¿Falta algo en esta página? Dínoslo en Discord