API
Lee homes, warps, kits, rangos y clasificaciones, dirige los teletransportes y reclamaciones, abre las pantallas del plugin y entérate de cambios de homes, warps, kits y ascensos.
SurvivalService es la parte de ExyliaSurvivalCore que otro plugin puede leer o accionar: spawn,
teletransporte aleatorio, homes, warps, kits, estadísticas, rangos, algunos ayudantes de ganancias y
seis de las pantallas del plugin. Lo acompañan seis eventos, todos cancelables, que se disparan
delante de las cosas que cambian el mundo de un jugador, así que una integración puede negarlas en
vez de limpiar después.
ExyliaAPI.get(SurvivalService.class).ifPresent(survival ->
survival.homes(player.getUniqueId())
.forEach(home -> player.sendMessage("Home: " + home.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. El teletransporte aleatorio, los
kits de regalo, la escalera de rangos y su coste y los abridores de menú llegaron en exylia-api
v1.133.0; toolForBreak, countStatistic e isSettingEnabled llegaron después. Compila contra una
etiqueta reciente para usarlos todos.
Las cajas, las minas, las recompensas por cabeza y las salas de duelo salieron de este plugin, y sus métodos también: los de llaves de cajas, recompensas por cabeza y rotura de minas siguen en la interfaz como obsoletos sin efecto. Usa el service del plugin que ahora los tiene (ExyliaCrates, ExyliaMines, ExyliaCombat, ExyliaWarzone).
El plugin es un conjunto de módulos que el administrador enciende uno a uno, así que un servidor
puede correr el survival core sin homes, sin warps o sin kits. Cada método se degrada cuando su
módulo está apagado — una lista vacía, un Optional vacío, false, 0 o no hacer nada — y nunca
lanza una excepción. isModuleEnabled es como distingues «no tiene homes» de «no hay módulo de
homes». Los abridores de menú son la excepción que lo confirma: le dicen al jugador que el módulo
está apagado, igual que el comando.
Todo lo que devuelve un valor lee una caché y puedes llamarlo desde el redibujado de un menú o desde un placeholder. Todo lo demás teletransporta a un jugador, le da objetos, rompe un bloque, abre una pantalla o le cobra dinero, y ejecuta el mismo flujo que su propio comando o su propio golpe — con sus comprobaciones de permisos y los mensajes que ve —, así que llámalo en el hilo dueño del jugador (o, para un bloque de mina, del bloque) y no más veces de las que un jugador podría provocarlo.
Módulos#
| Método | Qué hace |
|---|---|
boolean isModuleEnabled(String moduleId) | Si un módulo está encendido. |
Set<String> enabledModules() | Todos los ids de módulo que están encendidos. |
Los ids son el vocabulario del propio plugin y el conjunto crece entre releases, así que trata uno
desconocido como un módulo que tu integración no conoce y no como un error. Los que hay detrás de
este service son spawn, rtp, homes, warps, kits, stats, rankup y playtime-rewards.
Spawn#
| Método | Qué hace |
|---|---|
Optional<Location> spawn() | Dónde está el spawn del servidor. Vacío si no hay ninguno puesto o el módulo está apagado. |
void teleportToSpawn(Player player) | Manda al jugador allí. |
Teletransporte aleatorio#
| Método | Qué hace |
|---|---|
void randomTeleport(Player player, String worldId) | Manda al jugador a un punto aleatorio de un mundo, igual que /rtp <mundo>. Para un NPC o un portal que haga las veces del comando. |
worldId es el nombre del mundo tal como lo lista la configuración del teletransporte aleatorio.
Primero se comprueba el mundo — que esté en la lista, activado y cargado; si no, al jugador se le
dice que no existe —, después su cooldown y su saldo, y luego corre el warmup exactamente como el del
comando, mensajes incluidos. No se comprueba exyliasurvivalcore.rtp, el permiso que pide el propio
/rtp; los permisos para saltarse el cooldown y el precio siguen valiendo.
La búsqueda de un punto seguro se hace después del warmup, así que el jugador aterriza un momento después de que la llamada vuelva, o no aterriza si se mueve o recibe daño mientras tanto.
Homes#
| Método | Qué hace |
|---|---|
List<Home> homes(UUID player) | Los homes de un jugador. |
Optional<Home> home(UUID player, String name) | Uno de ellos por nombre, sin distinguir mayúsculas. Vacío si no tiene ninguno con ese nombre. |
int maxHomes(Player player) | Cuántos puede tener. Sale de sus permisos, así que necesita al jugador y no su id, y cambia cuando cambia su rango. |
void setHome(Player player, String name, Location location) | Crea o mueve un home. Reemplaza el del mismo nombre en vez de añadir un segundo, que es lo que hace el comando del propio jugador. |
void deleteHome(UUID player, String name) | Borra un home. |
void teleportToHome(Player player, String name) | Manda al jugador a uno de sus homes. |
homes lee la caché, que guarda los homes de un jugador mientras está conectado. Los de un jugador
desconectado no están cacheados, así que responde vacío para él en vez de ir a la base de datos en el
hilo que llama.
teleportToHome existe para que no tengas que teletransportar tú a Home.location(): se encarga de
un home en un mundo sin cargar o en otro servidor, los dos casos en los que esa ubicación es null.
Warps#
| Método | Qué hace |
|---|---|
List<Warp> warps() | Todos los warps, activados o no. |
Optional<Warp> warp(String warpId) | Uno por su id. Vacío si ninguno tiene ese id. |
boolean canUseWarp(Player player, String warpId) | Si tiene el permiso que pide el warp. |
void teleportToWarp(Player player, String warpId) | Lo manda allí, cobrando, comprobando el permiso y arrancando el warmup igual que su propio comando. |
long warpCooldownMillis(UUID player, String warpId) | Milisegundos hasta que pueda usarlo otra vez. 0 si puede usarlo ya. |
canUseWarp es solo el permiso. Un jugador que puede usar un warp igual está en cooldown o no puede
pagarlo, así que sirve para poner una fila en gris en un menú, no para garantizar que el viaje ocurra.
Kits#
| Método | Qué hace |
|---|---|
List<SurvivalKit> kits() | Todos los kits, activados o no. |
Optional<SurvivalKit> kit(String kitId) | Uno por su id. Vacío si ninguno tiene ese id. |
KitClaimStatus kitStatus(Player player, String kitId) | Si podría reclamarlo ahora mismo, y por qué no. La misma respuesta que daría claimKit, calculada sin entregar nada — que es de donde un menú dibuja la fila. |
boolean claimKit(Player player, String kitId) | Le da el kit. Hace todas las comprobaciones primero y no entrega nada si una falla, así que un reclamo rechazado no le cuesta ni un uso ni un cooldown. |
boolean giveKit(Player player, String kitId, boolean ignoreLimits) | Le da el kit como recompensa y no como reclamo — una misión, un voto, una caja que paga con un kit. claimKit es esto con ignoreLimits en false. |
long kitCooldownMillis(UUID player, String kitId) | Milisegundos hasta que pueda reclamarlo otra vez. |
int kitUsesLeft(UUID player, String kitId) | Reclamos que le quedan. -1 si el kit no tiene límite. |
Con ignoreLimits en true, giveKit se salta el cooldown y el límite de usos del kit, igual que la
entrega de un administrador y el kit de primera entrada. El regalo queda registrado igualmente, así
que arranca el cooldown y cuenta como un uso para el próximo reclamo del propio jugador. Todo lo demás
se comprueba en ambos casos — que el kit esté activado, que el jugador tenga su permiso y el hueco en
el inventario —, y los dos métodos disparan KitClaimEvent y le cuentan al jugador el rechazo igual
que el comando.
kitCooldownMillis y kitUsesLeft responden 0 para alguien que no está conectado, y es a
propósito, no un hueco. El progreso de kits se guarda por jugador conectado y se suelta cuando se va,
así que preguntar por alguien ausente no tiene respuesta que dar ni motivo para empezar a guardarla.
Un 0 de kitUsesLeft también significa «no existe ese kit», así que comprueba que el jugador esté
conectado antes de leer cualquiera de los dos como un número.
Estadísticas#
| Método | Qué hace |
|---|---|
Optional<SurvivalStats> stats(UUID player) | Los contadores de combate de un jugador. Vacío si el módulo de estadísticas está apagado. |
List<String> statistics() | Todos los ids de estadística que se pueden rankear. |
List<SurvivalRanking> leaderboard(String statisticId) | El leaderboard de una estadística, el mejor primero. Vacío si la estadística es desconocida o todavía no se construyó. |
int rank(UUID player, String statisticId) | Su posición, empezando en 1. 0 si no está rankeado. |
long playtimeMillis(UUID player) | Milisegundos jugados. 0 si el módulo está apagado o nunca entró. |
Las estadísticas se configuran en vez de estar fijas — un administrador puede añadir una que lea un
placeholder de otro plugin —, así que pide statistics() para saber los ids que acepta leaderboard
en vez de dar por hecho un conjunto.
leaderboard lee el podio que el plugin mantiene caliente con un temporizador, así que es seguro
desde un placeholder y puede ir unos minutos por detrás.
playtimeMillis es el total del propio plugin, que es contra el que se pagan sus recompensas por
tiempo jugado, no el contador de sesión del servidor.
stats solo responde para un jugador cuyos contadores están cargados en este servidor, es decir,
uno conectado. Para cualquier otro devuelve vacío en lugar de una fila de ceros, que sería una
respuesta falsa. Usa leaderboard para jugadores ausentes.
Rangos#
| Método | Qué hace |
|---|---|
List<Rank> ranks() | La escalera entera, del más bajo al más alto. Vacía si el módulo está apagado. |
Optional<Rank> currentRank(UUID player) | El rango que alcanzó. Vacío si todavía no tiene ninguno. |
Optional<Rank> nextRank(UUID player) | El rango al que va. Vacío si ya está arriba del todo. |
int prestigeLevel(UUID player) | Cuántas veces hizo prestigio. 0 si nunca lo hizo. |
double nextRankCost(UUID player) | El dinero que le cobrará su próximo ascenso. 0 si es gratis, ya está arriba del todo, está desconectado o el módulo está apagado. |
boolean canRankUp(Player player) | Si cumple todos los requisitos de su siguiente rango. |
boolean rankUp(Player player) | Lo sube de rango, cobrando, ejecutando los comandos de recompensa y anunciándolo igual que su propio comando. |
canRankUp necesita al jugador y no su id: un requisito puede ser un permiso o un placeholder que
solo se resuelve contra alguien conectado.
nextRankCost es la suma de los requisitos de dinero del siguiente rango tal como los paga este
jugador: multiplicados una vez por cada nivel de prestigio por el multiplicador de coste del
prestigio (ver progresión). Es solo dinero: un rango también
puede pedir tiempo jugado, un permiso o una condición de placeholder, así que un jugador que puede
pagarlo igual puede ser rechazado. Lee el rango del jugador de la caché, y por eso responde 0 para
alguien desconectado.
rankUp escribe el ascenso como una comparación-y-asignación contra el rango guardado, así que dos
servidores no pueden ascender dos veces al mismo jugador. Un true puede llegar antes de que la
escritura se confirme; en el raro caso de que otro servidor lo ascendiera primero, el cobro se
devuelve después.
Ganancias y contadores compartidos#
Eran los ganchos con los que minas y cultivos pagaban a un jugador. Los potenciadores pasaron al
sistema de modificadores de ExyliaLib, la venta automática a ExyliaMarket y las minas a ExyliaMines,
así que los métodos antiguos están obsoletos y responden en neutro (boostDrops devuelve los drops
sin cambios, payEarnings y autoSell devuelven false); el javadoc de cada uno indica su
sustituto. Tres métodos siguen vivos.
| Método | Qué hace |
|---|---|
ItemStack toolForBreak(Player player, ItemStack tool, Location at) | La herramienta con la que se calcula una rotura tras los límites de encantamientos del lugar: una copia si un límite recorta Fortuna o Toque de seda allí. La durabilidad sigue siendo del objeto real. |
void countStatistic(UUID player, String name, String key, long delta) | Suma a uno de los contadores de un jugador, los que leen misiones, clasificaciones y temporadas (protections.created, por ejemplo). |
boolean isSettingEnabled(UUID player, String key) | Si un jugador mantiene activo un ajuste, como un anuncio que puede silenciar. true salvo que lo haya desactivado; una clave desconocida cuenta como activa. |
Menús#
| Método | Abre | Permiso que comprueba |
|---|---|---|
void openKitsMenu(Player player) | La lista de kits, como /kit. | exyliasurvivalcore.kits |
void openWarpsMenu(Player player) | La lista de warps, como /warps. | exyliasurvivalcore.warps.use |
void openHomesMenu(Player player) | Los homes del jugador, como /homes. | exyliasurvivalcore.homes |
void openRankUpMenu(Player player) | La escalera de rangos, como /rankup. | exyliasurvivalcore.rankup |
void openRandomTeleportMenu(Player player) | El selector de mundo, como /rtp. | exyliasurvivalcore.rtp |
void openPlaytimeRewardsMenu(Player player) | Las recompensas por tiempo jugado, como /playtime. | Ninguno. Ejecuta el /playtime de ExyliaRewards, así que sin ese plugin se avisa al jugador de que el módulo está apagado. |
Para un NPC, un cartel o un objeto del lobby que lleve a una pantalla. Cada uno comprueba primero el permiso que pide su comando, y un jugador sin él recibe el mensaje de falta de permiso del propio plugin en vez de la pantalla. Un módulo apagado también se le dice al jugador, igual que lo dice el comando, así que quien llama no tiene nada que explicar en ningún caso.
openHomesMenu le dice a un jugador sin homes que no tiene ninguno en vez de mostrarle una pantalla
vacía. openRankUpMenu no cobra nada: la pantalla muestra el progreso y es desde donde el jugador
sube de rango. Elegir un mundo en openRandomTeleportMenu arranca el mismo flujo que
randomTeleport, con cooldown, precio y warmup.
Tipos#
Home — owner, name, location e iconMaterial (vacío si no tiene). location puede ser
null, y esa es la respuesta honesta y no un hueco: un home puede apuntar a un mundo que este
servidor no cargó, o directamente a otro servidor, y no hay Location para ninguno de los dos casos.
Úsalo para dibujar un menú, y teleportToHome para viajar.
Warp — id, displayName, enabled, cost (0 si es gratis), permission (vacío si puede
usarlo cualquiera) y un location que puede ser null por el mismo motivo que el de un home. Que un
jugador concreto pueda usarlo depende además de su cooldown, así que pregunta canUseWarp y
warpCooldownMillis en vez de decidirlo solo con cost y permission.
SurvivalKit — id, displayName, description, permission, cooldownMillis (0 si no hay
espera), maxUses y enabled. El contenido queda fuera a propósito: es un array de ItemStack que
pertenece al plugin y que se reescribe cada vez que un administrador edita el kit, y entregarlo
dejaría que alguien cambiara lo que recibe todo el mundo. Reclama el kit, o cancela KitClaimEvent y
dale tú lo que quieras.
El javadoc del record dice que maxUses es 0 cuando no hay límite. El plugin pasa tal cual el
valor del kit, y marca un kit ilimitado con -1: el editor de administración guarda cualquier número
negativo como -1, y la comprobación del reclamo solo trata -1 como ilimitado. Un kit con maxUses
en 0 se rechaza con MAX_USES_REACHED desde el primer reclamo. Lee -1 como ilimitado, que es
también lo que devuelve kitUsesLeft.
KitClaimStatus — SUCCESS, NO_PERMISSION, ON_COOLDOWN, MAX_USES_REACHED,
KIT_DISABLED, KIT_NOT_FOUND (también cuando el módulo de kits no está encendido) y NO_ROOM (no
entraría, y el kit se queda con lo que no cabe en vez de tirarlo). Un mismo conjunto responde a «¿este
jugador puede reclamarlo?» y a «¿qué pasó cuando lo hizo?», porque los motivos son los mismos: un
reclamo se rechaza antes de entregar nada, así que un jugador nunca se queda con medio kit y el
cooldown gastado.
SurvivalStats — player, kills, deaths, bestKillStreak y currentStreak. Los cuatro que
el plugin guarda por su cuenta. El sistema de estadísticas más amplio puede rankear cualquier cosa
que nombre un administrador, y esas se leen de una en una con leaderboard(String) en vez de estar
fijadas en un record.
SurvivalRanking — player, playerName, value y rank. value es un double cuente lo
que cuente la estadística, porque la misma maquinaria rankea kills, dinero y horas jugadas. El plugin
lo formatea por estadística para sus propios menús; formatea tú el número en vez de depender de su
configuración.
Rank — id, displayName y order (más bajo va antes en la escalera). Los requisitos quedan
fuera: se leen de la configuración a los tipos del propio plugin, y uno de ellos puede ser una
expresión de placeholder arbitraria que solo el plugin sabe evaluar. Pregunta canRankUp en vez de
intentar deducir la respuesta, y nextRankCost para la parte de dinero.
Eventos#
Seis eventos en net.exylia.lib.api.survival.event, todos Cancellable, todos disparados antes de
escribir, entregar, cobrar o mover nada, así que cancelar deja al jugador exactamente como estaba, sin
nada que deshacer. Cancelar tampoco dice nada al jugador: el manejador que negó la acción es el único
que sabe por qué y debe decírselo él mismo.
| Evento | Se dispara cuando |
|---|---|
HomeSetEvent | Un jugador crea o mueve un home. |
HomeDeleteEvent | Un home está a punto de borrarse. |
HomeTeleportEvent | Un jugador viaja a uno de sus homes. |
WarpTeleportEvent | Un jugador viaja a un warp. |
KitClaimEvent | Un jugador reclama un kit, o se le entrega uno con giveKit. |
RankUpEvent | Un jugador sube un peldaño de la escalera de rangos. |
BountyClaimEvent, MineBlockBreakEvent, MineResetEvent y DuelRoomEndEvent siguen existiendo en
exylia-api, pero ahora los disparan ExyliaCombat, ExyliaMines y ExyliaWarzone. Escúchalos como
eventos de esos plugins; este no dispara ninguno.
¿Un evento no cancelado significa que ocurrió?#
| Evento | No cancelado significa |
|---|---|
KitClaimEvent | Ocurre. Se dispara con todas las comprobaciones pasadas (activo, permiso, cooldown y usos salvo que giveKit los omita, hueco en el inventario) y antes de entregar un solo objeto. Cancelar no da objetos, no ejecuta comandos de recompensa, no escribe cooldown y no cuenta un uso. |
HomeSetEvent | Ocurre. Se dispara cuando el mundo está permitido y, para un home nuevo, el jugador está bajo su límite. Cancelar es lo único que aún puede detenerlo. |
HomeDeleteEvent | Ocurre. Se dispara antes de tocar nada, así que cancelar deja el home exactamente como estaba. |
HomeTeleportEvent | No es promesa de llegada. Una cuenta atrás puede abandonarse o interrumpirse por daño, y el home puede apuntar a un mundo que este servidor no resuelve. |
WarpTeleportEvent | No es promesa de llegada. La cuenta atrás se cancela si el jugador se mueve o recibe daño, y el pago solo se cobra si sobrevive. En el momento del evento no se cobra nada. |
RankUpEvent | No es promesa de ascenso. El pago se cobra después del evento y aún puede fallar; el jugador se queda donde estaba. Compara getTo() con currentRank(UUID) para saber si llegó. |
Ambos eventos de teletransporte se disparan antes de que el plugin decida si el viaje es instantáneo o lleva cuenta atrás, así que cancelar detiene todo y no solo el salto del final.
Leer los eventos#
RankUpEvent.getFrom()es unOptional<Rank>, vacío para quien nunca ha subido de rango.getTo()siempre está.HomeDeleteEvent.getPlayer()es unUUID, porque un home puede borrarse para alguien desconectado.HomeSetEvent.getLocation()no es necesariamente donde está el jugador: la orden puede venir de otro plugin mediantesetHome.getName()es el id del home, así que reutilizar un nombre mueve ese home.- Todo evento se llama en el hilo dueño del jugador, que en Folia es un hilo de región. Lo que toque el mundo en general debe programarse.
Lo que no expone#
El plugin ejecuta unos treinta módulos y este service alcanza un puñado. El resto (portales, back, reparar, near, proyectos, reputación y los demás módulos de calidad de vida) son herramientas de jugador o de administrador cuyo estado es un conjunto de objetos colocados o ajustes por jugador, y un tercero no puede hacer nada útil con ellos. Las cajas, minas, recompensas por cabeza, cápsulas de suministro, zonas de regeneración, cofres de botín y salas de duelo son ahora otros plugins y publican sus propios services.
Dentro de los módulos que alcanza se dejan fuera los flujos de editor y las escrituras administrativas, igual que el contenido de los kits y los requisitos de los rangos: pertenecen al plugin y se reescriben cada vez que un administrador los edita. Las únicas pantallas que abre son las cinco que un jugador abriría con su propio comando.
Si te falta algo, pregunta en Discord: un método añadido a un service es una release menor.
¿Falta algo en esta página? Dínoslo en Discord