API

SurvivalService es la parte de ExyliaSurvivalCore que otro plugin puede leer o accionar: spawn, teletransporte aleatorio, homes, warps, kits, llaves de cajas, estadísticas, rangos, recompensas por cabeza, bloques de minas y seis de las pantallas del plugin. Lo acompañan diez eventos. Ocho son cancelables y 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; los otros dos avisan de un duelo o de un reinicio de mina que ya ocurrió.

ExyliaAPI.get(SurvivalService.class).ifPresent(survival ->
    survival.homes(player.getUniqueId())
            .forEach(home -> player.sendMessage("Home: " + home.name())));

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

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, crates, stats, rankup, playtime-rewards, mines y bounties, y duel-rooms dispara uno de los eventos.

Spawn

Teletransporte aleatorio

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

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

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

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.

Cajas

crateKeys cuenta solo el saldo. Las llaves físicas que lleva en el inventario son objetos como cualquier otro y no cuentan. El saldo se guarda por jugador conectado, así que uno desconectado da 0 en vez de leer la base de datos en el hilo que llama.

giveCrateKeys es para un listener de votos, una tienda o el premio de un evento, y funciona con un jugador desconectado o en otro servidor. Primero se carga su saldo, así que una entrega nunca escribe una fila construida desde cero encima de las llaves que ya tenía. Para alguien ya cargado en este servidor las llaves llegan al instante; para cualquier otro llegan cuando termina esa lectura, un momento después de que vuelva true. Al jugador no se le dice nada.

Estadísticas

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.

Rangos

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.

Minas

Para plugins que rompen bloques en nombre de un jugador — un pico de 3x3, un minero de vetas. Dentro de una mina la rotura de bloques del propio servidor siempre se cancela y la mina quita el bloque ella misma, así que romper un bloque ahí de cualquier otra forma se salta el permiso de la mina, su loot y su regeneración, y deja un agujero que la mina nunca rellena. Pasa cada bloque por aquí primero y rómpelo tú solo con UNCLAIMED.

La mina comprueba su permiso, dispara MineBlockBreakEvent y rompe el bloque con el objeto que el jugador tiene en la mano principal: sus encantamientos dan forma a los drops vanilla (Fortuna, Toque de seda) salvo que el bloque tenga una tabla de loot propia, y pierde durabilidad en ambos casos. Un jugador con exyliasurvivalcore.mines.admin pasa tanto el permiso como la restricción. Al jugador no se le dice nada cuando la mina se niega: quien llama y recibe un rechazo en ocho bloques a la vez es quien sabe si merece un mensaje.

Recompensas por cabeza

Todas las recompensas viven en memoria, así que responde también para un jugador desconectado.

Menús

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.

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.

MineBreakResult — qué pasó con un bloque entregado a breakMineBlock. Solo UNCLAIMED deja el bloque en manos de quien llama; cualquier otro valor significa que una mina es su dueña y no hay que romperlo de ninguna otra forma.

Eventos

Diez eventos en net.exylia.lib.api.survival.event. Ocho son Cancellable, y esos ocho se disparan antes de que se escriba, se entregue, se cobre, se mueva o se rompa nada — así que cancelar deja al jugador exactamente como estaba, sin nada que deshacer. Los otros dos avisan de algo que ya ocurrió.

Cancelar tampoco le dice nada al jugador. El handler que negó la acción es el único que sabe por qué, y se espera que lo diga él.

¿Un evento no cancelado significa que ocurrió?

Para los ocho que se pueden cancelar, depende de lo que queda entre el evento y el resultado.

HomeTeleportEvent se dispara antes de que el plugin decida si el viaje es instantáneo o lleva cuenta atrás, así que cancelar corta todo y no solo el salto del final del warmup. WarpTeleportEvent hace lo mismo, y por eso un handler nunca deja a un jugador plantado durante un warmup que no lleva a ninguna parte.

Leer los eventos

• RankUpEvent.getFrom() es un Optional<Rank> y está vacío para un jugador que nunca subió de rango. El primer ascenso parte de no tener ninguno, no de un escalón inicial, y no hay un Rank sensato que nombrar. getTo() siempre está.
• HomeDeleteEvent.getPlayer() es un UUID y no un Player, porque un home se puede borrar para alguien que no está conectado: lo hacen tanto un comando de administración como la limpieza del propio plugin. Búscalo si lo necesitas, y cuenta con null.
• HomeSetEvent.getLocation() no es necesariamente donde está parado el jugador: la operación puede venir de otro plugin a través de setHome(Player, String, Location). getName() es el id del home, no un nombre visible, y por eso poner un nombre que el jugador ya usó mueve ese home en vez de añadir un segundo.
• BountyClaimEvent trae getKiller(), getVictim(), getAmount() y getBounties(). Todas las recompensas sobre la víctima se cobran a la vez, así que getAmount() es el total entero como BigDecimal y getBounties() cuántas colocaciones lo forman, como mínimo 1. Se dispara después de la muerte, y solo si la víctima tenía una recompensa y la mató un jugador.
• MineBlockBreakEvent trae getPlayer(), getMineId() y getBlock(), y el bloque todavía tiene el tipo que el jugador estaba minando. Dentro de una mina el BlockBreakEvent del propio servidor siempre se cancela, así que un listener que ignora los eventos cancelados nunca ve una rotura en una mina: escucha este. Se vuelve a disparar por cada bloque que un handler rompa con breakMineBlock, así que un handler que lo haga tiene que distinguir sus propias roturas.
• MineResetEvent.getMineId() nombra la mina. Se dispara cuando el último bloque vuelve a su sitio, lo haya pedido el temporizador, el umbral de vaciado o un administrador, y después de sacar a los jugadores que los bloques nuevos dejaron enterrados. El relleno se reparte en varios ticks, así que llega un poco después de que empezara el reinicio. Solo lo disparan las minas clásicas: una mina realista hace crecer cada bloque por su cuenta y nunca vuelve a estar llena en un momento concreto.
• DuelRoomEndEvent trae getRoomId(), getWinner() y getParticipants(). getWinner() es un UUID que puede ser null, null en un empate: no queda nadie en pie, se acabó el tiempo del combate o nadie acertó un golpe dentro del límite de inactividad de la sala. getParticipants() es todo el que empezó el duelo en el orden en que entró, ganador incluido, y alguno puede haber salido del servidor: quien se desconecta pierde, pero participó igual. Se dispara antes de que las recompensas de la sala lleguen al ganador, y la sala sigue cerrada durante su tiempo de loot, así que los jugadores normalmente siguen dentro.
• Cada uno se llama en el hilo dueño de aquello de lo que trata — el jugador, o en los dos eventos de minas el bloque y el último bloque rellenado de la mina —, que en Folia es un hilo de región y no un único hilo principal. DuelRoomEndEvent se llama en el hilo que notó el final: el temporizador de las salas, una vez por segundo en el hilo global, o el hilo de región del jugador cuya muerte, desconexión o salida lo decidió; ninguno de los dos tiene garantizado ser dueño del ganador. Todo lo que toque el resto del mundo, o a un jugador del que el hilo no es dueño, hay que programarlo.

Lo que no expone

El plugin tiene cincuenta módulos y este service llega a una docena. El resto — portales, zonas de regeneración, cofres de loot, objetos bloqueados y los demás módulos de construcción de mundo — son herramientas de administración cuyo estado es un conjunto de objetos colocados, y no hay nada útil que un tercero pueda hacer con ellos. Las minas publican su rotura y su reinicio y nada más, para que un plugin que rompe bloques por un jugador reciba el loot y la regeneración de la mina en vez de un agujero.

Dentro de los módulos a los que llega quedan fuera los flujos de editor y las escrituras administrativas, igual que el contenido de los kits y los requisitos de los rangos: los dos pertenecen al plugin y los dos se reescriben cada vez que un administrador los edita. Las únicas pantallas que abre son las seis que un jugador podría abrir con su propio comando.

Si te falta algo, pídelo en Discord — añadir un método a un service es un release menor.