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.
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.
ExyliaAPI.get(ClassesService.class).ifPresent(classes ->
classes.classOf(player.getUniqueId())
.ifPresent(found -> player.sendMessage("Class: " + found.name())));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.
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().
El catálogo#
| Método | Qué 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étodo | Qué 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étodo | Qué 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étodo | Qué 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.
AbilityUseResult | Significado |
|---|---|
USED | La habilidad salió. |
NOT_IN_CLASS | El jugador no está en ninguna clase. Estar en warmup cuenta como ninguna. |
UNKNOWN_ABILITY | Su clase no tiene habilidad en ese trigger. |
ON_COOLDOWN | Sigue en cooldown. |
NOT_ENOUGH_ENERGY | Tiene menos de lo que cuesta. |
CANCELLED | Un handler de AbilityUseEvent la rechazó. |
Todo rechazo salvo CANCELLED ya se le dijo al jugador con las palabras del propio plugin.
Energía#
| Método | Qué 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.
| Evento | Cuándo | Cancelable |
|---|---|---|
ClassEquipEvent | Al 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. |
AbilityUseEvent | Cuando 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. |
ClassRemoveEvent | Despué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.
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