Primary Details

Let's take a look at the primary details of a voucher, and how to configure them!

There are 5 primary details of the voucher. They are as follows:

1. Standard Values

   1. The Voucher ID

   2. The Voucher Name

   3. The Voucher Icon Item

   4. Whether the Icon is enchanted

   5. The Voucher Primary Lore

2. Optional Values

   1. Server Use Limit

   2. Whether the voucher is previewable

Let's take a look at each one in a little more detail.

---

Standard Values

Voucher ID

The Voucher ID is determined by the file name. This is set when the file is created. For example, if you have a voucher file named Money.yml, the Voucher ID is Money. Whilst creating the voucher, it is fine to change the name of the file to reflect your needs for the ID. It is important to note that file names should only ever be one word, if you want the effect of having multiple, you could connect words with underscores or dashes, "like_this" "or-this" "never this".

Once your voucher is in circulation (Players have a copy of the voucher), you should never change the ID. An ID is assigned to a voucher item at creation, changing the file name (and thus actual ID) will not reflect with the players items, and thus they will not be able to use the voucher. In the case that this happens, you can always change the file name back (or make an exact copy with the old name), to continue support for the players voucher.

---

Voucher Name

The Voucher Name is one of the first fields in any voucher file. This is the name of the physical item that a player will be able to hold as the voucher. The name may include color codes, as well as hex. It may also be as many words as you need!

The name may be changed at any time without any effect on users who have a voucher with the old name.

Adding a name to a voucher file is mandatory for it to become a valid voucher. To do this, we include the following line in our voucher file:

# The name of the voucher, this is required for all created vouchers (Not to be confused with the ID, which is the file name)
Name: '&fMy &6&lFirst &fVoucher'

---

Voucher Icon Item

The Voucher Icon Item is the physical item that will be given to a player when they receive a voucher. This item is representative of what the voucher is, it may be any item in minecraft, see: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html

The icon item may be changed at any time without any effect on users who have a voucher with the old icon item.

Adding an icon item to a voucher file is not mandatory for it to become a valid voucher, however the voucher will inherit the default icon of a minecraft barrier block. To add an icon item, we include the following line in our voucher file:

# The name of the voucher, this is required for all created vouchers (Not to be confused with the ID, which is the file name)
Name: '&fMy &6&lFirst &fVoucher'

Voucher:
  # The ICON used to represent the voucher
  Item: 'PAPER'

---

Icon Enchanted State

The Enchanted state of the Voucher represents whether the physical item that will be given to a player when they receive the voucher should be enchanted. This is a simple boolean value and thus must be set to true for enchanted, or false for not.

The enchanted state may be changed at any time without any effect on users who have a voucher with the old enchanted state.

Adding an enchanted state to a voucher file is not mandatory for it to become a valid voucher, however the voucher will inherit the default false state for whether it is enchanted. To add an enchanted state, we include the following line in our voucher file:

# The name of the voucher, this is required for all created vouchers (Not to be confused with the ID, which is the file name)
Name: '&fMy &6&lFirst &fVoucher'

Voucher:
  # The ICON used to represent the voucher
  Item: 'PAPER'
  # Whether the ICON should be enchanted
  Enchanted: true

---

Primary Lore

The Primary Lore of the voucher will be the text lore that is included in the physical item that will be given to a player when they receive the voucher. This is a string list value and thus multiple lines of text may be added!

The primary lore may be changed at any time without any effect on users who have a voucher with the old primary lore.

Adding a primary lore to a voucher file is not mandatory for it to become a valid voucher, however the voucher will not have any physical lore present (other than config instructions). To add a primary lore, we include the following line in our voucher file:

# The name of the voucher, this is required for all created vouchers (Not to be confused with the ID, which is the file name)
Name: '&fMy &6&lFirst &fVoucher'

Voucher:
  # The ICON used to represent the voucher
  Item: 'PAPER'
  # Whether the ICON should be enchanted
  Enchanted: true
  # The lore of the voucher icon
  Lore:
    - '&7Test your luck with the My First Voucher!'
    - '&7Prizes Given: 1'
    - '&7Prize List:'
    - '&f1x Dirt'
    - '&f2x Gold'
    - '&b8x Diamonds!'

---

Optional Values

Server Use Limit

The server use limit is a value which determines how many times a voucher may be used server-wide. For example, if set to 5, the voucher may only be used 5 times total throughout the entire server.

To add a Server Use Limit to your voucher, you should include the following line in your voucher config:

ServerLimit: 5

If you decide that you don't need this limit, you can delete the line or set the value to -1.

---

Allow Preview State

The Allow Preview state allows you to determine whether a voucher should be previewable.

For example, if a player has the vouchers.preview permission node, and this is set to true. The user will be able to preview the voucher.

However, if a player has the vouchers.preview permission node, and this is set to false. The user will not be able to preview the voucher.

To add an Allow Preview configuration to your voucher, you should include the following line in your voucher config:

AllowPreview: true

If this line does not exist within the voucher configuration file, the 'Allow Preview' state will automatically assume the value true.