# Voucher Configuration ### Basic settings For example, in first installation, this is one example in the default configuration: ```yaml exclusive-armor: icon: ender_chest name: "򢰪Exclusive 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") ### 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](https://anhcraft.gitbook.io/vouchers/configuration/main-configuration "mention")) Read how to configure reward here: [reward](https://anhcraft.gitbook.io/vouchers/configuration/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: \ Supported functions: **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. 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](https://anhcraft.gitbook.io/vouchers/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: --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://anhcraft.gitbook.io/vouchers/configuration/voucher-configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.