Rewards
What a player earned: items, commands, money, experience and effects, with odds, conditions and a queue for whoever is not there.
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.
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#
| Type | Payload |
|---|---|
COMMAND | command, run by the console, with or without a leading /. %player_name% is the player. |
ITEM | itemSnapshot: a material, a head string or bytes:. |
MESSAGE | message, in Exylia text notation. |
ECONOMY | value as text, plus an optional currency; blank is the default currency. |
EXPERIENCE | value, in points. |
POTION | value, 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#
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:
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| Key | Meaning |
|---|---|
name | What the reward is called in menus and messages. |
itemAmount | A fixed stack size. |
minAmount / maxAmount | A random amount, both ends included; wins over itemAmount. For money and experience it is the amount paid. |
chance | Percent, 0–100: does this one happen. 100 never rolls. |
weight | Which one happens, for roll and pick. Default 1; 0 or less is never picked. |
permission | Needed to receive it. |
condition | %player_level% >= 10. Operators >=, <=, >, <, ==, !=, or true/false. == and != compare text, case-insensitively. |
deliveryMessage | Sent when it lands. |
priority | Higher is given first; equal priorities keep file order. |
icon | What a menu draws it as. |
A row that cannot be read is reported and skipped; the rest still load.
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#
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.
| Asked | What 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 item | The 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 items | One window takes any number of items and adds one item reward per stack. |
| Several commands | One command per line, one reward per command. |
| Money | The amount and a currency picker. |
| Experience | The least and most points. |
| A potion | The effect list opens on submit, including for a new reward with no effects yet. |
| Edit all | Chance, 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:
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#
| Call | What 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.
List<RewardEntry> share = Rewards.scaled(pot, 0.25); // a quarter of the money and experienceRewards.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:
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().
| Outcome | Means | Counts as |
|---|---|---|
GIVEN | They got it. | given |
NOT_ROLLED | The dice said no. | skipped |
NO_PERMISSION | Missing permission. | skipped |
CONDITION_FAILED | The condition did not hold. | skipped |
NO_ROOM | No room, under FAIL. | failure |
QUEUED | Kept for their return. | — |
FAILED | Something 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#
rewards.overflow(OverflowPolicy.QUEUE);| Policy | Does |
|---|---|
DROP | Drops what does not fit at the player's feet. Default. |
QUEUE | Keeps the leftover for later. Needs a pending store; if the store refuses it, it is dropped and said in the console. |
FAIL | Gives 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:
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.
| Call | What 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.
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.
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#
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