Skip to content

Rewards

Pétrus Pradella edited this page Nov 14, 2026 · 7 revisions

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.

Occasion

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.

Reading a rule under an occasion

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).

Scene

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 RewardContext with 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!).

What a payment's effects see

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.

Choosing participants: mark, any-of, not

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
  • mark reads 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) any mark is refused - also one nested in any-of/not.
  • any-of and not nest any eligibility (of: is a list for any-of, one node for not) and serve any rule, a quest's included. In code: Eligibility.mark("alive"), Eligibility.anyOf(...), Eligibility.not(...).

once: true

- 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

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'.

target inside a rule

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.

offline: on any effect

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.

The table and its receipt

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 applied

pay 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.

{amount}, {base-amount} and {share}

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 2000

A delivery keeps them with the other variables, so the login reads the same numbers.

Boosted payments: boostedBy

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.resolve of the member's context - online, every source; offline, the boosters a BoosterManager granted), and frozen on the line. Several domains multiply together (boostedBy(A, B): 2 x 1.5 = 3), as a shop sale's do.
  • The money effect 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.
  • preview and pay settle the same receipt, multipliers included.
  • Without boostedBy nothing multiplies, and a money outside a reward (a region's effect, a screen's choice, a logic command) never does.

Tables by phase

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 takes

getTable(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 by 4-10, 11 by default.
  • MobArena, by wave: every 5 and default - wave 10 is a boss wave, wave 7 takes default.
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 command node: export and simulate

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 export writes <raid data folder>/export/rewards.json and 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 its preview on the occasion's sample scene (RewardOccasion.Builder.sample): one line per step (index from 0, name, how many members; once, from the console; or does not pay at this moment) and one per member (name, share, {base-amount} × multiplier = {amount} - amount 500 × 2.5 = 1250, × 1 when 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 a BoosterManager granted 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 format (format 1)

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" : [ ... ]
    }
  } ]
}

Clone this wiki locally