Jugadores
Un registro de reservas, estancias, cooldowns locales y de red, multicuentas, bloques colocados, teletransportes, snapshots, clanes, combate y cabezas.
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.
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));| Llamada | Qué 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. |
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:
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:
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);| Llamada | Qué 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:
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 correCooldownScope 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:
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:
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. sameAddresscuenta 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.firstSeentiene 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:
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#
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(...):
PluginTeleports teleports = Teleports.of(this);
teleports.to(player, spawn)
.warmup(3.0)
.cancelOnMove()
.cancelOnDamage()
.cooldown("spawn", 30.0)
.safe()
.start();| Llamada | Qué 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:
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"); // devueltocapture 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:
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:
- FactionsUUID / Factions
- HuskTowns
- ZelTeams
- RunithClans
- UltimateClans
- Kingdoms / KingdomsX
- SimpleClans
- 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:
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#
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#
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