API
Preguntar dónde está un jugador, mandarlo a un mundo, leer los mundos y sus kits, vestirlo, leer sus estadísticas de sandbox, y los eventos de entrada, llegada y salida.
SandBoxService es como otro plugin pregunta si un jugador está en un sandbox o en una cola, lo manda a
un mundo, lee los mundos configurados y los kits guardados de un jugador, viste a alguien con uno de
ellos y lee sus bajas, muertes y tiempo jugado. Tres eventos le avisan de cuándo un jugador pide entrar,
llega y sale.
ExyliaAPI.get(SandBoxService.class).ifPresent(sandbox -> {
if (sandbox.isInSandbox(player.getUniqueId())) {
event.setCancelled(true);
}
});El artefacto, el repositorio y la línea de plugin.yml son los mismos para todos los plugins de Exylia
y están en la página de la API pública.
La respuesta es la reserva, no el mundo#
isInSandbox responde desde la reserva de sesión que toma el plugin, no desde el mundo en el que esté
parado el jugador. Los dos no coinciden durante un teletransporte sin terminar, y gana la reserva — que
es lo que quieres: un jugador ya reservado y en vuelo está ocupado.
Todo lo que devuelve un valor lee una caché y es seguro desde un placeholder, una línea de marcador o un redibujado de menú. Todo lo que actúa teletransporta jugadores y reescribe inventarios: llama a eso en el hilo principal, y no más a menudo de lo que podría provocarlo un jugador.
Sesión#
| Método | Qué hace |
|---|---|
boolean isInSandbox(UUID) | Si tiene la reserva de sandbox. |
boolean isInQueue(UUID) | Si está esperando rival. |
boolean leave(Player) | Lo manda de vuelta al lobby. Informa de si la petición se aceptó, no de si terminó; false mientras está montando un kit. |
boolean joinQueue(Player, String worldId, int kitSlot) | Lo mete en la cola de un mundo. false solo cuando no hay ningún mundo con ese id — cualquier otro rechazo de la cola ya se le ha dicho al jugador. |
void leaveQueue(Player) | Lo saca de la cola en la que esté. |
EnterResult enter(Player, String worldId, int kitSlot) | Lo manda directo a un mundo, vestido con uno de sus kits: la entrada de /rtp. |
void openWorldSelector(Player) | Abre la lista de mundos que abre /rtp: la pantalla que quiere un NPC del lobby. |
enter decide cada rechazo antes de quitarle nada al jugador, y no le dice ninguno: el resultado es
tuyo para ponerlo en palabras. ACCEPTED es una petición en marcha, no una llegada: encontrar un sitio
seguro y completar el teletransporte terminan unos ticks después y todavía pueden fallar, y en ese caso
el jugador vuelve a estar como estaba y se le avisa. SandboxArriveEvent es la confirmación.
EnterResult | Significado |
|---|---|
ACCEPTED | De camino |
BUSY | Otro plugin lo tiene, o está montando un kit |
ALREADY_IN_SANDBOX | Pasar de un mundo sandbox a otro no es entrar en uno |
UNKNOWN_WORLD | No hay ningún mundo configurado con ese id |
WORLD_NOT_READY | Todavía se está generando, o no está disponible |
NO_KIT | La ranura no tiene ningún kit guardado con contenido |
REFUSED | Un handler de SandboxJoinEvent lo canceló, el jugador está en combate (se le dice general.in-combat), u otro plugin se lo llevó entre las comprobaciones y la reserva |
openWorldSelector abre la pantalla pueda o no entrar el jugador ahora mismo: un mundo que no está
listo se dibuja sin acción, y cada entrada que ofrece la pantalla hace sus propias comprobaciones al
pulsarla.
Mundos#
| Método | Qué hace |
|---|---|
List<SandboxWorld> worlds() | Todos los mundos configurados, inservibles incluidos, sin orden concreto. Inmutable. |
Optional<SandboxWorld> world(String worldId) | Uno por id. |
Optional<SandboxWorld> worldOf(World) | La pregunta de un listener: ¿este mundo de Bukkit es de los nuestros? |
float pregenerationProgress(String worldId) | De 0 a 1. 0 tanto para un mundo terminado como para uno que nunca empezó. |
SandboxWorld es una foto fija, no una vista viva: id, displayName, worldName, biome,
borderSize, type, status y loaded, más isPlayable() — cargado y READY. Lleva un nombre
de mundo en vez de un World porque un mundo configurado no está necesariamente cargado.
WorldStatus es CREATING, PREGENERATING, READY o UNAVAILABLE. WorldType es MANAGED o
IMPORTED.
Kits#
| Método | Qué hace |
|---|---|
List<SandboxKit> kits(UUID) | Sus kits guardados, ordenados por ranura. Un jugador desconectado no informa de nada. Inmutable. |
Optional<SandboxKit> kit(UUID, int slot) | Una ranura. |
Optional<SandboxKit> favoriteKit(UUID) | El marcado con estrella, si tiene alguno. |
int maxKits(Player) | Cuántas ranuras se le permiten. Lee permisos, por eso toma el jugador. |
int activeKitSlot(UUID) | La ranura que lleva puesta, -1 si no lleva ninguna. |
void applyKit(Player, int slot) | Sustituye lo que lleva por ese kit. No hace nada en una ranura sin usar. |
SandboxKit es slot, name, favorite, hasContents, createdAt y updatedAt. El contenido no se
expone a propósito: usa applyKit en vez de leer las pilas.
Estadísticas#
| Método | Qué hace |
|---|---|
SandboxStats stats(UUID) | Nunca vacío. Un jugador que nadie ha cargado se lee como ceros, y la lectura se lanza, así que el siguiente dibujado ya tiene los números. |
SandboxStats es player, kills, deaths y playtimeMillis, más kdr() — que devuelve el número
de bajas cuando no hay muertes. El tiempo jugado es tiempo de sandbox, no tiempo en el servidor.
Eventos#
Los tres viven en net.exylia.lib.api.sandbox.event, llevan getPlayer() y getWorld() (un
SandboxWorld), y se llaman en el hilo dueño del jugador, que en Folia es el hilo de su región.
| Evento | Cuándo | Cancelable |
|---|---|---|
SandboxJoinEvent | Un jugador pide un mundo, por teletransporte aleatorio o entrando en su cola, antes de quitarle nada. getKitSlot() e isQueued() dicen cómo. | Sí: se queda exactamente como estaba, y el plugin no dice nada |
SandboxArriveEvent | Ha llegado, en supervivencia, con la vida llena y su kit puesto. La confirmación que los otros dos no son. | No |
SandboxLeaveEvent | El sandbox lo ha soltado: inventario devuelto, reserva liberada. getReason() es LEFT, DIED o DISCONNECTED. | No |
Una cola pregunta una vez, al entrar el jugador, y no otra vez al encontrarle pareja: rechazar en ese
momento mandaría a la pareja sola. Pasar de un mundo sandbox a otro no dispara ninguno de los tres, ni
tampoco volver a conectarse dentro de uno. Salir de una cola, o una entrada que falló antes de que el
jugador llegara, no dispara SandboxLeaveEvent. Cancelar una entrada no le dice nada al jugador:
explicarle por qué es cosa de quien cancela.
¿Falta algo en esta página? Dínoslo en Discord