API pública
Un solo artefacto por el que responde toda la suite: lo agregas, pides un service y escuchas sus eventos.
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.
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.DiGround-s.ExyliaLib:exylia-api:v1.321.2'
}repositories {
maven("https://jitpack.io")
}
dependencies {
compileOnly("com.github.DiGround-s.ExyliaLib:exylia-api:v1.321.2")
}<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 — 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:
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.
ExyliaAPI.get(ClansService.class)
.flatMap(clans -> clans.clanOf(player.getUniqueId()))
.ifPresent(clan -> player.sendMessage("Clan: " + clan.name()));| Llamada | Para 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. |
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:
@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#
| Service | Plugin | Paquete |
|---|---|---|
AimTrainerService | ExyliaAimTrainer | net.exylia.lib.api.aimtrainer |
ArmorSkinService | ExyliaArmorSkin | net.exylia.lib.api.armorskin |
ArmorTrimService | ExyliaArmorTrims | net.exylia.lib.api.armortrims |
ArrowsService | ExyliaArrows | net.exylia.lib.api.arrows |
CaptureService | ExyliaCapture | net.exylia.lib.api.capture |
ChatService | ExyliaChatCosmetics | net.exylia.lib.api.chatcosmetics |
ClansService | ExyliaClans | net.exylia.lib.api.clans |
ClassesService | ExyliaClasses | net.exylia.lib.api.classes |
CosmeticsService | ExyliaChatCosmetics | net.exylia.lib.api.chatcosmetics |
CratesService | ExyliaCrates | net.exylia.lib.api.crates |
EventsService | ExyliaEvents | net.exylia.lib.api.events |
FfaService | ExyliaFFA | net.exylia.lib.api.ffa |
HitEffectService | ExyliaHitEffect | net.exylia.lib.api.hiteffect |
KillEffectService | ExyliaKillEffect | net.exylia.lib.api.killeffect |
MarketService | ExyliaMarket | net.exylia.lib.api.market |
MinesService | ExyliaMines | net.exylia.lib.api.mines |
PearlsService | ExyliaPearls | net.exylia.lib.api.pearls |
PracticeBotService | ExyliaPracticeBot | net.exylia.lib.api.practicebot |
PracticeService | ExyliaPracticeCore | net.exylia.lib.api.practice |
ProtectionsService | ExyliaProtections | net.exylia.lib.api.protections |
SandBoxService | ExyliaSandBox | net.exylia.lib.api.sandbox |
ShieldsService | ExyliaShields | net.exylia.lib.api.shields |
SpecialsService | ExyliaSpecials | net.exylia.lib.api.specials |
StaffService | ExyliaStaff | net.exylia.lib.api.staff |
SurvivalService | ExyliaSurvivalCore | net.exylia.lib.api.survival |
TableService | ExyliaTabletop | net.exylia.lib.api.tabletop |
TotemTrainerService | ExyliaTotemTrainer | net.exylia.lib.api.totemtrainer |
| — | ExyliaTotems | net.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.
PlayerTotemHoldEventse 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 — yPlayerTotemSaveEventdespués de salvarlo. La muerte se cancela, así que niPlayerDeathEventniEntityResurrectEventllegan a un listener; estos dos son toda la API. EventsServiceacepta minijuegos propios.net.exylia.lib.api.events.customes el único lugar del artefacto donde un plugin declara algo para que otro lo corra en vez de leerlo:registerMinigameagrega un minijuego que ExyliaEvents arma y juega como uno de serie. Ver ExyliaEvents · Registrar tu propio minijuego.MinesService.breakBlockes 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 conMineBreakResult.UNCLAIMED.MineBlockDropEventle 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;truesignifica que se vendió y no hay que darlo además. Eventos del mercado:MarketDealEvent(un trato cerrado),TradeRequestEvent, el cancelableSellWandUseEvent(cancélalo para un contenedor que decide él cuándo se abre) yMarketLogEvent, obsoleto — los plugins ahora registran en el log de staff de ExyliaLib.SurvivalServicetambién lleva lo que el survival core comparte con otros plugins:countStatisticsuma a los contadores que leen misiones, rankings y temporadas, eisSettingEnabledlee 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 deMinesService,CratesServiceyMarketService, y sus boosts de drops, experiencia y dinero en favor deModifiersde ExyliaLib.TableServicedescribe las partidas jugador contra jugador de ExyliaTabletop: sus juegos (TableGameInfo), las partidas en vivo y las ofertas abiertas (copiasTableMatchcon susTableSeaty unMatchState), 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;cancelanula una partida y la reembolsa. EscuchaTableMatchCreateEventyTableMatchJoinEvent(cancelables, antes de cobrar nada),TableMatchStartEventyTableMatchEndEventpara el resultado: el ganador, elEndReason, 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