Contenido generado con IA — puede contener errores.

ExyliaLib/Juego

Jugadores

Un registro de reservas, estancias, cooldowns locales y de red, multicuentas, bloques colocados, teletransportes, snapshots, clanes, combate y cabezas.

Página 42 de 5411 min de lectura

Un jugador, una actividad#

El problema que resuelve: tres minijuegos en un servidor, cada uno con su método isInGame(player), cada uno preguntando a los otros dos por reflexión, cada uno respondiendo sobre un momento que ya había pasado para cuando se ejecutaba la entrada.

java
PluginSessions sessions = Sessions.of(this);
 
if (!Sessions.isFree(player)) {
    Sessions.holder(player).ifPresent(claim ->
            Text.of("Ocupado en " + claim.kind()).send(player));
    return;
}
 
sessions.claim(player, "Event", () -> { leaveEvent(player); return true; })
        .ifPresent(claim -> join(player));
LlamadaQué hace
Sessions.isFree(player)Si algo lo tiene. Una pregunta, no una reserva.
Sessions.holder(player)Quién lo tiene, y cómo lo llamó.
sessions.claim(player, kind, onRelease)Tomarlo. Atómico — esto es lo que decide de verdad.
sessions.mine(player)La reserva, si es nuestra.
sessions.release(player)Devolverlo: termina nuestra reserva, nunca la de otro plugin.
Sessions.release(player)Pedir a quien lo tenga que lo devuelva.
isFree no es una reserva

Entre preguntar y actuar, otro puede haberse llevado al jugador. claim es lo que decide, y devuelve vacío cuando perdió la carrera. El callback de liberación es cómo se le dice a quien lo tiene que lo suelte.

El callback de liberación devuelve si la petición se acepta, no si ha terminado: devolver a un jugador es un teletransporte y una restauración, que acaban más tarde, así que un manejador que acepta suelta la reserva desde su propio callback. Devolver false la rechaza — un jugador en combate no está disponible — y a quien pregunta se le dice que no. Una reserva tomada sin callback se suelta sin más cuando alguien lo pide.

El trabajo que termina más tarde se protege contra la reserva, para que no pueda tocar a un jugador que ya se fue a otra cosa:

java
teleport(player, spawn).thenRun(() -> claim.ifCurrent(() -> giveKit(player)));

La reserva es reentrante para su dueño: un jugador que pasa del lobby de un evento a la partida, o de jugar a espectar, mantiene una única reserva continua en vez de soltarla y competir por recuperarla. Una reserva también termina cuando el jugador se desconecta o su plugin se desactiva.

Nada del registro sabe qué modos existen, así que un modo añadido más tarde queda cubierto sin tocarlo.

Estancias#

La mayoría de reservas significan "llévalo a mi arena y devuélvelo tal como vino". Stays es eso, con los tres órdenes que cada plugin de arenas tuvo que aprender a las malas ya incorporados:

java
PluginStays stays = Stays.of(this);
 
// Entrar: reservado y guardado aquí, vaciado cuando ya está en la arena.
stays.enter(player, "duel", () -> { endMatch(player); return true; }).ifPresent(stay ->
        stay.ready().thenCompose(ignored -> teleport(player, arena))
                .thenCompose(ignored -> stays.dress(player, GameMode.ADVENTURE, stay::isCurrent)));
 
// Salir: a casa, restaurado allí, liberado al final.
stays.leave(player);
 
// Al entrar al servidor: lo que dejó un crash vuelve, y el jugador también.
stays.recover(player);
LlamadaQué hace
enter(player, kind, onRelease)Reserva al jugador y guarda un snapshot suyo. stay.ready() se completa cuando está guardado — la señal para moverlo.
enter(player, claim)Convierte en estancia una reserva que este plugin ya tiene (una cola que pasa a su jugador a la partida). Conserva el token y el manejador de la reserva.
dress(player, mode, still)Lo vacía y le pone el modo de juego, al llegar. Se salta si still dice que ya no se le quiere.
leave(player) / leave(player, home)De vuelta a donde vino (o a un lobby), restaurado allí, y luego liberado.
leaveHere(player)Restaurado donde está, para un jugador que se fue por un portal.
recover(player)Devuelve cada estancia guardada que dejó un crash o un reinicio. Llámalo al entrar.
isHeld(uuid)Si este plugin responde por sus pertenencias: reservado, o aún saliendo.
  • El snapshot se toma antes del teletransporte y el inventario se vacía solo después, porque un plugin de inventario por mundo escribe lo que lleve el jugador en el mundo que deja.
  • Una restauración nunca empieza antes de que su guardado haya llegado.
  • La reserva se suelta al final, para que nada más pueda vestir al jugador mientras sus cosas aún vuelven.

Cooldowns#

La base sobre la que se apoya cada cooldown del ecosistema, para que una barra pueda mostrar uno sin ser su dueña:

java
PluginCooldowns cooldowns = Cooldowns.forPlugin(this);   // las claves pasan a ser "miplugin:pearl"
 
cooldowns.startSeconds(player, "pearl", 16);
cooldowns.isActive(player, "pearl");
cooldowns.remainingSeconds(player, "pearl");
cooldowns.tryStart(player, "pearl", Duration.ofSeconds(16));   // false mientras corre

CooldownScope amplía la clave más allá de un jugador — CooldownScope.GLOBAL, CooldownScope.group(clanId) o cualquier CooldownScope.of(tipo, id). Los cooldowns de cinco minutos o más se escriben a disco y vuelven tras un reinicio; los más cortos viven en memoria.

ItemCooldowns pone además el barrido de cooldown de vanilla sobre un item, para que el cliente lo apague visualmente. En Lunar y en el mod de SurvivalCore el cooldown también se dibuja en el HUD con el item como icono — ver Integración de cliente.

Ítems que comparten material: separate(stack, group) (Minecraft 1.21.4+) da a una pila su propio grupo de cooldown, y start/clear/redraw(player, key, ItemStack, ...) dibujan sobre ese grupo, así una perla personalizada en cooldown deja libres las demás perlas. Vanilla reinicia un barrido tras usar el ítem; si se inició durante ese uso, haz redraw un tick después.

Un efecto puede leer un cooldown en marcha en vez de contar por su cuenta — ver Efectos · Temporizadores.

Entre reconexiones y servidores#

Cooldowns pertenece a la memoria de un servidor: un jugador que sale o cambia de servidor empieza de cero un cooldown de treinta segundos. Para cualquier cosa que merezca la pena abusar — una reparación, una curación, una recompensa por kill — usa NetworkCooldowns, escrito en la base de datos del plugin para que todos los servidores que la comparten vean el mismo:

java
NetworkCooldowns cooldowns = NetworkCooldowns.of(this);   // una vez, en onEnable
 
if (!cooldowns.tryStart(player.getUniqueId(), "repair", Duration.ofMinutes(10))) {
    if (!cooldowns.isLoaded(player.getUniqueId())) { say(player, "Aún cargando."); return; }
    say(player, "Espera " + cooldowns.remaining(player.getUniqueId(), "repair").toSeconds() + "s.");
    return;
}

Los cooldowns de un jugador se leen al entrar y después se responden desde memoria. Hasta que esa lectura vuelve, la respuesta es "espera": isActive es true y tryStart es false, así que un jugador no puede colarse por el hueco que abre un salto de servidor. start y clear cambian la memoria al momento y se escriben en el orden en que se hicieron. Las filas viven en exylia_network_cooldowns y se borran al limpiarse o cuando el dueño vuelve a entrar después de que terminaran.

Multicuentas y primeras entradas#

Accounts responde si dos cuentas son probablemente la misma persona, y desde cuándo conoce la red a un jugador — conectado o no:

java
Accounts accounts = Accounts.of(this);   // una vez, en onEnable
 
accounts.sameAddress(buyer, seller).thenAccept(alt -> {
    if (alt) return;   // nada de reputación entre un jugador y su multicuenta
    ...
});
accounts.firstSeen(invited).thenAccept(first -> ...);   // Optional<Instant>
  • La dirección en sí nunca se guarda. Cada entrada escribe un hash con clave de ella, con cuándo se usó por última vez, más la primera vez que se vio al jugador. La clave vive en la base de datos, así que todos los servidores que la comparten calculan el mismo hash para una dirección. Una dirección IPv6 se resume por su /64.
  • sameAddress cuenta una dirección que ambos jugadores usaron en los últimos 30 días (accounts.window(…) lo cambia), o que ambos estén conectados aquí ahora mismo desde la misma.
  • firstSeen tiene en cuenta también la fecha de primera conexión del propio servidor, así que un veterano no es "nuevo" la primera vez que lo ve este módulo.
  • Ambas se completan con error cuando la base de datos no puede responder. Decide qué significa: una recompensa debería negarse (.exceptionally(failure -> true)), un aviso debería callarse.

Apunta el plugin de cada servidor a una misma base de datos y las respuestas son de toda la red.

Bloques colocados#

Si un bloque lo puso un jugador, recordado entre reinicios — la pregunta del anti-farmeo:

java
PlacedBlocks.track(this, List.of(Material.SUGAR_CANE, Material.DIAMOND_ORE));
 
@EventHandler(ignoreCancelled = true)
public void onBreak(BlockBreakEvent event) {
    if (PlacedBlocks.placedByPlayer(event.getBlock())) return;   // sin recompensa por colocar y romper
    reward(event.getPlayer());
}

El registro vive en los datos del propio chunk, así que se guarda y se carga con los bloques y no cuesta nada mientras el chunk está descargado. Solo se registran los materiales seguidos; un pistón mueve el registro con el bloque, y romperlo lo olvida solo después de que todos los listeners por debajo de MONITOR hayan preguntado. Un bloque que se va de otra forma (explosión, fuego) conserva su registro — la respuesta se equivoca hacia "colocado". Cada chunk guarda como mucho 4096 posiciones.

Números en permisos#

java
int homes = PermissionNumbers.highest(player, "myplugin.homes.", settings.defaultHomes());

Gana el número más alto tras un prefijo, porque una escalera de rangos concede cada peldaño de subida. Un nodo puesto a false no concede nada, y una cola que no sea un número entero se ignora. Llámalo en el hilo del propio jugador.

Teletransportes#

Mover a un jugador rara vez es solo player.teleport(...):

java
PluginTeleports teleports = Teleports.of(this);
 
teleports.to(player, spawn)
         .warmup(3.0)
         .cancelOnMove()
         .cancelOnDamage()
         .cooldown("spawn", 30.0)
         .safe()
         .start();
LlamadaQué hace
to(player, location)Una petición, configurada y luego arrancada con start(). Nada pasa antes, y el cooldown solo se cobra entonces.
toAll(players, location)Un grupo a la vez.
back(player)Una petición hacia donde estaba antes del último teletransporte.
lastLocationOf(player)Esa ubicación, sin moverlo.
request(from, to, …)Una petición estilo /tpa.
accept(target, from) / deny(…) / cancel(…)Responderla.

Una petición también puede lanzar efectos (onStart, onArrive, onCancel), informar de la cuenta atrás (onTick) y devolver el resultado (then). Los calentamientos, los aterrizajes seguros, el historial de /back y los traspasos entre servidores viven aquí, y todos corren en el hilo del propio jugador.

Snapshots#

El estado de un jugador guardado para después — en memoria mientras un menú está abierto, o almacenado para que sobreviva a un reinicio:

java
PluginSnapshots snapshots = Snapshots.of(this);
 
Snapshot held = snapshots.capture(player);            // en memoria, ahora mismo
snapshots.saveAndClear(player, "event:lms1");         // guardado, y el jugador vaciado
snapshots.restore(player, "event:lms1");              // devuelto

capture es el de memoria, para un menú que va a devolver el estado en un momento. save lo escribe bajo un id de contexto para que sobreviva a un reinicio, y saveAndClear hace las dos mitades de "guarda esto y dale el kit" en una llamada.

Es lo que devuelve a un jugador su inventario de supervivencia tras un evento, y lo que permite a un editor de kits devolver lo que alguien llevaba al abrirlo. Las estancias se apoyan en ello.

Clanes#

Una API sobre ocho plugins de clanes, detectados automáticamente al arrancar:

java
if (Clans.isSupported()) {
    Optional<String> tag = Clans.clanTag(player.getUniqueId());
    Optional<Clan> clan  = Clans.clanOf(player.getUniqueId());
}

Orden de detección — gana el primero presente y accesible:

  1. FactionsUUID / Factions
  2. HuskTowns
  3. ZelTeams
  4. RunithClans
  5. UltimateClans
  6. Kingdoms / KingdomsX
  7. SimpleClans
  8. ExyliaClans

Cada proveedor llega a su plugin por reflexión, de modo que uno instalado cuya API no se pueda alcanzar se salta con un aviso en vez de ocupar el hueco en silencio. Un plugin que no esté en la lista registra un ClanBridge, y un puente registrado gana a la detección automática.

Las alianzas y rivalidades forman parte de la API (areAllied, areRivals), y los proveedores que no tienen ese concepto responden vacío en vez de inventárselo.

Combate#

Si un jugador está peleando, sobre DeluxeCombat, PvPManager o un puente que escribas:

java
if (Combat.isTagged(player)) {
    return;
}

La idea es la misma que en clanes: tu plugin hace una pregunta y no le importa qué plugin responde. Sin nada instalado todas las llamadas siguen funcionando: nadie está marcado y el PvP siempre está permitido.

Argumentos placeholder en comandos#

Para cualquier otro valor de una palabra con caracteres que Brigadier rechaza (un placeholder como %top_kills;name;1%), usa command.lamp.TokenArgument (desde 1.583.0): se lee igual y le dice al cliente que es un nombre de jugador, el único tipo vanilla que el cliente también lee hasta el siguiente espacio, así nada se pinta en rojo.

Jugadores de Bedrock#

java
if (Clients.isBedrock(player)) {
    // sáltate lo que un cliente Bedrock no puede dibujar, como las display entities
}

Floodgate responde cuando está instalado, porque solo él conoce a un jugador vinculado; si no, responde el UUID, como recomienda Geyser, y se pregunta a la propia API de Geyser cuando corre sin Floodgate. El nombre nunca se usa. Funciona sea cual sea de los dos el que se active primero. Un jugador vinculado que está desconectado no se distingue de su cuenta de Java y responde false.

Cabezas#

java
Skulls.player("Notch").build();
Skulls.texture(base64).build();
Skulls.url(url).build();

Cacheadas, compartidas entre plugins, y sin bloquear nunca: una cabeza que aún no se ha descargado vuelve en plano y se reemplaza cuando llega. Por eso un menú lleno de cabezas de jugador se abre al instante en vez de congelar el servidor en una consulta a Mojang.

Preferencias#

Los ajustes de jugador y la pantalla /settings en la que se registra cada plugin tienen su propia página: Ajustes de jugador.

¿Falta algo en esta página? Dínoslo en Discord