# Voucher Configuration

### Basic settings

For example, in first installation, this is one example in the default configuration:

```yaml
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'"
  physical-id: true
```

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 out[#custom-item](#custom-item "mention")&#x20;

### Rewards

`rewards` is a list of rewards the voucher will give to the player.&#x20;

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](main-configuration "mention"))

Read how to configure reward here: [reward](voucher-configuration/reward "mention")

### 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](https://ezylang.github.io/EvalEx/references/operators.html)\
Supported functions: [https://ezylang.github.io/EvalEx/references/functions.html](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.

To **disable** condition, **either**:

* Remove the `condition` setting
* Write an always-true condition such as `1 == 1`

### Usage limit

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

```yaml
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.

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

To **disable** usage limit, remove the `usage-limit` setting.

### Cooldown

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

```yaml
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`

To **disable** usage limit, remove the `cooldown` setting.

### Double-check

A functionality that requires players to confirm before redeeming a voucher

```yaml
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 still having that identifier cannot be used.&#x20;

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

```yaml
physical-id: true # default is false
```

### Use message

You can define global (default) use message in `messages.yml` (see: [message-configuration](message-configuration "mention"))

If a voucher has use-message defined, it would be picked over the default one.

Similar to global use message, PlaceholderAPI is supported.

```yaml
use-message:
- ""
- "&eYou have used x{bulk-size} {voucher-name}"
- ""

# Empty use message
use-message: []
```

### Full configuration example

Here is an example with all settings defined

```yaml
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
  use-message: []
```

* RGB text generator: [https://www.birdflop.com/resources/rgb/](https://www.birdflop.com/resources/rgb/)
