Contenido generado con IA — puede contener errores.

ExyliaClans/ReferenciaActualizada en v1.4.0

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.

Página 22 de 2912 min de lectura

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.

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

Agregarlo a tu proyecto

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.

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

Las consultas son baratas, las acciones no

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étodoQué 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étodoQué 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étodoQué 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étodoQué hace
Optional<ClanStats> stats(String clanId)Las kills, muertes y tiempo jugado del clan. Vacío si el clan no existe.

Raideo#

MétodoQué 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étodoQué 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étodoQué 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étodoQué 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#

ValorSignificado
NORMALPor encima de cero y sin regenerar: el estado habitual.
FROZENPerdió un miembro hace poco, así que el DTR queda congelado antes de recuperarse.
REGENERATINGRecuperándose hacia su máximo.
RAIDABLEEn 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.

EventoSe lanzaCancelable
ClanCreateEventUn 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í
ClanDisbandEventDespué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
ClanMemberJoinEventDespués de que un jugador entra: clan abierto, invitación aceptada o forcejoin. Fundar no es entrar. getPlayer(), getClanId().No
ClanMemberLeaveEventDespué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
ClanRoleChangeEventDespué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
ClanDtrChangeEventDespué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
ClanClaimEventUn 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í
ClanUnclaimEventDespués de quitar un terreno, al liberarlo o en una disolución (justo antes de ClanDisbandEvent). getClaim().No
java
@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