Contenido generado con IA — puede contener errores.

ExyliaLib/Referenciaguide

API pública

Un solo artefacto por el que responde toda la suite: lo agregas, pides un service y escuchas sus eventos.

Página 50 de 549 min de lectura

Todos los plugins de Exylia publican su API de la misma forma. Hay un artefacto que agregar, una clase que llamar y una regla que respetar — y cuando lo sabes para uno, lo sabes para todos.

Agregarlo a tu proyecto#

La API se publica desde el repositorio de ExyliaLib a través de JitPack.

build.gradle
groovy
repositories {
    maven { url 'https://jitpack.io' }
}
 
dependencies {
    compileOnly 'com.github.DiGround-s.ExyliaLib:exylia-api:v1.321.2'
}
build.gradle.kts
kotlin
repositories {
    maven("https://jitpack.io")
}
 
dependencies {
    compileOnly("com.github.DiGround-s.ExyliaLib:exylia-api:v1.321.2")
}
pom.xml
xml
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>
 
<dependencies>
    <dependency>
        <groupId>com.github.DiGround-s.ExyliaLib</groupId>
        <artifactId>exylia-api</artifactId>
        <version>v1.321.2</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

La versión es el tag del release de ExyliaLib, con la v incluida — usa el tag del ExyliaLib que corre el servidor, o uno anterior. Los jars de fuentes y javadoc se publican junto al artefacto, así que tu IDE te muestra la documentación de cada método sin que salgas del editor.

El contrato tiene además una versión propia, hoy 3.1.0, que es la que cuentan los @since del javadoc (@since 1.10.0 en CratesService es exylia-api 1.10.0, no ExyliaLib 1.10.0). Ver Versionado.

compileOnly no es una preferencia de estilo

compileOnly — provided en Maven — es obligatorio, y meter el artefacto dentro de tu propio jar lo rompe. Estas clases ya viajan dentro de ExyliaLib.jar en el servidor. Una segunda copia en tu jar la carga tu classloader, con lo cual pasa a ser una clase distinta de la que implementan los plugins, y cada búsqueda devuelve vacío. No hay mensaje de error: sencillamente nunca encuentra nada.

Declarar la librería#

ExyliaLib tiene que habilitarse antes que tú, y tu plugin tiene que tener permiso para ver sus clases. Una línea en tu plugin.yml resuelve las dos cosas:

plugin.yml
yaml
depend: [ ExyliaLib ]

Usa softdepend si tu plugin igual tiene que cargar en un servidor sin ExyliaLib. En ese caso protege cada llamada con el Optional que la búsqueda ya te devuelve.

Pedir un service#

Todo pasa por net.exylia.lib.api.ExyliaAPI.

java
ExyliaAPI.get(ClansService.class)
         .flatMap(clans -> clans.clanOf(player.getUniqueId()))
         .ifPresent(clan -> player.sendMessage("Clan: " + clan.name()));
LlamadaPara qué
get(Service.class)Una integración blanda. Devuelve Optional, vacío si el plugin no está, está deshabilitado o todavía no terminó de habilitarse.
require(Service.class)Un depend duro contra el plugin que provee el service. Lanza IllegalStateException si no está.
isAvailable(Service.class)Un chequeo de disponibilidad, sin desenvolver nada.
Pídelo donde lo usas, no en onEnable

Un service se registra cuando habilita su plugin, y el orden de carga del servidor no lo eliges tú. Pedirlo dentro de tu propio onEnable puede perfectamente preguntar antes de que el otro plugin haya arrancado. Resuélvelo en el punto de uso — la búsqueda es leer un mapa — o desde ServerLoadEvent.

Escuchar eventos#

Los plugins que tienen algo a lo que valga la pena reaccionar publican eventos de Bukkit reales, en el mismo artefacto, bajo net.exylia.lib.api.<plugin>.event. Se registran como cualquier otro listener:

java
@EventHandler
public void onKitClaim(KitClaimEvent event) {
    if (isTournamentRunning()) event.setCancelled(true);
}

Cancelar significa que la acción no ocurre y que no se manda ningún mensaje — explicarle al jugador por qué te toca a ti. El javadoc de cada evento aclara si un evento no cancelado garantiza que la acción se completó: algunos sí, y otros van delante de un paso que todavía puede fallar, como un cobro o un warmup de teletransporte del que el jugador puede salir caminando.

Por qué el contrato vive en la librería#

Vale la pena saberlo, porque explica la regla del compileOnly y por qué hay un artefacto en vez de veinte.

Todos los plugins de Exylia se distribuyen como un loader: el servidor carga un jar chico que después desencripta el plugin real dentro de un classloader propio. La delegación de dependencias de Bukkit llega hasta ese loader y ahí se detiene — así que una interfaz que viaje adentro de un plugin es invisible para cualquier otro plugin, digan lo que digan los plugin.yml, y una copia enviada en los dos son dos clases sin relación.

ExyliaLib es el único jar que todos los plugins del servidor ya ven. Por eso el contrato vive ahí, y exylia-api son esas mismas clases empaquetadas para que compiles contra ellas.

Los services#

ServicePluginPaquete
AimTrainerServiceExyliaAimTrainernet.exylia.lib.api.aimtrainer
ArmorSkinServiceExyliaArmorSkinnet.exylia.lib.api.armorskin
ArmorTrimServiceExyliaArmorTrimsnet.exylia.lib.api.armortrims
ArrowsServiceExyliaArrowsnet.exylia.lib.api.arrows
CaptureServiceExyliaCapturenet.exylia.lib.api.capture
ChatServiceExyliaChatCosmeticsnet.exylia.lib.api.chatcosmetics
ClansServiceExyliaClansnet.exylia.lib.api.clans
ClassesServiceExyliaClassesnet.exylia.lib.api.classes
CosmeticsServiceExyliaChatCosmeticsnet.exylia.lib.api.chatcosmetics
CratesServiceExyliaCratesnet.exylia.lib.api.crates
EventsServiceExyliaEventsnet.exylia.lib.api.events
FfaServiceExyliaFFAnet.exylia.lib.api.ffa
HitEffectServiceExyliaHitEffectnet.exylia.lib.api.hiteffect
KillEffectServiceExyliaKillEffectnet.exylia.lib.api.killeffect
MarketServiceExyliaMarketnet.exylia.lib.api.market
MinesServiceExyliaMinesnet.exylia.lib.api.mines
PearlsServiceExyliaPearlsnet.exylia.lib.api.pearls
PracticeBotServiceExyliaPracticeBotnet.exylia.lib.api.practicebot
PracticeServiceExyliaPracticeCorenet.exylia.lib.api.practice
ProtectionsServiceExyliaProtectionsnet.exylia.lib.api.protections
SandBoxServiceExyliaSandBoxnet.exylia.lib.api.sandbox
ShieldsServiceExyliaShieldsnet.exylia.lib.api.shields
SpecialsServiceExyliaSpecialsnet.exylia.lib.api.specials
StaffServiceExyliaStaffnet.exylia.lib.api.staff
SurvivalServiceExyliaSurvivalCorenet.exylia.lib.api.survival
TableServiceExyliaTabletopnet.exylia.lib.api.tabletop
TotemTrainerServiceExyliaTotemTrainernet.exylia.lib.api.totemtrainer
—ExyliaTotemsnet.exylia.lib.api.totems

Algunos que conviene conocer desde acá, antes de abrir la página del plugin:

  • ExyliaTotems tiene eventos y ningún service. PlayerTotemHoldEvent se lanza antes de dejar en suspenso la muerte de un jugador para ver si llegó a tiempo a un tótem — un plugin que maneja sus propias muertes lo cancela — y PlayerTotemSaveEvent después de salvarlo. La muerte se cancela, así que ni PlayerDeathEvent ni EntityResurrectEvent llegan a un listener; estos dos son toda la API.
  • EventsService acepta minijuegos propios. net.exylia.lib.api.events.custom es el único lugar del artefacto donde un plugin declara algo para que otro lo corra en vez de leerlo: registerMinigame agrega un minijuego que ExyliaEvents arma y juega como uno de serie. Ver ExyliaEvents · Registrar tu propio minijuego.
  • MinesService.breakBlock es para plugins que rompen bloques en nombre de un jugador (un pico 3x3, un vein miner): dentro de una mina el evento de rotura del servidor siempre se cancela, así que pasa cada bloque por acá y rómpelo tú solo con MineBreakResult.UNCLAIMED. MineBlockDropEvent le entrega a un listener los drops que la mina está por dar, para cambiarlos o activar el auto-pickup.
  • MarketService.autoSell(player, drop) ofrece un drop al autosell del jugador; true significa que se vendió y no hay que darlo además. Eventos del mercado: MarketDealEvent (un trato cerrado), TradeRequestEvent, el cancelable SellWandUseEvent (cancélalo para un contenedor que decide él cuándo se abre) y MarketLogEvent, obsoleto — los plugins ahora registran en el log de staff de ExyliaLib.
  • SurvivalService también lleva lo que el survival core comparte con otros plugins: countStatistic suma a los contadores que leen misiones, rankings y temporadas, e isSettingEnabled lee los ajustes de un jugador, como los anuncios que silenció. Sus métodos de minas, llaves de cajas y autosell están obsoletos en favor de MinesService, CratesService y MarketService, y sus boosts de drops, experiencia y dinero en favor de Modifiers de ExyliaLib.
  • TableService describe las partidas jugador contra jugador de ExyliaTabletop: sus juegos (TableGameInfo), las partidas en vivo y las ofertas abiertas (copias TableMatch con sus TableSeat y un MatchState), el historial de un jugador (TableStats) y acciones que corren el mismo flujo que el comando del jugador (openLobby, createOffer, duel, join, forfeit) y vuelven antes de cobrar la entrada; cancel anula una partida y la reembolsa. Escucha TableMatchCreateEvent y TableMatchJoinEvent (cancelables, antes de cobrar nada), TableMatchStartEvent y TableMatchEndEvent para el resultado: el ganador, el EndReason, el premio y la comisión del servidor.

Lo que maneja un service#

Un service hace más que responder preguntas:

  • Acciones a pedido pasan por el mismo camino que el disparador propio del plugin — un efecto de kill sin kill, un kit dado como recompensa, un ítem especial activado sin tenerlo en la mano. Los filtros que pasa un disparador real siguen aplicando, y el javadoc de cada método dice cuáles se salta.
  • Abridores de menús abren una pantalla del jugador exactamente como lo hace su comando, para que un NPC, un cartel o un ítem del lobby lleven a ella.
  • Enums de resultado reemplazan a los booleanos donde una llamada puede rechazarse por más de un motivo (DuelStartResult, EnterResult, MineBreakResult, …).
  • Los eventos cancelables se lanzan después de los chequeos del propio plugin y antes de escribir nada, así que un evento cancelado no deja nada a medias.

Lo que no está#

Cada service está curado, no es un espejo de los internos del plugin. Los flujos de editor, las escrituras administrativas, todo lo que gaste el dinero de un jugador en su nombre y las filas crudas de configuración quedan afuera a propósito: un contrato público no se rompe a la ligera, así que lleva lo que una integración realmente necesita y nada que solo tuviera sentido dentro de una versión de un plugin.

Si te falta algo, pídelo en Discord en vez de recurrir a reflection — agregar un método a un service es un release menor, y reflection contra un plugin con loader no funciona de entrada.

Versionado#

exylia-api sigue versionado semántico de forma independiente de la versión de ExyliaLib, y su versión solo se mueve cuando se mueve el contrato. Los métodos y services nuevos son releases menores y nunca rompen a quien llama. Un método obsoleto sigue funcionando, normalmente reenviando a lo que lo reemplazó.

Un release mayor es raro y dice qué reemplazó. 3.0.0 quitó net.exylia.lib.api.betcore: su plugin pasó a ser ExyliaTabletop, cuyas partidas jugador contra jugador describe net.exylia.lib.api.tabletop (BetCoreService es ahora TableService, BetMatch es TableMatch, los BetMatch*Event son TableMatch*Event), y los juegos contra el servidor ya no forman parte del contrato.

Compilar contra un tag más viejo que el que corre el servidor está bien. Al revés no: un método agregado en una API más nueva no está en un ExyliaLib.jar más viejo, y en runtime no encuentra nada.

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