Adding Rewards

Let's take a look at how to add rewards to your voucher!

Defining Reward Quantities

Firstly, we need to consider how many rewards should be given whilst redeeming a voucher. This could just be 1 reward or it could be anything like 5 rewards, 100 rewards, or even a million. A common requirement for vouchers is that 1 of each reward is given, regardless of weighting. This is also possible. To define the reward quantity, create a field named RewardsPerOpen, an example is below:

# The number of rewards that will be given upon redeeming the voucher
# Set to 'all' to give a player every item within the voucher (ignoring weighting)
RewardsPerOpen: 1

As mentioned, this value can be set to the number of rewards to be given, or to the value of 'all' to ignore all weighting and give one of each reward in the voucher.

Adding the Rewards

To add rewards to your voucher, you will first need to add (or locate) the Rewards: field. This is a parent field, sub-fields will be included representing each individual reward.

To add a reward, we first need to create the reward ID. We find it helpful to use incrementing numbers to better keep track of all of the available rewards. However, this can realistically be anything.

Let's create a sample reward with ID 1 in our voucher file:

# The list of rewards within the voucher, currently a voucher supports up to 28 items, any extra items are ignored
Rewards:
  1:
    # The name of the reward
    Name: ''
    # The icon of the reward
    Icon:
      Item: ''
      Amount: 1
    # The weighted chance of getting the item, higher weight = higher chance (Doesn't have to add up to 100)
    # If a weighting isn't provided, the item will automatically assume a weight of 100
    Weight: 100
    # The command to be ran if this reward is given to the user, use <playerName> as a placeholder for the players name
    Commands:
      - ''
    # The message sent when a player wins this prize, this message is sent immediately after the commands are run to allow any PAPI placeholders to update
    # You can delete this field if you would rather no message was sent
    Message: ''
    # The lore for the reward when previewed in the GUI
    GUILore:
      - ''

Now that we have a sample reward, let's look at each field in more detail:

Name

This is the name of the reward, players may be presented with this when previewing rewards through the official preview GUI.

---

Icon

Item

This is the item to be used as the icon for the reward, it can be any material in minecraft from the following list: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html (excluding AIR and CAVE_AIR)

Amount

This is the quantity of item to be used for the icon, the value should be between 1 and 64, representing a valid minecraft Item Stack

---

Weight

If the RewardsPerOpen field is not set to 'all', weight is an important aspect of the voucher. This will determine the chance of a user receiving that item when opening the voucher.

The best way to consider weight without a deeper understanding of statistics is like a raffle entry. Consider the weight value of a reward to be the number of raffle tickets entered into a big prize pool for that reward. Each rewards weight enters its associated number of raffle tickets. Then, when the voucher is used, a raffle ticket is pulled at random and the associated reward is provided. Evidently, the bigger the weight, the more likely a player is to receive that reward.

If you don't include the Weight field in your reward, but RewardsPerOpen is not set to 'all', the reward will automatically inherit the weight: 100

---

Commands

This is a String-List of all the commands to be executed when a player receives that reward. All commands are executed through the console.

You may use the built-in placeholder <playername> to represent the voucher user's name, or any PAPI placeholder in the commands list.

---

Message

This is the message sent to the user if that reward is given to them.

---

GUILore

This is the lore item of the reward icon shown within preview windows for the voucher.

You may use the placeholder <chance> to represent the percentage chance of acquiring that reward. This value is calculated based on the weight of all rewards, as well as the state of the RewardsPerOpen field

Closing Notes

Creating rewards may be difficult at first, but gets significantly easier with practice. Take a look at our Example Vouchers for some inspiration and guidance on how to create awesome rewards for your server!