🎁 Rewards

EventForge rewards are command-based.

This means rewards work with most economy plugins, crate plugins, permissions plugins, item plugins, rank plugins, and custom server commands.

Rewards can be given for:

participating in an event
placing on the leaderboard
winning chance-based bonus rewards

Reward placeholders

Reward commands support EventForge placeholders.

Placeholder	Description
`{player}`	Player name
`{uuid}`	Player UUID
`{event}`	Event ID
`{event_display}`	Event display name
`{score}`	Player score
`{position}`	Leaderboard position, if available
`{var:key}`	Event variable

Example:

commands:
  - "eco give {player} 250"
  - "say {player} earned a reward from {event_display}!"

Participation rewards

Participation rewards are given to players who take part in an event and meet the minimum score.

rewards:
  participation:
    enabled: true
    minimum-score: 1
    commands:
      - "eco give {player} 100"
      - "give {player} emerald 2"

In this example, players need at least 1 point to receive the participation reward.

Minimum score

minimum-score controls how much score a player needs before they qualify.

rewards:
  participation:
    enabled: true
    minimum-score: 10
    commands:
      - "eco give {player} 250"

If a player scores less than 10, they will not receive that reward.

tip

Use minimum-score to stop players from joining an event and earning rewards without actually participating.

Leaderboard rewards

Leaderboard rewards are given by final placement.

rewards:
  leaderboard:
    1:
      commands:
        - "eco give {player} 1000"
        - "give {player} diamond 3"

    2:
      commands:
        - "eco give {player} 500"
        - "give {player} diamond 2"

    3:
      commands:
        - "eco give {player} 250"
        - "give {player} diamond 1"

The number is the leaderboard position.

= first place
= second place
= third place

Chance rewards

Chance rewards are optional bonus rewards.

They can be used under:

rewards.participation.chance-rewards
rewards.leaderboard.<position>.chance-rewards

A chance reward uses a percentage chance.

chance-rewards:
  rare_key:
    chance: 5.0
    commands:
      - "crate key give {player} rare 1"

In this example, the player has a 5% chance to receive the rare key.

Participation chance rewards

You can add chance rewards to participation rewards.

rewards:
  participation:
    enabled: true
    minimum-score: 1
    commands:
      - "eco give {player} 100"

    chance-rewards:
      bonus_key:
        chance: 10.0
        commands:
          - "crate key give {player} event 1"

      lucky_diamond:
        chance: 3.5
        commands:
          - "give {player} diamond 1"

This gives every qualifying participant the normal reward, then rolls the configured chance rewards.

Leaderboard chance rewards

You can also add chance rewards to leaderboard positions.

rewards:
  leaderboard:
    1:
      commands:
        - "eco give {player} 1000"

      chance-rewards:
        champion_bonus:
          chance: 25.0
          commands:
            - "crate key give {player} legendary 1"

    2:
      commands:
        - "eco give {player} 500"

      chance-rewards:
        runner_up_bonus:
          chance: 10.0
          commands:
            - "crate key give {player} rare 1"

This is useful when you want winners to always receive something, but still have a chance at an extra bonus.

Chance rules

Chance values are percentages.

0 = 5%
0 = 25%
0 = guaranteed

Rules:

chance must be greater than 0
chance above 100 is treated as 100
empty command lists are skipped

warning

Do not set chance to 0. If you do not want the reward to roll, remove it or disable that section.

Using variables in rewards

Reward commands support event variables with {var:key}.

variables:
  reward_name: "Mining Tokens"
  reward_amount: "250"

rewards:
  participation:
    enabled: true
    minimum-score: 1
    commands:
      - "eco give {player} {var:reward_amount}"
      - "say {player} earned {var:reward_name}!"

This is useful when the same reward name, crate name, currency name, or amount is used in several places.

Full reward example

variables:
  reward_name: "Ancient Cache"

rewards:
  participation:
    enabled: true
    minimum-score: 1
    commands:
      - "eco give {player} 100"
      - "say {player} earned the {var:reward_name} participation reward."

    chance-rewards:
      bonus_cache:
        chance: 10.0
        commands:
          - "crate key give {player} ancient 1"
          - "say {player} found a bonus {var:reward_name}!"

  leaderboard:
    1:
      commands:
        - "eco give {player} 1000"
        - "give {player} diamond 3"

      chance-rewards:
        champion_bonus:
          chance: 25.0
          commands:
            - "give {player} netherite_scrap 1"

    2:
      commands:
        - "eco give {player} 500"
        - "give {player} diamond 2"

    3:
      commands:
        - "eco give {player} 250"
        - "give {player} diamond 1"

Command tips

Commands are run from console.

Do not include / at the start.

Good:

commands:
  - "eco give {player} 100"

Bad:

commands:
  - "/eco give {player} 100"

Troubleshooting

Reward did not run

Check:

The event finished normally
The player scored enough points
The command works from console
The command does not start with /
The placeholder names are correct

Participation reward did not run

Check the minimum score:

minimum-score: 1

If the player scored 0, they will not qualify.

Leaderboard reward did not run

Check that the player placed in a configured position.

Example:

leaderboard:
  1:
    commands:
      - "eco give {player} 1000"

Only first place receives that reward.

Chance reward did not run

Chance rewards are not guaranteed unless the chance is 100.

chance: 100.0

Use this for testing.

Console says the command is unknown

Test the command manually from console first.

If the command belongs to another plugin, make sure that plugin is installed and loaded.