Contenido generado con IA — puede contener errores.

ExyliaArrows/ReferenciaActualizada en v1.7.1

API

Reproduce efectos, átalos a arcos y lee lo que tiene un jugador desde tu propio plugin.

Página 15 de 2210 min de lectura

ArrowsService es por donde otro plugin lee y maneja ExyliaArrows: el catálogo y sus categorías, el efecto que eligió el jugador, sus favoritos y su ajuste de partículas, los efectos ligados a los arcos, los efectos lanzados a demanda, los menús, los desbloqueos y las llaves de la caja.

java
ExyliaAPI.get(ArrowsService.class).ifPresent(arrows -> {
    arrows.select(player, "storm");
    arrows.effectItem("storm").ifPresent(item -> player.getInventory().addItem(item));
});
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. Lanzar un efecto, los menús, los desbloqueos, las llaves y ArrowEffectPlayEvent llegaron en exylia-api v1.133.0 y ExyliaArrows 1.4.0: compila contra esa etiqueta o una más nueva para alcanzarlos.

El servicio se registra en el ServicesManager de Bukkit cuando ExyliaArrows se activa. Trata un resultado vacío de ExyliaAPI.get como "este servidor no usa efectos de flecha", no como un fallo.

Todo se direcciona por id de efecto, comparado sin distinguir mayúsculas. Un id que el catálogo no declara no es un error — una recarga puede quitar uno mientras una caja todavía lo reparte —, así que las búsquedas devuelven vacío y las escrituras devuelven false.

MétodoQué hace
effects()Todos los efectos que declara el servidor, en el orden en que los dibuja el menú. Una foto: sirve para montar una tienda, sobra dentro de un bucle.
effect(String effectId)Un efecto como Optional<ArrowEffect>. Vacío cuando el catálogo no declara ese id.
exists(String effectId)Si el catálogo declara ese id.
categories()Todas las categorías, en el orden en que el menú dibuja sus pestañas.
category(String categoryId)Una categoría como Optional<ArrowCategory>. Vacío cuando el catálogo no declara ese id.
effectsIn(String categoryId)Los efectos de una categoría, en orden de menú. Vacío cuando la categoría no existe.

Permisos#

MétodoQué hace
canUse(Player, String effectId)Si puede usar el efecto.

Responde con la regla del propio servidor: el nodo del efecto, el de toda su categoría o su rareza, el comodín, o un desbloqueo de la caja o de la tienda. Una tienda que pregunta recibe la misma respuesta que daría el menú, no una comprobación cruda de nodo.

Lo que eligió el jugador#

MétodoQué hace
mode()De dónde salen los efectos que reproduce este servidor, como EffectMode.
selected(UUID player)Su id de efecto elegido, como Optional<String>. Vacío cuando no eligió ninguno, el menú está apagado, o su fila todavía se está leyendo.
select(Player, String effectId)Fija el efecto que lo acompaña. true cuando quedó guardado.
clear(Player)Le quita su propia elección, de vuelta al predeterminado de su rango. No es un "no quiero efecto": eso solo lo registra el jugador al quitar su efecto en el menú.
select fija, y no pide nodo

select fija en vez de alternar: llamarlo dos veces deja el efecto puesto. No pasa por permiso, porque un efecto entregado por una caja o una recompensa es del jugador aunque nunca se le concediera un nodo. Pregunta antes por canUse cuando sí quieras que decida el permiso.

Favoritos#

MétodoQué hace
favourites(UUID player)Los ids de efecto que marcó, en el orden en que los marcó. Vacío cuando no marcó ninguno o todavía se está leyendo.
isFavourite(UUID player, String effectId)Si un efecto está marcado.
toggleFavourite(Player, String effectId)Marca un efecto, o lo desmarca cuando ya lo estaba. true cuando el id nombraba un efecto que existe.
clearFavourites(Player)Desmarca todo.

La lista corta guarda el orden del jugador y no el del catálogo: la armó alguien, y reordenarla se lo quita. toggleFavourite es a propósito un alternador y no un par de métodos: la estrella es un solo control con dos estados, y quien tuviera que leer el estado primero competiría con el jugador que la está pulsando.

Visibilidad de partículas#

MétodoQué hace
visibility(UUID player)Quién ve ahora mismo sus partículas de flecha. ParticleVisibility.ALL cuando nunca lo cambió o todavía se está leyendo.
setVisibility(Player, ParticleVisibility)Guarda quién las ve.

Efectos en los objetos#

MétodoQué hace
boundTo(ItemStack bow)El id de efecto ligado a ese arco, ballesta o tridente, como Optional<String>. Vacío cuando no lleva ninguno.
bind(ItemStack bow, String effectId)Liga un efecto al arco, en el sitio, conservando todo lo demás que tenía. Se rechaza cuando el objeto no admite efectos, o cuando el efecto declara que no encaja en él.
unbind(ItemStack bow)Quita el efecto y no devuelve nada a cambio. true cuando había uno.
effectItem(String effectId)Una ficha de efecto lista para entregar, como Optional<ItemStack>. Vacío cuando el catálogo no declara ese efecto.
isEffectItem(ItemStack)Si un objeto es una de las fichas de efecto del plugin.

Pregunta isEffectItem antes de que una caja, una tienda o un intercambio traten un stack como botín normal: una ficha se dibuja como convenga a lo que lleva y no es el material que aparenta.

Lanzar un efecto#

MétodoQué hace
boolean play(String effectId, ArrowTrigger trigger, Location where, Player shooter, @Nullable Entity hit)Lanza un momento de un efecto en un sitio, como si hubiera un disparo allí. La flag de región, ArrowEffectPlayEvent y la visibilidad de cada observador siguen decidiendo; el arco, la elección del menú, los tipos de proyectil y el permiso se saltan, porque quien llama nombró el efecto. Exactamente el momento pedido: un HIT_ENTITY sobre un efecto que solo declara HIT no dibuja nada. false cuando no hay efecto con ese id, no dibuja nada en ese momento, la región lo silencia o un listener lo canceló. Llámalo en el hilo dueño de where.
boolean attach(Projectile projectile, String effectId)Hace que un proyectil lleve un efecto, como si se acabara de disparar con él — la ráfaga de una habilidad, una torreta, un hechizo dibujado como flecha. El lanzamiento suena donde está ahora, la estela lo sigue y el impacto suena donde cae; el efecto que ya llevara se reemplaza. El tirador tiene que ser un jugador. Llámalo justo después de crear el proyectil, en el hilo dueño de él.
boolean preview(Player viewer, String effectId)Muestra el efecto en el escenario de vistas previas, como hace el clic derecho del menú. No hace falta tenerlo, lo que lo convierte en el "pruébalo antes de comprarlo" de una tienda. false, avisando al jugador, cuando no hay escenario fijado.

ArrowTrigger es LAUNCH, TRAIL, HIT o HIT_ENTITY.

Menús#

MétodoQué hace
void openMenu(Player player)Abre el menú de efectos exactamente como /arrows, 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 bow se le dice al jugador que el menú está apagado. Seguro desde cualquier hilo.
void openCrate(Player player)Abre la caja exactamente como el comando y los bloques de caja: la pantalla que pregunta cuántas abrir y gasta llaves. Con la caja apagada se le dice al jugador. Seguro desde cualquier hilo.

Desbloqueos y llaves de la caja#

MétodoQué hace
boolean unlock(Player player, String effectId)Le da un efecto para siempre, como ganarlo en la caja — propiedad sin nodo de permiso, que canUse cuenta desde entonces. No elige nada ni da ningún objeto: sigue con select o effectItem para eso. false cuando no hay efecto con ese id, ya lo tiene así, o su fila todavía no llegó.
int keys(UUID player)Cuántas llaves 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.

ArrowEffectPlayEvent#

net.exylia.lib.api.arrows.event.ArrowEffectPlayEvent se dispara cuando todo lo demás ya aceptó que un momento debe sonar: el efecto dibuja algo en él y la región permite los efectos de flecha. Se dispara una vez por momento — el lanzamiento, el inicio de la estela, el impacto — para disparos reales y para play y attach por igual, y no se distinguen a propósito: una arena que quiere los efectos de flecha callados los quiere callados en ambos casos.

java
@EventHandler
public void onArrowEffect(ArrowEffectPlayEvent event) {
    if (event.getLocation().getWorld().getName().equals("lobby")) event.setCancelled(true);
}
MétodoQué devuelve
Player getPlayer()El tirador: de quién es el efecto.
@Nullable Entity getHitEntity()En qué cayó el disparo. null para un lanzamiento, una estela, un bloque o un lanzamiento que no nombró nada.
String getEffectId()El efecto a punto de sonar, normalizado.
ArrowTrigger getTrigger()Qué momento es.
Location getLocation()Dónde suena; para una estela, donde empieza la línea. Una copia: cambiarla no mueve nada.

Cancelarlo no dibuja nada ni dice nada; el disparo vuela y cae igual. Cancelar un TRAIL para toda la línea de ese disparo. El evento se llama en el hilo dueño de la ubicación, que en Folia es un hilo de región y no el principal.

Tipos#

ArrowEffect — id, categoryId, name (con los códigos de color dentro), permission (el nodo que concede ese efecto suelto) y description (las palabras del dueño, con sus saltos de línea). Lo que el efecto dibuja no está a propósito: es una secuencia compilada que pertenece al plugin que la reproduce.

ArrowCategory — id, name, permission. Su nodo concede de una vez todos los efectos que contiene, que es como se vende un rango como "todos los efectos de tormenta" sin listarlos uno a uno.

EffectMode — de dónde sale el efecto que suena: PLAYER (solo lo que eligió el jugador; el arco no lleva nada), BOW (solo lo ligado al arco; el menú no elige nada) o BOTH. usesBows() y usesMenu() responden sin switch. Vale la pena preguntarlo antes de escribir nada: la mitad que un servidor no usa devuelve false o vacío en lugar de lanzar, así que una integración escrita para las dos funciona en cualquiera.

ParticleVisibility — ALL, NONE, SELF_ONLY, OTHERS_ONLY. Es un ajuste del jugador, no del servidor. La etiqueta con la que se muestra cada modo la escribe el dueño del servidor y no viaja aquí: una constante es una identidad, no un nombre.

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: un jugador que todavía no terminó de cargar se lee como uno que no eligió nada, que es por lo que aquí toda lectura responde en vez de esperar. Todo lo que cambia la elección de un jugador escribe en la base de datos, así que llama a eso desde el hilo principal y no más seguido de lo que podría un jugador.

Lo que no expone#

Un evento, ArrowEffectPlayEvent. Lo que dibuja un efecto (su secuencia compilada) queda fuera a propósito, igual que la configuración y las clases internas del plugin: 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