Content generated with AI — it may contain mistakes.

ExyliaLib/Gameplay

Rewards

What a player earned: items, commands, money, experience and effects, with odds, conditions and a queue for whoever is not there.

Page 44 of 549 min read

A reward list is items, commands, money, experience, messages and potion effects with odds and conditions, edited in-game and stored exactly as ExyliaCommons stored it.

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

Money pays through the economy, and loot tables and crates live on Crates and loot.

Types#

TypePayload
COMMANDcommand, run by the console, with or without a leading /. %player_name% is the player.
ITEMitemSnapshot: a material, a head string or bytes:.
MESSAGEmessage, in Exylia text notation.
ECONOMYvalue as text, plus an optional currency; blank is the default currency.
EXPERIENCEvalue, in points.
POTIONvalue, one effect per line: SPEED|2|15.

An item reward is stored whole: the name, lore, enchantments and attributes it was given are what the player receives. A head reward stored as basehead-… or playerhead-… is handed over as a plain PLAYER_HEAD; store it as bytes: to keep the texture.

In a config file#

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

The keys are the stored field names, so a file and a database column say the same thing:

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}You won a key!"
    priority: 5
  - "broadcast %player_name% won"      # a bare string is a command
KeyMeaning
nameWhat the reward is called in menus and messages.
itemAmountA fixed stack size.
minAmount / maxAmountA random amount, both ends included; wins over itemAmount. For money and experience it is the amount paid.
chancePercent, 0–100: does this one happen. 100 never rolls.
weightWhich one happens, for roll and pick. Default 1; 0 or less is never picked.
permissionNeeded to receive it.
condition%player_level% >= 10. Operators >=, <=, >, <, ==, !=, or true/false. == and != compare text, case-insensitively.
deliveryMessageSent when it lands.
priorityHigher is given first; equal priorities keep file order.
iconWhat a menu draws it as.

A row that cannot be read is reported and skipped; the rest still load.

An unreadable condition gives the reward

A condition nobody can parse is reported once and treated as passing. It said who should be excluded, and a typo excludes nobody. A menu does the opposite: an unreadable condition there hides the slot.

Editing on screen#

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

Pagination, add, edit, delete, copy, paste, save and cancel. A reward copied in one plugin pastes into any other reward editor.

AskedWhat happens
What does it give?The type comes first, because it decides which fields the form has: a command is never asked for a stack size.
An itemThe icon picker, then a form filled from the item: its own name and the stack size put in. Editing it later does not ask for the item again.
Several itemsOne window takes any number of items and adds one item reward per stack.
Several commandsOne command per line, one reward per command.
MoneyThe amount and a currency picker.
ExperienceThe least and most points.
A potionThe effect list opens on submit, including for a new reward with no effects yet.
Edit allChance, weight, permission, condition and message applied to every row; blank keeps each row's own.

A list drawn by weight (a crate, roll, pick) uses the weighted editor:

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

Each row shows its real share of all drops counting weight, shift + left and shift + right raise and lower the weight in place, and a button sorts by weight. The extra lines are optional and asked again on every redraw.

Giving#

CallWhat it does
give(player, rewards)Every reward, each checked and rolled on its own. On the player's thread.
give(player, reward)One.
giveOnPlayerThread(player, rewards, then)The same from any thread, moved onto the player's.
giveItem(player, stack)One ItemStack under the overflow policy.
roll(player, rewards)Exactly one, picked by weight; it still faces its own chance.
pick(rewards)Pick by weight without giving: a preview.
giveDropping(player, rewards, spot)Gives everything, but items are thrown out at the spot, one entity per stack. Money, commands and the rest still reach the player. No overflow, nothing goes into an inventory.
scatter(spot, rewards)For nobody: items and experience orbs come out at the spot. Returns what needs a person (commands, money, rewards with a permission or condition), unrolled, for the caller to give.
deliver(uuid, rewards)Here or not: online on this server it is given on their thread; otherwise kept with giveLater. A player who leaves mid-delivery is queued.
deliver(uuid, rewards, spot)Items drop at the spot when the player is online, within 32 blocks and on the calling thread; otherwise deliver(uuid, rewards).
deliver(uuid, stack) / deliver(uuid, template, amount)An item, here or not. amount is split into stacks of the item's max size.
giveLater(uuid, rewards)Keep them for somebody who is not here.

Each reward is asked, in order, permission, then condition, then the roll. One that fails costs nothing else on the list.

java
List<RewardEntry> share = Rewards.scaled(pot, 0.25);   // a quarter of the money and experience

Rewards.scaled multiplies money (two decimals) and experience (whole points), rounding down, and drops what comes to nothing. Items and the rest are kept as they are. Boosters go through Modifiers.rewards instead.

Decided now, handed over later#

For anything that shows a prize before handing it over, so what was animated is what arrives:

java
List<RewardEntry> pool = crate.rewards().stream().filter(r -> rewards.eligible(player, r)).toList();
RewardEntry won = rewards.settle(rewards.pick(pool));   // null when its chance missed
// ... the animation shows `won` ...
rewards.deliver(player.getUniqueId(), List.of(won));

eligible asks the permission and the condition, on the player's thread. settle rolls the chance and amount now and answers a reward with chance 100, the amount pinned and no permission or condition, so the later give or deliver asks nothing again.

Outcomes#

RewardDelivery holds one RewardResult per reward: given(), skipped(), failed(), isClean(), failures().

OutcomeMeansCounts as
GIVENThey got it.given
NOT_ROLLEDThe dice said no.skipped
NO_PERMISSIONMissing permission.skipped
CONDITION_FAILEDThe condition did not hold.skipped
NO_ROOMNo room, under FAIL.failure
QUEUEDKept for their return.—
FAILEDSomething is broken.failure

A broken reward is reported to the console once per problem, not once per player. A command whose plugin throws, or that the console refuses, is one warning naming the command, without a stack trace.

Full inventories#

java
rewards.overflow(OverflowPolicy.QUEUE);
PolicyDoes
DROPDrops what does not fit at the player's feet. Default.
QUEUEKeeps the leftover for later. Needs a pending store; if the store refuses it, it is dropped and said in the console.
FAILGives up and reports NO_ROOM.

What is queued is what was left over: four of six received means two owed, at a fixed amount and chance 100. Permission and condition are kept and checked again when it is handed over.

Pending rewards#

Three lines is the whole queue, table and join listener included:

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

PendingRewards.database(plugin) writes to exylia_pending_rewards in your own plugin's database — whatever plugins/<Plugin>/database.yml says, H2 in a file by default. ExyliaLib has no database of its own. Two plugins on the same database share the table, told apart by a column naming them. One player is capped at 200 waiting batches per plugin; past that the write is refused and said once in the console.

CallWhat it does
claimOnJoin() / claimOnJoin(then)Hands over what is owed on every join. then runs only when something was owed. Registered once however often it is called.
claim(player, then)The same by hand. The store is read off the main thread, delivery comes back on the player's.
claim(player, batchId, then)One batch, leaving the rest.
pending.count(uuid)How many batches are waiting, for a "3 rewards to claim" line. Off the main thread.

The store lets go of rewards before delivery, so a failure cannot duplicate one. If the player dies, quits or changes server while the read is in flight, the rewards are kept for them again rather than lost.

For staff#

/exylialib pendingrewards [player] (permission exylialib.pendingrewards, op by default) lists who is owed rewards across every plugin, each batch they are owed, and gives one now or cancels it. Cancelling asks twice. From the console it prints a summary.

Your own store#

Keep implementing PendingRewards when the rows already exist somewhere — ExyliaCapture and ExyliaEvents each keep their own table.

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);
    }
});

Answer browsable(), owed(), peek(uuid) and take(uuid, batch) too, and the staff screen can list and act on it; without them it shows the store as one it cannot look into.

`keep` runs on the thread that owed the reward

Writing to a database inline there is a stall on the main thread: schedule it and return. claim is the opposite — it is already off the main thread, so read directly, and never return the same rewards twice.

Building in code#

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

Factories: command, message, item, economy, experience, potion, of(type). RewardEntry is immutable: toBuilder() edits and keeps the id, copy() duplicates with a new one. Amounts are set with fixedAmount(n) or amountBetween(min, max).

Rewards.snapshot(stack) stores an item as bytes: byte-identical to ExyliaCommons, and RewardCodec.encode/decode is the database column: fields equal to their default are left out, and an empty list is stored as NULL.

Something missing on this page? Tell us on Discord