Contenido generado con IA — puede contener errores.

ExyliaSurvivalCore/ReferenciadevActualizada en v1.2.2

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.

Página 22 de 3818 min de lectura

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.

java
ExyliaAPI.get(SurvivalService.class).ifPresent(survival ->
    survival.homes(player.getUniqueId())
            .forEach(home -> player.sendMessage("Home: " + home.name())));
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. 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).

Tener el service no es tener los módulos

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étodoQué 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étodoQué 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étodoQué 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étodoQué 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étodoQué 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étodoQué 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.

Los dos contadores de kit responden 0 con el jugador desconectado

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étodoQué 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étodoQué 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étodoQué 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étodoAbrePermiso 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.

maxUses es -1 sin límite, no 0

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.

EventoSe dispara cuando
HomeSetEventUn jugador crea o mueve un home.
HomeDeleteEventUn home está a punto de borrarse.
HomeTeleportEventUn jugador viaja a uno de sus homes.
WarpTeleportEventUn jugador viaja a un warp.
KitClaimEventUn jugador reclama un kit, o se le entrega uno con giveKit.
RankUpEventUn 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ó?#

EventoNo cancelado significa
KitClaimEventOcurre. 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.
HomeSetEventOcurre. 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.
HomeDeleteEventOcurre. Se dispara antes de tocar nada, así que cancelar deja el home exactamente como estaba.
HomeTeleportEventNo 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.
WarpTeleportEventNo 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.
RankUpEventNo 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 un Optional<Rank>, vacío para quien nunca ha subido de rango. getTo() siempre está.
  • HomeDeleteEvent.getPlayer() es un UUID, porque un home puede borrarse para alguien desconectado.
  • HomeSetEvent.getLocation() no es necesariamente donde está el jugador: la orden puede venir de otro plugin mediante setHome. 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