Contenido generado con IA — puede contener errores.

ExyliaLib/Juego

Recompensas

Lo que un jugador ganó: items, comandos, dinero, experiencia y efectos, con probabilidades, condiciones y una cola para quien no está.

Página 44 de 5410 min de lectura

Una lista de recompensas son items, comandos, dinero, experiencia, mensajes y efectos de poción con probabilidades y condiciones, editable en el juego y guardada exactamente como la guardaba ExyliaCommons.

java
PluginRewards rewards = Rewards.of(this);
 
rewards.give(player, config.winnerRewards());

El dinero se paga a través de la economía, y las tablas de loot y las cajas están en Cajas y loot.

Tipos#

TipoContenido
COMMANDcommand, ejecutado por la consola, con o sin / delante. %player_name% es el jugador.
ITEMitemSnapshot: un material, un texto de cabeza o bytes:.
MESSAGEmessage, en notación de texto Exylia.
ECONOMYvalue como texto, más un currency opcional; vacío es la moneda por defecto.
EXPERIENCEvalue, en puntos.
POTIONvalue, un efecto por línea: SPEED|2|15.

Una recompensa de item se guarda entera: el nombre, el lore, los encantamientos y los atributos que se le dieron son lo que recibe el jugador. Una cabeza guardada como basehead-… o playerhead-… se entrega como un PLAYER_HEAD liso; guárdala como bytes: para conservar la textura.

En un archivo de config#

java
List<RewardEntry> list = Rewards.read(section, "rewards",
        (where, problem) -> getLogger().warning(where + ": " + problem));

Las claves son los nombres de campo guardados, así que un archivo y una columna de base de datos dicen lo mismo:

yaml
rewards:
  - type: ITEM
    itemSnapshot: DIAMOND
    minAmount: 4
    maxAmount: 12
    chance: 25.0
    permission: event.vip
  - type: ECONOMY
    value: "500"
    currency: gems
  - type: COMMAND
    command: "crate key give %player_name% 1"
    deliveryMessage: "{success}¡Ganaste una llave!"
    priority: 5
  - "broadcast %player_name% won"      # un texto suelto es un comando
ClaveSignificado
nameCómo se llama la recompensa en menús y mensajes.
itemAmountUn tamaño de stack fijo.
minAmount / maxAmountUna cantidad aleatoria, ambos extremos incluidos; gana sobre itemAmount. En dinero y experiencia es lo que se paga.
chancePorcentaje, 0–100: si esta ocurre. 100 nunca tira.
weightCuál ocurre, para roll y pick. Por defecto 1; 0 o menos nunca sale.
permissionNecesario para recibirla.
condition%player_level% >= 10. Operadores >=, <=, >, <, ==, !=, o true/false. == y != comparan texto sin distinguir mayúsculas.
deliveryMessageSe envía cuando llega.
priorityMayor se entrega antes; a igual prioridad se respeta el orden del archivo.
iconCómo la dibuja un menú.

Una fila que no se puede leer se reporta y se salta; el resto carga igual.

Una condición ilegible entrega la recompensa

Una condición que nadie puede leer se reporta una vez y se da por cumplida. Decía a quién excluir, y una errata no excluye a nadie. Un menú hace lo contrario: ahí una condición ilegible oculta el slot.

Editar en pantalla#

java
rewards.editor(zone.rewards())
        .title("{primary}&lREWARDS")
        .onSave(edited -> manager.save(zone, edited))
        .onCancel(() -> setupMenu.open(player))
        .open(player);

Paginación, añadir, editar, borrar, copiar, pegar, guardar y cancelar. Una recompensa copiada en un plugin se pega en el editor de recompensas de cualquier otro.

PreguntaQué pasa
¿Qué da?El tipo va primero, porque decide qué campos tiene el formulario: a un comando nunca se le pide tamaño de stack.
Un itemEl selector de icono, luego un formulario rellenado desde el item: su propio nombre y el tamaño de stack que se puso. Editarlo después no vuelve a pedir el item.
Varios itemsUna ventana acepta cualquier cantidad de items y añade una recompensa por stack.
Varios comandosUn comando por línea, una recompensa por comando.
DineroLa cantidad y un selector de moneda.
ExperienciaLos puntos mínimos y máximos.
Una pociónLa lista de efectos se abre al enviar, también en una recompensa nueva sin efectos todavía.
Editar todasProbabilidad, peso, permiso, condición y mensaje aplicados a todas las filas; vacío conserva el de cada una.

Una lista que se sortea por peso (una caja, roll, pick) usa el editor con pesos:

java
rewards.weightedEditor(crate.rewards(), reward -> List.of(
        " {letters_black}▎ {letters}Rarity {letters_black}» " + tiers.of(reward).display()));

Cada fila muestra su parte real de todos los drops contando el peso, shift + izquierdo y shift + derecho suben y bajan el peso ahí mismo, y un botón ordena por peso. Las líneas extra son opcionales y se vuelven a pedir en cada redibujado.

Entregar#

LlamadaQué hace
give(player, rewards)Todas, cada una comprobada y tirada por su cuenta. En el hilo del jugador.
give(player, reward)Una.
giveOnPlayerThread(player, rewards, then)Lo mismo desde cualquier hilo, movido al del jugador.
giveItem(player, stack)Un ItemStack bajo la política de desborde.
roll(player, rewards)Exactamente una, elegida por peso; aun así se enfrenta a su propio chance.
pick(rewards)Elegir por peso sin entregar: una vista previa.
giveDropping(player, rewards, spot)Lo entrega todo, pero los items salen lanzados en el sitio, una entidad por stack. Dinero, comandos y el resto siguen llegando al jugador. Sin desborde: nada entra en un inventario.
scatter(spot, rewards)Para nadie: items y orbes de experiencia salen en el sitio. Devuelve lo que necesita una persona (comandos, dinero, recompensas con permiso o condición), sin tirar, para que lo entregue quien llama.
deliver(uuid, rewards)Esté o no: conectado en este servidor se entrega en su hilo; si no, se guarda con giveLater. Si se va a mitad de la entrega, queda en cola.
deliver(uuid, rewards, spot)Los items caen en el sitio cuando el jugador está conectado, a menos de 32 bloques y en el hilo que llama; si no, deliver(uuid, rewards).
deliver(uuid, stack) / deliver(uuid, template, amount)Un item, esté o no. amount se reparte en stacks del máximo del item.
giveLater(uuid, rewards)Guardarlas para alguien que no está.

Cada recompensa pregunta, en orden, permiso, luego condición, luego la tirada. Una que falla no le cuesta nada más de la lista.

java
List<RewardEntry> share = Rewards.scaled(pot, 0.25);   // un cuarto del dinero y la experiencia

Rewards.scaled multiplica el dinero (dos decimales) y la experiencia (puntos enteros), redondeando hacia abajo, y quita lo que queda en nada. Los items y el resto quedan igual. Los potenciadores van por Modifiers.rewards.

Decidida ahora, entregada después#

Para todo lo que enseña un premio antes de entregarlo, de modo que lo animado es lo que llega:

java
List<RewardEntry> pool = crate.rewards().stream().filter(r -> rewards.eligible(player, r)).toList();
RewardEntry won = rewards.settle(rewards.pick(pool));   // null cuando falló su probabilidad
// ... la animación muestra `won` ...
rewards.deliver(player.getUniqueId(), List.of(won));

eligible pregunta el permiso y la condición, en el hilo del jugador. settle tira la probabilidad y la cantidad ya y devuelve una recompensa con probabilidad 100, la cantidad fijada y sin permiso ni condición, así que el give o deliver posterior no vuelve a preguntar nada.

Resultados#

RewardDelivery guarda un RewardResult por recompensa: given(), skipped(), failed(), isClean(), failures().

ResultadoSignificaCuenta como
GIVENLo recibió.entregada
NOT_ROLLEDLos dados dijeron que no.saltada
NO_PERMISSIONFalta el permiso.saltada
CONDITION_FAILEDLa condición no se cumplió.saltada
NO_ROOMSin sitio, con FAIL.fallo
QUEUEDGuardada para su vuelta.—
FAILEDAlgo está roto.fallo

Una recompensa rota se reporta en consola una vez por problema, no una por jugador. Un comando cuyo plugin lanza un error, o que la consola rechaza, es un único aviso que nombra el comando, sin traza.

Inventarios llenos#

java
rewards.overflow(OverflowPolicy.QUEUE);
PolíticaHace
DROPTira a sus pies lo que no cabe. Por defecto.
QUEUEGuarda lo que sobra para luego. Necesita un almacén de pendientes; si el almacén lo rechaza, se tira y se dice en consola.
FAILSe rinde y reporta NO_ROOM.

Lo que se encola es lo que sobró: si recibió cuatro de seis, se le deben dos, con cantidad fija y probabilidad 100. El permiso y la condición se conservan y se vuelven a comprobar al entregarla.

Recompensas pendientes#

Tres líneas son toda la cola, tabla y listener de entrada incluidos:

java
rewards = Rewards.of(this)
        .overflow(OverflowPolicy.QUEUE)
        .pending(PendingRewards.database(this))
        .claimOnJoin((player, delivery) -> messages.claimed(player, delivery.given()));

PendingRewards.database(plugin) escribe en exylia_pending_rewards en la base de datos de tu propio plugin — lo que diga plugins/<Plugin>/database.yml, H2 en un archivo por defecto. ExyliaLib no tiene base de datos propia. Dos plugins sobre la misma base comparten la tabla, distinguidos por una columna con su nombre. Un jugador tiene un tope de 200 lotes pendientes por plugin; pasado eso la escritura se rechaza y se dice una vez en consola.

LlamadaQué hace
claimOnJoin() / claimOnJoin(then)Entrega lo pendiente en cada entrada. then solo se llama si se debía algo. Se registra una vez aunque se llame varias.
claim(player, then)Lo mismo a mano. El almacén se lee fuera del hilo principal y la entrega vuelve al del jugador.
claim(player, batchId, then)Un lote, dejando el resto.
pending.count(uuid)Cuántos lotes esperan, para una línea de "tienes 3 recompensas". Fuera del hilo principal.

El almacén suelta las recompensas antes de la entrega, así un fallo no puede duplicar una. Si el jugador muere, sale o cambia de servidor mientras la lectura está en vuelo, se le vuelven a deber en vez de perderse.

Para el staff#

/exylialib pendingrewards [jugador] (permiso exylialib.pendingrewards, op por defecto) lista quién tiene recompensas pendientes en todos los plugins, cada lote que se le debe, y permite darlo ya o cancelarlo. Cancelar pide confirmación dos veces. Desde la consola imprime un resumen.

Tu propio almacén#

Sigue implementando PendingRewards cuando las filas ya existen en otro sitio — ExyliaCapture y ExyliaEvents tienen cada uno su tabla.

java
rewards.pending(new PendingRewards() {
    public void keep(UUID player, List<RewardEntry> owed) {
        tasks.runAsync(() -> repository.save(new PendingReward(player, owed)));
    }
    public List<RewardEntry> claim(UUID player) {
        return repository.takeAllFor(player);
    }
});

Responde también browsable(), owed(), peek(uuid) y take(uuid, batch) y la pantalla del staff podrá listarlo y actuar sobre él; sin ellos lo muestra como un almacén en el que no puede mirar.

`keep` corre en el hilo que debía la recompensa

Escribir en la base de datos ahí en línea es un parón del hilo principal: prográmalo y vuelve. claim es lo contrario — ya está fuera del hilo principal, así que lee directamente, y nunca devuelvas las mismas recompensas dos veces.

Construir en código#

java
RewardEntry coins = RewardEntry.economy("500")
        .name("{primary}&lSTARTER BONUS")
        .chance(50.0)
        .permission("event.vip")
        .build();

Fábricas: command, message, item, economy, experience, potion, of(type). RewardEntry es inmutable: toBuilder() edita y conserva el id, copy() duplica con uno nuevo. Las cantidades se fijan con fixedAmount(n) o amountBetween(min, max).

Rewards.snapshot(stack) guarda un item como bytes: idéntico byte a byte a ExyliaCommons, y RewardCodec.encode/decode es la columna de la base de datos: los campos iguales a su valor por defecto se omiten, y una lista vacía se guarda como NULL.

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