📌Voucher Configuration

This is an example configuration with all options defined. I will explain each of them below.

exclusive-armor:
  icon: ender_chest
  name: "&#666666Exclusive Armor Set"
  description:
    - "&ex1 &5Super&f Netherite Helmet"
    - "&ex1 &5Super&f Netherite Chestplate"
    - "&ex1 &5Super&f Netherite Leggings"
    - "&ex1 &5Super&f Netherite Boots"
  rewards:
    - "give %player_name% netherite_helmet 1"
    - "give %player_name% netherite_chestplate 1"
    - "give %player_name% netherite_leggings 1"
    - "give %player_name% netherite_boots 1"
  usage-limit: {global: 100, default: 1}
  condition: "%player_level% >= 5 && '%player_world%' == 'world'"

First, you have to define the voucher ID. This is used to distinguish vouchers (even when they have the same name)

For the icon, you can choose any Bukkit material. If it is unset, the default icon from the config.yml will be used.

Then you have to provide the name and description. The description is used for the item's lore. The final lore will contain the footer defined in the main configuration.

Required options are name and rewards

Custom item

It is possible to customize the voucher item such as a player skull (with custom skin), a book, coloured leather armour, etc

For details, check outCustom item

Rewards

rewards is a list of rewards the voucher will give to the player.

Since each reward has its own chance and requirement, there is a small possibility that no reward is given to the player, you can decide whether to keep the voucher in that case (see Main Configuration)

Read how to configure reward here: Reward

Condition

This option allows you to pre-check the voucher when the player attempts to use it. This is a boolean expression and supports PlaceholderAPI

For example: %player_level% >= 5 && '%player_world%' == 'world'

PlaceholderAPI will be parsed first before evaluating the expression, so assume that the player's level is 10 and the world is world, that expression will become 10 >= 5 && 'world' == 'world' and returns true

Supported operators: https://ezylang.github.io/EvalEx/references/operators.html Supported functions: https://ezylang.github.io/EvalEx/references/functions.html

Warning: Ensure you wrap the string between pairs of single quotes or double quotes (both the string placeholder and the value)

If the condition is invalid, the voucher is not usable. You can enable debug mode to inspect the error.

Usage limit

Vouchers has two kinds of usage limit: global and per-player. They are both defined in the same setting usage-limit

usage-limit:
  global: 100
  default: 3
  vip: 5 # vouchers.usage-limit.vip
  mvp: 10 # vouchers.usage-limit.mvp

Global and default and two reserved names. The global is used to check usage limit over the server, and the default is the fallback value when checking per-player usage limit.

Other names define per-player limit groups with their own permission. The plugin will prioritize the highest usage limit to check first. If none are met, it uses the default as the fallback.

So in the above example, the plugin will do the following stuff:

1. Check if the player has permission vouchers.usage-limit.mvp since this group has the highest limit.

2. If not met, check permission vouchers.usage-limit.vip

3. Otherwise, select the default limit which is 3

4. Global is not evaluated because it is a global limit

You can shorten the configuration if it is too long. This is a valid syntax in YAML.

usage-limit: {global: 100, default: 3, vip: 5, mvp: 10}

Cooldown

Unlike usage limit, there is no concept of global cooldown.

cooldown: 
  default: 180
  vip: 60 # vouchers.cooldown.vip
  mvp: 30 # vouchers.cooldown.mvp

The time is defined in second(s). The plugin will prioritise the group with the lowest cooldown time.

So in the example above, MVP will be evaluated first, then VIP. If none is met, the plugin uses the fallback value from default

Double-check

A functionality that requires players to confirm before redeeming a voucher

double-check: true # default is false

Physical identification

When this option is enabled, any physical instance of the voucher (as an item) will have its own identifier. When the player uses an instance, the physical identifier is marked as used. Since then, any item that still has that identifier cannot be used by any player.

This mechanism is a simple approach to avoid duping. The negative aspect is that because every instance of the item has its own physical identifier, the player cannot stack the item in a single slot.

physical-id: true # default is false

Full configuration example

Here is an example with all settings defined

new-year-voucher:
  icon: paper
  name: "&#fba041H&#f39747a&#ec8d4dp&#e48454p&#dc7b5ay &#d47260N&#cd6866e&#c55f6cw &#bd5672Y&#b54d79e&#ae437fa&#a63a85r"
  description:
    - "&ex500 &7EXP"
    - "&ex100 &7coins"
    - ""
    - "&710% chance to receive 30% extra"
  rewards:
    - "exp give %player_name% 500"
    - "eco give %player_name% 100"
    - "[chance=0.1] exp give %player_name% 150"
    - "[chance=0.1] eco give %player_name% 30"
    - "[broadcast] &c&l[!] &a&l%player_name%&f&l has redeemed New Year voucher"
    - "[sound] entity.firework_rocket.twinkle"
  usage-limit: {global: 100, default: 10, vip: 20, mvp: 30}
  cooldown: {default: 60}
  condition: "'%player_world%' == 'spawn'"
  double-check: true

• RGB text generator: https://www.birdflop.com/resources/rgb/