Contenido generado con IA — puede contener errores.

ExyliaClasses/ReferenciadevActualizada en v1.1.0

API

Leer el catálogo de clases y qué lleva puesto un jugador, usar habilidades y mover energía a demanda, y los tres eventos de clase.

Página 13 de 208 min de lectura

ClassesService es por donde otro plugin lee y maneja ExyliaClasses: el catálogo de clases, qué puede hacer y qué gasta cada una, y qué es un jugador ahora mismo. También puede lanzar una habilidad sin su objeto y dar o quitar energía, y tres eventos dejan a un plugin rechazar una clase o una habilidad y enterarse de cuándo termina una clase.

java
ExyliaAPI.get(ClassesService.class).ifPresent(classes ->
    classes.classOf(player.getUniqueId())
           .ifPresent(found -> player.sendMessage("Class: " + found.name())));
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.

Las clases se direccionan por id de clase: el nombre del archivo de la clase, en minúsculas.

Una clase se lleva puesta, no se elige

Un jugador está en una clase porque lo dice su armadura. Aquí nada asigna una directamente: apply le pide al plugin entrar en una clase igual que si se equipara la armadura, con su mensaje de rechazo y su warmup, y la clase termina sola en cuanto se quita una pieza. Un plugin que quiere a alguien en una clase le da la armadura que nombra PlayerClass.equipment().

MétodoQué hace
classes()Todas las clases que declara el servidor. Una foto: sirve para montar un menú, sobra dentro de un bucle.
classById(String classId)Una clase como Optional<PlayerClass>. Vacío cuando el catálogo no declara ese id.
exists(String classId)Si el catálogo declara ese id.
abilities(String classId)Qué puede hacer la clase. Vacío cuando la clase no existe o no tiene habilidades.
energy(String classId)El recurso que gasta, como Optional<ClassEnergy>. Vacío cuando la clase no existe o no gasta nada.

Permisos#

MétodoQué hace
canUse(Player, String classId)Si puede entrar en la clase. false cuando la clase no existe.

Responde con la regla del propio servidor, así que una clase que el dueño dejó abierta vale para todos en vez de rechazarse por falta de un nodo que nadie declaró.

Qué es un jugador#

MétodoQué hace
isInClass(UUID player)Si ahora mismo está en una clase.
classOf(UUID player)Su clase como Optional<PlayerClass>. Vacío cuando no está en ninguna.
energyOf(UUID player)Cuánta energía tiene ahora mismo. 0 cuando no está en ninguna clase o su clase no gasta nada.
marks(UUID player)Cuántas marcas lleva. Cero es el estado normal.
isMarked(UUID player)Si está marcado.
warmingUp(Player)La clase en la que está entrando, como Optional<PlayerClass>. Vacío cuando no está en warmup.
classForEquipment(Player)La clase que nombra su armadura actual, esté o no en ella. Vacío cuando no nombra ninguna.

energyOf sube sola entre llamadas, al ritmo de recarga de la propia clase: léela al dibujar en vez de cachearla. isMarked no es lo mismo que marks por encima de cero: una marca también pertenece al arma que la puso, y la que se queda sin su arma deja de contar. Las marcas las pone en un jugador el arma de otro, y esa misma arma las gasta.

Entre ponerse la armadura y que la clase surta efecto hay un retraso que configura el dueño, y quien está en él todavía no está en ninguna clase: por eso existe warmingUp, y por eso classForEquipment es lo que distingue "lleva la armadura equivocada" de "está en warmup". classForEquipment es además lo que pregunta una vista previa: en qué convertiría este set a alguien, antes de que se lo ponga.

Acciones#

MétodoQué hace
apply(Player, String classId)Le pide al jugador entrar en una clase. No devuelve nada.
remove(Player)Lo saca de su clase, con sus efectos pasivos, su energía, sus marcas y sus barras. Los cooldowns de habilidades siguen corriendo.
useAbility(Player, Material trigger)Usa una de sus habilidades, como lo haría el clic derecho con su objeto. Devuelve un AbilityUseResult.

apply corre el mismo flujo que equipar la armadura: el permiso se comprueba y se rechaza en voz alta, y el warmup corre antes de que la clase surta efecto, así que cuando la llamada vuelve todavía no pasó nada — por eso no informa nada de vuelta. Lee classOf después si necesitas saberlo. La clase igual termina en cuanto la armadura del jugador deja de nombrarla, así que esto no es una forma de meter a alguien en una clase para la que no está vestido.

remove no toca la armadura, así que volver a ponerse una pieza lo mete otra vez en la clase.

useAbility corre el flujo entero de un clic: cooldown y energía se comprueban y se rechazan en voz alta, se dispara AbilityUseEvent, se gasta la energía, arranca el cooldown y los efectos caen sobre quien alcance la habilidad. Lo único que no hace es consumir un objeto, y el jugador no necesita sostener ninguno. El trigger es el ClassAbility.trigger() de la habilidad. Llámalo desde el hilo dueño del jugador.

AbilityUseResultSignificado
USEDLa habilidad salió.
NOT_IN_CLASSEl jugador no está en ninguna clase. Estar en warmup cuenta como ninguna.
UNKNOWN_ABILITYSu clase no tiene habilidad en ese trigger.
ON_COOLDOWNSigue en cooldown.
NOT_ENOUGH_ENERGYTiene menos de lo que cuesta.
CANCELLEDUn handler de AbilityUseEvent la rechazó.

Todo rechazo salvo CANCELLED ya se le dijo al jugador con las palabras del propio plugin.

Energía#

MétodoQué hace
giveEnergy(Player, double amount)Suma energía, nunca por encima del max de la clase. false si no está en ninguna clase o esta no gasta energía.
spendEnergy(Player, double amount)Quita energía, toda o nada. false si tiene menos, no está en ninguna clase o esta no gasta energía.

Los dos lanzan una excepción con una cantidad negativa y redibujan la barra de energía. La energía se recarga cada tick en el hilo del propio jugador, así que llámalos desde ese hilo: un comando, un listener de ese jugador o una tarea programada sobre él. spendEnergy es lo que usa un plugin que cobra energía por algo propio.

Eventos#

Los tres viven en net.exylia.lib.api.classes.event, llevan getPlayer() y getPlayerClass(), y se llaman en el hilo dueño del jugador, que en Folia es el hilo de su región.

EventoCuándoCancelable
ClassEquipEventAl final del warmup, justo cuando la clase empezaría, antes de aplicar nada.Sí: el jugador queda vestido para la clase pero fuera de ella hasta que cambie su armadura.
AbilityUseEventCuando un uso saldría: en la clase, sin cooldown, con la energía. Se dispara con el clic y con useAbility. getAbility() es el ClassAbility.Sí: no se gasta energía, no hay cooldown, ni efecto, ni objeto consumido.
ClassRemoveEventDespués de quitar la clase, por armadura, muerte, salida, recarga o remove. classOf ya responde vacío.No. Un apagado del servidor no lo dispara.

Cancelar no le dice nada al jugador: se espera que el handler que rechazó le explique por qué. El jugador de ClassRemoveEvent puede estar saliendo, así que comprueba isOnline() antes de escribirle.

Tipos#

PlayerClass — id, name (con los códigos de color dentro), permission y equipment, un mapa de EquipmentSlot a Material. gated() responde si entrar en la clase necesita nodo siquiera; un permission vacío significa que la clase está abierta a todos. equipment es parte de la forma pública a propósito: un plugin de kits que reparte esas piezas repartió la clase, y uno que quita una pieza se la quitó.

ClassAbility — name, trigger (el Material que el jugador sostiene para usarla, y también su clave dentro de la clase, así que no hay dos habilidades que compartan uno), type, cooldown en segundos, energyCost y radius en bloques. Lo que la habilidad aplica de verdad queda fuera: son líneas que el dueño escribe en la sintaxis del plugin. Lo que hay aquí es lo que necesita un menú, una tienda o un HUD para describir una habilidad sin reproducirla.

ClassEnergy — name (maná, foco, furia), symbol, max y regenPerTick. Pertenece a la clase y no al jugador: todos los arqueros tienen el mismo techo y el mismo ritmo de recarga, y lo que tiene uno concreto ahora mismo es energyOf. regenPerTick está para que una barra se pueda predecir entre actualizaciones en vez de consultarla.

AbilityType — a quién alcanza una habilidad: SELF, TO_CLAN, TO_ALLY, TO_ENEMY, TO_CLAN_AND_ALLY. Los valores que saben de clanes no significan nada en un servidor sin clanes: ahí no encuentran a nadie y la habilidad se comporta como SELF. SELF ignora el radius.

Las consultas son baratas, las acciones no

Todo lo que devuelve un valor lee la caché del plugin y es seguro desde un redibujado de menú o un placeholder. apply, remove y useAbility corren el mismo flujo que corre un cambio de equipo o un clic del propio jugador — efectos de poción, cooldowns, barras, los mensajes que ve —, así que llama a eso desde el hilo principal.

Lo que no expone#

Lo que aplica de verdad una habilidad, los efectos pasivos, los internos de armas y marcas y las filas crudas de configuración quedan fuera a propósito: un contrato público no se puede romper después, así que lleva lo que una integración necesita y nada que solo tuviera sentido dentro de una versión.

Si de verdad te falta algo, pídelo en Discord.

¿Falta algo en esta página? Dínoslo en Discord