Repository navigation
Rewards
br.com.finalcraft.evernifecore.logic.reward pays a RewardTable - an ordered list of steps, each a RewardRule -
through RewardTable.pay(context). A step itself (eligibility, distribution, absent, moment, leaver/joiner, effects) is
described in Groups; this page covers how a plugin describes who takes part in a payment and
what its texts read (the scene and the occasion), the table and its receipt, tables keyed by phase, and the command node a plugin mounts to export and simulate them.
A RewardOccasion is a kind of payment the plugin declares in code, once: its id, the marks a participant may carry
and the {variables} a scene of it fills.
RewardOccasion raid = RewardOccasion.builder(plugin, "raid")
.phase("stage") // what its phase keys count; "phase" when not said
.marks("alive", "mvp")
.variables("stage", "boss")
.sample(scene -> scene.participant(UUID.randomUUID(), "Steve", BigDecimal.TEN, "alive").variable("stage", 5))
.build();player, player-uuid, owner, caller, amount and share (RewardOccasion.ALWAYS_ACCEPTED) are read by every
reward text and cannot be declared again. getSample() is the sample scene, built under the occasion when it is built
(a mark or variable it does not declare is refused then); empty when not declared.
RewardRule.parse(plugin, occasion, node) reads a rule as RewardRule.parse(plugin, node) does, and first refuses a
{variable} in any of its texts that the occasion does not give. Accepted: the occasion's variables, the six above and
every registered Variable ({level}, {finaljobs:level}). %placeholders% are not checked. The refusal names the
variable, lists the accepted ones and the way out (.variables("<name>") on the occasion).
A RewardScene describes one payment under an occasion: the participants - uuid, the name the plugin knows them by, the
contribution (zero or more) and the marks - plus the occasion's variables. A mark or variable the occasion does not
declare, a participant added twice, a blank name or a negative contribution is refused when the scene is built.
RewardScene scene = RewardScene.builder(raid)
.participant(steve, "Steve", new BigDecimal("1200"), "alive", "mvp")
.participant(bob, "Bob", new BigDecimal("300")) // left the raid: no "alive"
.variable("stage", 5)
.build();
RewardContext ctx = RewardContext.builder(Caller.of(plugin, "raid/stage-5"), ProgressOwner.global())
.scene(scene)
.attribute("arena", arena) // for a piece or effect of the plugin's own
.build();
table.pay(ctx);With a scene:
-
The candidates are the participants, in the scene's order - members of no owner included. The owner's membership
and the leaver rule are not asked; the owner still names whose reward it is (events, audit,
role:). -
The contributions are the participants': a
RewardContextwith a scene and.contributions(...)is refused. -
{player}is the participant's name, online or offline - it wins over the last name the server saw. -
Every effect reads the scene's variables (
Stage {stage} cleared!).
A step builds one ExecutionContext per paid member, and the condition eligibility tests that same context.
It carries the member (online) or its uuid as owner with the pending destination (offline), every attribute of the
RewardContext (ctx.getAttribute("arena", Arena.class)) and, under a scene, the scene's variables and the
participant's {player}, plus {amount}, {base-amount} and {share} (below). So condition: { type: compare, variable: stage, op: '>=', amount: 5 } reads the scene's
stage: compare reads a variable written in the context before a registered one, as a resolved text does.
A pending delivery (an offline member's share kept for the next login) stores the effects and the variables the
context had written (Delivery.getVariables()): on the claim, {stage} and {player} resolve as the scene had them -
the participant's name, not the login's - and anything else reads the claiming player.
eligibility: { type: mark, mark: alive } # the participants carrying the mark
eligibility:
type: any-of # whoever one of the list accepts
of: [ { type: mark, mark: mvp }, { type: top, count: 3 } ]
eligibility: { type: not, of: { type: mark, mark: alive } } # whoever the inner one does not accept-
markreads the scene's participants: nobody without a scene. Read under an occasion, a mark it does not declare is refused with the declared ones listed; read with no occasion (RewardRule.parse(plugin, node), a quest) anymarkis refused - also one nested inany-of/not. -
any-ofandnotnest any eligibility (of:is a list forany-of, one node fornot) and serve any rule, a quest's included. In code:Eligibility.mark("alive"),Eligibility.anyOf(...),Eligibility.not(...).
- name: stage-announcement
once: true
effects:
- { type: command, command: "broadcast Stage {stage} cleared" }The effects apply one time, on the main thread, from the console: no player, the reward's attributes and the
scene's variables - even when the scene has no participant. Its receipt step has no line; it posts no
RewardPaidEvent and writes one REWARD_PAID audit line. With eligibility, distribution, absent, leaver or
joiner the rule is refused on load, the message naming the key, why it does not apply and the way out;
RewardRule.builder().once(true) with an eligibility, distribution, absence or membership set is refused by build()
with the same message (IllegalStateException). A target
(online-players) is the way to reach players from a once rule.
name: bonus-alive is optional; RewardRule.getName() returns it and the REWARD_PAID audit line of every payment of
the rule starts with reward 'bonus-alive'.
An effect with a target other than self in a rule that is not once logs a warning on the caller's log, naming the
step by its index in the table and its name (step 2 'everyone-online') and the target: the eligibility picks N members and the effect reaches its targets once
per member - N times. Write once: true, or drop the target.
Every effect takes offline: run | skip | on-login (see Logic): for an offline member,
skip applies nothing and audits EFFECT_SKIPPED, on-login keeps the effect as a delivery claimed on the next login
(with the scene's variables, above). A message to an offline participant writes offline: on-login to reach them.
RewardTable table = RewardTable.parse(plugin, raid, node); // a list of steps; one step may skip the list
RewardReceipt receipt = table.pay(ctx).join(); // or thenAccept: completes once every step applied
RewardReceipt dryRun = table.preview(ctx); // the same receipt, nothing appliedpay runs the steps in order: a step starts once the previous one applied or kept all its effects. A step that
cannot be read is refused naming its index and name (The reward step 2 'alive': ...). A step asking for role: on an
owner that is not a group refuses the whole table before anything is paid. RewardTable.of(steps) builds one in code -
a single rule pays as a one-step table; there is no other way to pay.
The RewardReceipt has one Step per step (getIndex(), getName(), isOnce(), isRun() - false when its
moment did not take the trigger) and, per member, a Line: getShare() (0-1), getAmount() and getStatus():
| Status | Means |
|---|---|
ONLINE |
applied to the member |
DELIVERED |
the offline member's share waits as a pending delivery (absent: deliver) |
LOST |
not paid: offline under absent: forfeit, or redistribute with nobody eligible online |
REDISTRIBUTED |
not paid to the offline member: split among the online eligible, whose lines carry it |
receipt.getAmount(uuid) sums what every step paid a member (ONLINE and DELIVERED lines). preview answers the
receipt pay would answer - who is online is read when it is called - and applies no effect, keeps no delivery, posts
no RewardPaidEvent and writes no audit line.
Every effect of a member's payment reads {base-amount} - what the step's effects with an amount give that member,
after the distribution (Effect.getAmount, answered by money; summed when there are several) -, {amount} - that
times the member's booster multiplier, what the wallet gets - and {share}, its part of the step, 0-1. Without
boosters the two amounts are the same number. add divides by the share too but has no amount, so neither counts it:
- distribution: proportional
effects:
- { type: money, amount: 2000, currency: "raid:gold" }
- { type: message, text: "Your part of the pool: {amount} ({share})" } # 900 (0.45) for 900 of 2000A delivery keeps them with the other variables, so the login reads the same numbers.
A reward multiplies only when the plugin that pays it says, in code, which of its booster domains count - nothing in the reward's YAML names a booster:
// at start: the domain, its join and the factors its permission may grant
WIN = BoosterDomain.of(plugin, "win").join(BoosterJoin.sumBonus().cap(new BigDecimal(3)))
.permission("duels.booster.win", 2).register();
// at the win
RewardContext ctx = RewardContext.builder(Caller.of(plugin, "duel"), ProgressOwner.global())
.scene(scene).boostedBy(WIN).build();
table.getTable(round).pay(ctx);- effects:
- { type: money, amount: 500, currency: "duels:coins" }
- { type: message, text: "+{amount} (base {base-amount})" }Ana holds duels.booster.win.2 and a granted +50%: the join sums the bonuses, 1 + 1 + 0.5 = 2.5 (under the cap of
3). Her line of the receipt reads getBaseAmount() 500, getMultiplier() 2.5, getAmount() 1250; her wallet gets
1250 and her chat +1250 (base 500).
- The multiplier is resolved once per member and step, when the receipt is settled (
domain.resolveof the member's context - online, every source; offline, the boosters aBoosterManagergranted), and frozen on the line. Several domains multiply together (boostedBy(A, B): 2 x 1.5 = 3), as a shop sale's do. - The
moneyeffect pays exactly{amount}: the payment hands it the frozen multiplier (Rewards.MULTIPLIER_ATTRIBUTE) and it resolves no booster. A plugin's own effect with an amount may read that attribute to multiply the same way. - An offline member's pending delivery keeps the final number: the login pays 1250 even if the booster ended in between.
-
previewandpaysettle the same receipt, multipliers included. - Without
boostedBynothing multiplies, and amoneyoutside a reward (a region's effect, a screen's choice, a logic command) never does.
A plugin whose payment repeats by stage, wave, position or place writes a map of phase keys to tables, read by
PhasedRewardTable.parse(plugin, occasion, node):
5: [ ... ] # exactly 5
4-10: [ ... ] # 4 to 10, both included
10+: [ ... ] # 10 and up
every 5: [ ... ] # 5, 10, 15...
default: [ ... ] # what no other key takesgetTable(phase) answers the table of the most specific key that takes the phase - exact, then the narrowest range,
then the highest N+, then the largest every N, then default - or an empty table when none does; getKey(phase)
names the key. Two keys of one kind that take a common phase must nest (4-10 inside 1-20, every 10 inside
every 5); otherwise the load refuses them, naming both and a phase they share (4-10 and 8-12 both take 8). A key
that is no phase is refused listing the forms, worded with the occasion's phase.
-
MazeArena, by position:
1,2,4-10,default- position 6 is paid by4-10, 11 bydefault. -
MobArena, by wave:
every 5anddefault- wave 10 is a boss wave, wave 7 takesdefault.
PhasedRewardTable waves = PhasedRewardTable.parse(plugin, waveCleared, config.get("rewards"));
waves.getTable(wave).pay(RewardContext.builder(Caller.of(plugin, "wave"), ProgressOwner.global()).scene(scene).build());The core has no reward command. A plugin mounts RewardCommandNode (logic.reward.command) under its own command,
in the mold of RegionCommandNode, and hands it its occasions and where each one's rewards are read from:
@FinalCMD(aliases = "raid")
public class RaidCommand {
@FinalCMD.Node(subcmd = "rewards", permission = "raid.rewards")
private final RewardCommandNode rewards = new RewardCommandNode(ecPluginData, "raid.rewards")
.occasion(STAGE_WON, () -> config.getNode("Rewards.stage-won"), STAGE); // STAGE: the domain its payment is boostedBy
}The supplier answers the occasion's map of phase keys (what PhasedRewardTable.parse reads) and is asked again on
every verb, so an edited and reloaded file is what shows. An occasion of another plugin, or one added twice, is
refused. The mount's permission is the door; the permissionBase (optional) adds <base>.export and
<base>.simulate. The node sees nothing but what the plugin gave it: there is no server-wide list of occasions.
-
/raid rewards exportwrites<raid data folder>/export/rewards.jsonand answers with its absolute path. -
/raid rewards simulate <occasion> <phase>reads the occasion's rewards, takes the table of<phase>and prints the receipt of itspreviewon the occasion's sample scene (RewardOccasion.Builder.sample): one line per step (index from 0,name, how many members;once, from the console; ordoes not pay at this moment) and one per member (name, share,{base-amount} × multiplier = {amount}-amount 500 × 2.5 = 1250,× 1when no booster counts -,online/delivered/lost/redistributed). The multiplier is the one the payment would freeze, from the domains the node was given with the occasion: an online participant's boosters, and for one offline only what aBoosterManagergranted them (a made-up sample uuid gets 1). Nothing is applied - no effect, no delivery, no event, no audit line.<occasion>completes with the node's occasions; an unknown one is answered with the list; rewards that do not read are answered with the load error.
The export is the input of the reward editor; this section is its contract. It is the plugin's config already read into JSON: YAML anchors and aliases come resolved, so the editor writes back YAML without them.
The reward editor is a local static page, kept outside this repository: it opens the export from disk, repeats the
load's refusals in the browser, simulates a phase on the occasion's sample (the receipt preview gives) and writes the
occasion's YAML back. RewardEditorRoundTripTest proves the core reads what it writes: the fixtures under
common/src/test/resources/rewards/editor/ are an export of the test raid and the YAML the editor wrote from it, as
read and after one edit.
| Field | What it holds |
|---|---|
format |
1, the version of this shape (RewardCommandNode.FORMAT). A field that changes meaning or goes away bumps it. |
plugin |
The name of the plugin that mounted the node. |
platform |
IPlatform.getPlatformProviderId() of the server that wrote it. |
types |
The types a reward can write, by kind: effect, condition, variable, and the reward pieces by role - eligibility, distribution, absence, moment, membership. A piece whose plugin did not declare its role (TypeDescriptor.Builder.category) lands under reward-piece. Every registered type is listed, whoever registered it; registration order. |
effect-modifiers |
The keys every effect takes besides its own params (delay, chance, if, repeat, every, as, target, scope, to, offline), each shaped as a param. |
always-accepted |
The {variables} every reward text reads (RewardOccasion.ALWAYS_ACCEPTED). |
domains |
The plugin's registered booster domains (Boosters.getDomains): id (<plugin>:<name>), join (sum-bonus, max or product, then cap N when capped), permission-prefix (null when no permission boosts it) and permission-factors (the factors <prefix>.<factor> may grant, ascending). |
occasions |
The node's occasions, in the order they were added. |
A type (TypeReference.toJson): key (owner:name), name (the bare name a definition writes), category (its
role, or null), registered-by (plugin name), aliases, description, platforms (empty = every platform), sources
(event sources), capabilities (player capabilities), unsupported (why THIS server cannot run it, or null) and
params.
A param: name, kind (STRING, NUMBER, BOOLEAN, DURATION, TEXT, ID, LIST, NODE, NODE_LIST,
WINDOW, OWNER), required, default (null for none; a number as a number, a duration in seconds as "600s"),
one-of (the accepted values; empty = any), nested (for NODE/NODE_LIST, the kind its children are read by:
condition, reward-piece, ...; else null) and description.
An occasion: id, phase (what its keys count), marks, variables, sample (participants: uuid, name,
contribution, marks; variables: name to text), boosted-by (the ids of the domains the node was given for it -
what its payment is boostedBy) and rewards (the supplier's JSON, as is; null when it answers none).
An excerpt of a real export, written by RewardCommandNodeTest for a raid mounted over raid-stage-5.yml
(lists cut with ...):
{
"format" : 1,
"plugin" : "FakeRaid",
"platform" : "test",
"types" : {
"effect" : [ ... ],
"condition" : [ ... ],
"variable" : [ ... ],
"eligibility" : [ {
"key" : "evernifecore:mark",
"name" : "mark",
"category" : "eligibility",
"registered-by" : "EverNifeCore",
"aliases" : [ ],
"description" : "The participants of the scene carrying a mark; only on a rule read under an occasion that declares it.",
"platforms" : [ ],
"sources" : [ ],
"capabilities" : [ ],
"unsupported" : null,
"params" : [ {
"name" : "mark",
"kind" : "ID",
"required" : true,
"default" : null,
"one-of" : [ ],
"nested" : null,
"description" : "A mark the occasion declares, e.g. alive."
} ]
}, ... ],
"distribution" : [ ... ],
"absence" : [ ... ],
"moment" : [ ... ],
"membership" : [ ... ]
},
"effect-modifiers" : [ ..., {
"name" : "offline",
"kind" : "STRING",
"required" : false,
"default" : "run",
"one-of" : [ "run", "skip", "on-login" ],
"nested" : null,
"description" : "With the player offline: apply now, skip it, or wait for the next login; a command run as: player waits by default."
} ],
"always-accepted" : [ "player", "player-uuid", "owner", "caller", "amount", "base-amount", "share" ],
"domains" : [ ],
"occasions" : [ {
"id" : "stage-won",
"phase" : "stage",
"marks" : [ "alive", "dead" ],
"variables" : [ "stage", "faction", "boss" ],
"sample" : {
"participants" : [ {
"uuid" : "8b6d73e0-3d96-49c6-a7c4-dbc24286c74d",
"name" : "Ana",
"contribution" : 900,
"marks" : [ "alive" ]
}, ... ],
"variables" : { "stage" : "5", "faction" : "Dragons", "boss" : "MewTwo" }
},
"boosted-by" : [ ],
"rewards" : {
"5" : [ {
"name" : "congrats",
"effects" : [ { "type" : "message", "text" : "Congrats! Stage {stage} beaten! {boss} is down." } ]
}, ... ],
"default" : [ ... ]
}
} ]
}EverNifeCore · Home · made by Petrus Pradella
Getting Started
Commands & Text
Player Data & Storage
- PlayerData & PDSections
- Accounts
- Storage Backends
- Inline Backends for Plugins
- Block Data (SVWorldDataManager)
- Legacy Data Migration
- Cooldowns
Config & Minecraft Systems
- Configuration
- Logging & Debug Modules
- Events
- Regions
- Groups
- Notifications
- NPCs
- Logic
- Quests
- Rewards
- Provenance
- Scheduler & Threading
- Items & NBT
- Screens
- Dialogues
- Menus
- Integrations
- Economy
- Boosters
- Deliveries
- Audit Log
- Dynamic Values
- Player Ignore
- Version Compatibility
Architecture & Reference