Contenido generado con IA — puede contener errores.

ExyliaHitEffect/ReferenciadevActualizada en v1.6.2

API

Qué puede hacer otro plugin con los efectos de golpe: el catálogo, lo que eligió un jugador, lo que lleva un arma, lanzar uno a demanda, los menús y la caja.

Página 14 de 2111 min de lectura

HitEffectService lee el catálogo de ExyliaHitEffect, cambia lo que lleva un jugador, ata efectos a las armas, lanza un efecto a demanda, abre los menús y entrega efectos y llaves de caja. Con una sola búsqueda tienes toda la superficie.

java
ExyliaAPI.get(HitEffectService.class).ifPresent(effects ->
    effects.chosenEffect(player.getUniqueId())
           .ifPresent(effect -> player.sendMessage("Hit effect: " + effect.name())));

Un resultado vacío en la búsqueda significa que los efectos de golpe no forman parte de este servidor, no que algo haya fallado.

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.

Todo funciona con ids#

Los efectos y las categorías se nombran por las claves que declara effects.yml. Los ids están normalizados — minúsculas, letras, dígitos y guiones bajos — y se comparan sin importar mayúsculas, así que el id que una tienda guardó el mes pasado sigue resolviendo después de que el dueño lo reescribiera con otras mayúsculas.

Aquí no se comprueba ningún permiso

Un plugin que llama esto ya decidió que el jugador puede tener el efecto: una caja abierta, un rango comprado, una recompensa reclamada. Que lo anule un nodo que el comprador todavía no tiene no es lo que pidió. mayUse está para quien sí quiera la comprobación, en sus propios términos.

MétodoQué hace
List<HitEffect> effects()Todos los efectos declarados, en el orden del archivo. Es una foto: sirve para armar una página de tienda, sobra dentro de un bucle que podría pedir un id.
Optional<HitEffect> effect(String effectId)Un efecto por id. Vacío si el archivo no declara ninguno con ese id.
boolean effectExists(String effectId)Si el efecto existe. La forma barata de effect, para validar lo que escribió un jugador o lo que nombró una config.
List<HitEffectCategory> categories()Todas las categorías, en el orden en que se dibujan las pestañas.
Optional<HitEffectCategory> category(String categoryId)Una categoría por id. Vacío si el archivo no declara ninguna con ese id.
List<HitEffect> effectsIn(String categoryId)Los efectos de una categoría, en el orden en que se dibujan. Vacío si la categoría no existe.
boolean mayUse(Player player, String effectId)Si un jugador puede usar un efecto: su propio permiso, el de todos los efectos a la vez, el de su categoría entera o el de su rareza, o un desbloqueo de la caja o de la tienda. Un id desconocido nunca está permitido, así que un id viejo se lee como bloqueado y no como gratis.

Lo que eligió un jugador#

Todo lo que recibe un UUID lee lo que hay en memoria de un jugador conectado. Alguien cuya fila todavía no llegó responde como si no hubiera elegido nada, en vez de dejar al que llama esperando a una base de datos.

MétodoQué hace
Optional<HitEffect> chosenEffect(UUID player)El efecto que eligió en el menú. Vacío si no eligió ninguno.
boolean chooseEffect(Player player, String effectId)Pone el efecto que reproducen sus golpes. false si ningún efecto lleva ese id, y entonces no se cambió nada.
void clearEffect(Player player)Lo deja sin efecto elegido.
List<HitEffect> favourites(UUID player)Los efectos que marcó, en el orden en que los marcó — el suyo, no el del catálogo. Vacío si no tiene ninguno o no está cargado.
boolean isFavourite(UUID player, String effectId)Si marcó un efecto.
boolean toggleFavourite(Player player, String effectId)Marca un efecto, o lo desmarca si ya estaba marcado. false si ningún efecto lleva ese id.
void clearFavourites(Player player)Vacía sus favoritos.

Lo que lleva un arma#

MétodoQué hace
boolean weaponBindingEnabled()Si en este servidor se reproducen los efectos atados a las armas. Si no, atar uno escribe un valor que nunca va a sonar — así que pregunta antes de ofrecerlo.
boolean playerChoiceEnabled()Si en este servidor se reproduce el efecto que el jugador eligió en el menú.
boolean fitsWeapon(String effectId, Material weapon)Si el efecto acepta ese tipo de objeto. Un efecto que no declara armas encaja con todas.
Optional<HitEffect> boundEffect(ItemStack weapon)El efecto que lleva un arma. Vacío si no lleva ninguno.
HitEffectBindResult bind(ItemStack weapon, String effectId)Ata un efecto. El objeto se modifica en el sitio, y solo después de que pasen todas las comprobaciones.
HitEffectBindResult unbind(ItemStack weapon)Le quita el efecto sin devolver nada, para quien entrega la ficha por su cuenta. También en el sitio.
Optional<ItemStack> token(String effectId, Player viewer)El objeto que entrega una caja o una tienda: aplicarlo a un arma ata el efecto. Se dibuja para ese jugador, porque el nombre y el lore llevan placeholders. Vacío si ningún efecto lleva ese id.
ItemStack remover(Player viewer)El removedor. Aplicarlo a un arma le quita el efecto y devuelve la ficha.

bind y unbind escriben sobre la copia del stack que les pasas. Pásales una copia y no un objeto que siga dentro de una vista de inventario abierta: lo que ve el jugador se redibuja cuando devuelves el stack a su sitio.

Lanzar un efecto#

MétodoQué hace
boolean play(String effectId, Location where, Player attacker, @Nullable LivingEntity victim)Lanza un efecto en un lugar, como si allí hubiera caído un golpe. La bandera de región, HitEffectPlayEvent y la visibilidad de cada espectador siguen decidiendo; el arma, la elección del menú, la lista de mobs y el permiso se saltan, porque quien llama ya nombró el efecto. Un golpe real se lanza un bloque por encima de los pies de la víctima, sobre el cuerpo. victim es el cuerpo sobre el que dibujan sus pasos, o null para ninguno. false si ningún efecto lleva ese id, no dibuja nada, la región lo silencia o un listener lo canceló.
boolean playFor(Player attacker, LivingEntity victim)Lanza el efecto que gana un golpe, decidiendo todo lo que decide un golpe real: si ese tipo de víctima lanza efectos, y el arma y la elección del menú del atacante según el modo del servidor. false si el golpe no gana nada, o si play habría respondido false.
boolean preview(Player viewer, String effectId)Muestra el efecto como dice preview.mode: en el escenario de previsualización del servidor, a solas, devolviendo al jugador, o prestado para probarlo en los maniquíes — no hace falta tenerlo, así que sirve de "prueba antes de comprar" para una tienda. false si no hay escenario ni maniquí, o si al jugador le falta exyliahiteffect.preview, y se le avisa.

playFor sirve para daño que el servidor nunca reporta como un golpe de ese jugador: una habilidad, un arma personalizada, un dash. Un golpe que el servidor sí reporta ya lanza su efecto, así que llamar a playFor también para él lo lanza dos veces. En cualquier caso un atacante lanza como mucho cinco efectos por segundo.

El hilo dueño del lugar

Llama a play en el hilo dueño de where y a playFor en el dueño de la víctima: el hilo principal en Paper, el hilo de región en Folia. preview corresponde al hilo dueño del jugador.

Menús#

MétodoQué hace
void openMenu(Player player)Abre el selector de efectos igual que /hiteffect (el menú de inventario o el selector 3D, según menu.style), para un NPC, un objeto del hub o una tienda. Si la fila del jugador no está en memoria se lee antes, así que el menú puede aparecer un momento después de la llamada. En un servidor weapon se le avisa de que el menú está apagado. Seguro desde cualquier hilo.
void openCrate(Player player)Abre la caja igual que el comando y los bloques de caja: la pantalla que pregunta cuántas abrir y gasta las llaves. Con la caja apagada se le avisa. Seguro desde cualquier hilo.

Tener efectos, y llaves de caja#

MétodoQué hace
boolean unlock(Player player, String effectId)Le da un efecto para siempre, igual que ganarlo en la caja — posesión sin nodo de permiso, que mayUse cuenta desde entonces. No elige nada ni entrega ningún objeto: sigue con chooseEffect o token para eso. false si ningún efecto lleva ese id, la caja ya se lo dio o su fila todavía no llegó; no se cambió nada.
int keys(UUID player)Cuántas llaves de caja tiene. 0 si no tiene ninguna o su fila todavía no llegó.
void addKeys(Player player, int keys)Da llaves, o las quita con un número negativo — así paga una tirada una tienda, un voto o una misión. La cuenta nunca baja de cero. Un jugador cuya fila todavía no llegó queda igual.

HitEffectPlayEvent#

net.exylia.lib.api.hiteffect.event.HitEffectPlayEvent se lanza cuando todo lo demás ya aceptó que un efecto debe sonar: existe, dibuja algo y la región permite efectos de golpe. Se lanza para los golpes que reporta el servidor y para play y playFor por igual, y a propósito no se distinguen — una arena que quiere los efectos callados los quiere callados en los dos casos.

java
@EventHandler
public void onHitEffect(HitEffectPlayEvent event) {
    if (event.getLocation().getWorld().getName().equals("lobby")) event.setCancelled(true);
}
MétodoQué devuelve
Player getPlayer()El atacante: de quién es el efecto.
@Nullable LivingEntity getVictim()Sobre qué se lanza. null si un plugin lo lanzó en un lugar y no sobre un cuerpo.
String getEffectId()El efecto que va a sonar, normalizado.
Location getLocation()Dónde se lanza. Una copia: cambiarla no mueve nada.

Cancelarlo no dibuja nada ni dice nada; el golpe en sí queda intacto. El evento se llama en el hilo dueño del lugar, que en Folia es un hilo de región y no el principal.

HitEffectBindResult#

Todas las comprobaciones corren antes de escribir nada, así que cualquier resultado que no sea BOUND o UNBOUND significa que los dos objetos quedaron exactamente como estaban. isSuccess() es cierto para esos dos y para nada más.

ValorSignificado
BOUNDEl arma ahora lleva el efecto.
UNBOUNDEl arma ya no lleva ningún efecto.
NOT_A_WEAPONEl objeto no es algo a lo que se pueda atar un efecto.
WRONG_WEAPONEs un arma, pero no una con la que este efecto declare encajar.
UNKNOWN_EFFECTNingún efecto lleva ese id, que es también como se lee un id viejo.
ALREADY_BOUNDEl arma ya lleva un efecto; desátalo antes de atar otro.
NO_EFFECTEl arma no lleva ningún efecto, así que no había nada que quitar.
FAILEDRechazado por un motivo que este contrato no nombra.
Escribe una rama por defecto

Hoy nada produce FAILED. Está para que un motivo que se agregue más adelante dentro del plugin te llegue como un valor que puedes manejar, y no como una excepción lanzada contra quien haya preguntado — que en un servidor vivo es un plugin de terceros sin forma de recuperarse. Maneja los resultados que te importan y deja que el resto caiga en una sola rama.

Los records#

HitEffect lleva id(), categoryId(), name(), icon(), description(), priority() y permission() — la descripción con las palabras del archivo, el icono tal como lo nombra el archivo, y el permiso que concede ese efecto suelto, para que una tienda pueda venderlo sin saber cómo se arma el nodo.

HitEffectCategory lleva id(), name(), icon(), priority() y permission(). Su permiso concede todos los efectos de la categoría de una vez, que es lo que permite vender un rango como "todos los efectos infernales" en vez de como una lista de ids que crece cada vez que el dueño agrega uno.

Los dos son fotos de lo que decía el archivo cuando preguntaste. Una recarga reemplaza el catálogo entero, así que un efecto guardado de una recarga a otra es la descripción vieja de un id que quizá ya no exista — vuelve a pedirlo en vez de guardarlo.

El plugin gemelo#

KillEffectService es el mismo contrato para los efectos que se reproducen al matar. Los dos son idénticos en forma a propósito: mismos nombres de método, mismo orden, mismos resultados. Una integración escrita contra uno se pasa al otro cambiando los tipos.

Lo que no expone#

Lo que el efecto dibuja de verdad — los pasos de partículas que compila el motor de secuencias — no está aquí. Es la implementación de esa versión del efecto, cambia cada vez que el dueño edita una línea, y no significa nada fuera del plugin que lo reproduce. El editor in-game y las escrituras administrativas quedan afuera por lo mismo: un contrato público no se puede romper después, así que lleva lo que una integración realmente necesita y nada que solo tuviera sentido dentro de una versión.

Si te falta algo, pídelo en Discord.

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