# Hey


# Arcane


# Vouchers

The ultimate vouchers plugin


# v2.0.0

See what's new on v2.0.0

**Jump to:** [<mark style="color:green;">ADDED</mark>](#added), [<mark style="color:blue;">CHANGED</mark>](#changed), [<mark style="color:red;">REMOVED</mark>](#removed)

{% hint style="success" %}

#### ADDED <a href="#added" id="added"></a>

{% endhint %}

### Updater

Since this version brings many changes in terms of configuration, I've made a small program that will convert your files (config.yml, limits.yml and vouchers.yml) to the new format, including strings that use the legacy format (`&`) to [MiniMessage](https://docs.adventure.kyori.net/minimessage).

{% content-ref url="/pages/RrHd2o3vtaP9TexU2nms" %}
[Comet](/resources/arcane/vouchers/comet)
{% endcontent-ref %}

### MiniMessage

Every string and message supports [MiniMessage](https://docs.adventure.kyori.net/minimessage). Legacy strings (including `&` color codes) were deprecated for a long time, and is better to move one to a more modern system. With MiniMessage, you can add everything you want to any message: click events, hover, hex & gradient (<mark style="color:blue;">1.14.4+</mark>).

### Voucher Settings

#### Bind to receiver

Make the voucher usable only by the player who received it

```yaml
bindToReceiver:
  enabled: true
  message: '<red>You can not use this voucher, it belongs to {player}!</red>'
```

#### Cooldown

Put the voucher on a cooldown after each usage (e.g. allow them to use the voucher once a day)

```yaml
cooldown:
  enabled: true
  cooldown: 1d
  message: '<red>You can use this voucher again in {left}</red>'
```

#### Limit for bulk open

Limit how many vouchers can be opened at a time.

```yaml
bulkOpen:
  enabled: true
  limit: 5
```

#### Regex for 'regions' and 'worlds'

Since some servers might have different regions / worlds that follow a format, it is much easier to use a [RegEx ](https://www.w3schools.com/java/java_regex.asp)expression than to list all of them. These options can be combined with normal strings.\
Examples:

* `regex:player_world_.+` - match all worlds that start with `player_world_`
* `regex:mine-\w+` - match all regions that start with `mine-`

```yaml
worlds:
  whitelist:
    list:
    - spawn
    - regex:player_world_.+
    message: '<red>This voucher can only be used at spawn or on a player world.<red>'
```

#### Regions

Allow or disallow players to use vouchers based on the region they are standing on.\
This function require [WorldGuard ](https://dev.bukkit.org/projects/worldguard)6.x.x or 7.x.x.

```yaml
regions:
  whitelist:
    list: [boss-spawn-region]
    #
    # This message will be sent to players that attempt to redee the voucher
    # but they are not standing inside 'boss-spawn-region'
    #
    message: '<red>The boss can not be spawned here!</red>'
```

#### World blacklist

Previously it was only possible to whitelist certain worlds, now you can also blacklist them.

```yaml
worlds:
  blacklist:
    list: [world_nether]
    message: '<red>You can not use the voucher in world {world}</red>'
```

#### Message types

By default, all voucher related messages are sent in chat, but you can specify the type of each of them individually by adding a prefix before the actual message.

* `ACTION_BAR;<message>`&#x20;
* `CHAT;<message>`&#x20;
* `TITLE;<title>[n]<subtitle`

#### Sounds

Play a sound when the voucher is received / redeemed, when it is on cooldown, when the limit was reached, etc. More info can be found [**here**](/resources/arcane/vouchers/configuration/vouchers.yml#soundobject).

### NBT

Go beyond available customization options for voucher items with NBT tags.

{% content-ref url="/pages/VhYH6wyXKPMzC1SemCFW" %}
[vouchers-nbt.txt](/resources/arcane/vouchers/configuration/vouchers-nbt.txt)
{% endcontent-ref %}

### Bulk actions

A separated list of actions used when the player redeem multiple vouchers at once, use `%amount%` for actions to access the amount of vouchers used. If your actions don't fit this system (e.g. you use a command that must be executed n times) leave this list empty and the plugin will execute the `actions` n times (n = amount of vouchers).

```yaml
actions:
  - '[addmoney] 5000'
bulkActions:
  #
  # We multiply 5000 by %amount% to calculate the new amount of money that
  # will be given, depending on how many vouchers the player has redeem
  #
  - '[addmoney] math:{5000 * %amount%}'
```

### More skull texture options

The texture was moved to its own setting, `texture`, and now you can use: player names, [Head Database](https://www.spigotmc.org/resources/head-database.14280/) IDs or texture. Info about how to use each of them can be found [here](/resources/arcane/vouchers/configuration/vouchers.yml#texturestring).

```yaml
texture: BASE64;eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZGNlYjE3MDhkNTQwNGVmMzI2MTAzZTdiNjA1NTljOTE3OGYzZGNlNzI5MDA3YWM5YTBiNDk4YmRlYmU0NjEwNyJ9fX0=
texture: HDB;21899
texture: PLAYER;MHF_Chest
```

### Usages command

Previously, it was impossible to edit or view the usages of a voucher in-game. Now, you can use the `/av usages` command to do so.

* **/av usages \[voucher] check (player)** - Check the usages of a voucher
* **/av usages \[voucher] modify \[value] (player)** - Modify the usages of a voucher
* **/av usages \[voucher] set \[value] (player)** - Set the usages of a voucher

{% content-ref url="/pages/4NsNjrpByECgZNJQU0YK" %}
[Commands](/resources/arcane/vouchers/commands)
{% endcontent-ref %}

### Utils

Find out what [Materials](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html#enum-constant-summary) / [Sounds](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html#enum-constant-summary) / [Enchantments](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html#field-summary) (and many more) are available for your game version without having to check an external source. The files containing this data can be found in `/plugins/ArcaneVouchers/.RESOURCES/`

{% hint style="info" %}

#### CHANGED

{% endhint %}

* `display_name` was renamed to `name`
* Usages are now stored on a [SQLite ](https://www.sqlite.org/index.html)database instead of a simple, YAML file
* `[actionbar]` was replaced by `[message]` with `ACTION_BAR` type ([see](/resources/arcane/vouchers/actions#message))
* `[broadcast]` and `[permissionbroadcast]` were replaced by `[message]` with [broadcast property](/resources/arcane/vouchers/actions/properties#broadcast)
* The volume and pitch for `[sound]` are now [properties](/resources/arcane/vouchers/actions/properties) instead of action arguments
* Skull texture was moved to its own setting called `texture`&#x20;
* The format for arguments was changed from `{args[n]}` to `%args[n]%`&#x20;
* \---

{% hint style="danger" %}

#### REMOVED

{% endhint %}

* `[json]` - [MiniMessage ](https://docs.adventure.kyori.net/minimessage)is a better replacement
* `[centermessage]` and `[centerbroadcast]` - the system used wasn't working if the player had a different chat width so I decided to remove them, the functionality can still be achieved with a plugin like [RawMsg](https://www.spigotmc.org/resources/rawmsg.35864/)


# Example vouchers

Various examples to help new users get started with Arcane Vouchers

### Tag voucher

Unlock access to chat tags with a voucher. The example uses DeluxeTags permissions but it is very easy to modify the voucher to work with another plugin.

```yaml
heart-tag-voucher:
  item:
    material: NAME_TAG
    name: '<red>♥ chat tag'
    lore:
    - '<white>Click to unlock the chat tag!'
  actions:
  - '[permission] ADD deluxetags.tag.heart'
  - '[message] <green>You have unlocked the heart tag! Use /tags to equip it'
  settings:
    permissions:
      blacklist:
        list: [deluxetags.tag.heart]
        message: '<red>Looks lik you already have access to this tag!'
  
```


# Actions

## Format

Starting with v2.0.0 the format for actions was changed to the following `{`[`properties`](#properties)`} [`[`id`](#undefined)`] args`.

### Properties

A set of `key=value` options separated by space. Read more about properties on their own page. 👇

{% content-ref url="/pages/rRiLkaZ9gkPM3BpANYxj" %}
[Properties](/resources/arcane/vouchers/actions/properties)
{% endcontent-ref %}

### ID

Each action has its own unique identifier. The id is also case-insensitive, meaning that `[CONSOLE]` is the same as `[console]`.

#### Default actions

* Commands
  * [\[console\] \<command>](#console)
  * [\[player\] \<command>](#player)
* Economy
  * [\[addexp\] \<amount>(L)](#addexp)
  * [\[item\] \<material>(:damage) \<amount> (args...)](#item)
  * [\[voucher\] \<name> (amount) (args...)](#voucher)
* Message
  * [\[bossbar\] \<message>](#bossbar)
  * [\[chat\] \<message>](#chat)
  * [\[message\] \<message>](#message)
* Other
  * [\[data\] \<key> \<value>](#data)
  * [\[effect\] \<effect> \<duration> (amplifier)](#effect)
  * [\[sound\] \<sound>](#sound)

#### Actions with dependencies

* Crates
  * [\[givecratereloadedkey\] \<crate> (amount)](#givecratereloadedkey)
* [Vault](https://www.spigotmc.org/resources/vault.34315/)
  * [\[addmoney\] \<amount>](#addmoney)
  * [\[permission\] \<ADD/REMOVE> \<permission.node> (world)](#permission)

## Available actions

### Default actions

{% hint style="info" %} <mark style="color:blue;">**Commands**</mark>
{% endhint %}

#### \[console] - execute a command from [console](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/command/ConsoleCommandSender.html) <a href="#console" id="console"></a>

{% tabs %}
{% tab title="Arguments" %}
**\<command>**: String, the command to execute
{% endtab %}

{% tab title="Examples" %}
`[console] kill %player_name` - make the console run `/kill <name>`
{% endtab %}
{% endtabs %}

#### \[player] - execute a command as the player that is using the voucher <a href="#player" id="player"></a>

{% tabs %}
{% tab title="Arguments" %}
**\<command>**: String, the command to execute (the slash is not required, unless the command has two or more)
{% endtab %}

{% tab title="Examples" %}
`[player] kit Daily` - make the player run `/kit Daily`
{% endtab %}
{% endtabs %}

{% hint style="info" %} <mark style="color:blue;">**Economy**</mark>
{% endhint %}

#### \[addexp] - give to the player an amount of EXP <a href="#addexp" id="addexp"></a>

{% tabs %}
{% tab title="Arguments" %}
**\<amount>(L):** Integer, amount of exp to add. By appending an `L` after, levels of exp will be given instead of points
{% endtab %}

{% tab title="Examples" %}
`[addexp] 100` - give 100 EXP points to the player

`[addexp] 100L` - give 100 levels of EXP to the player
{% endtab %}
{% endtabs %}

#### \[item] - give to the player a custom item <a href="#item" id="item"></a>

A format similar to EssentialsX's is used.

{% tabs %}
{% tab title="Arguments" %}
**Required**

* **material(:damage)**: String, name of a [Material](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html#enum-constant-summary). To specify its damage, add `:damage` after (`INK_SACK:4` for lapiz lazuli on < 1.13)
* **amount**: Integer, the amount of the item

\
**Optional**

* **name:** String, the name of the item, use `_` for space
* **lore**: String, the lore of the item, use `_` for space and `|` for a new line
* **color**: [ColorString](/resources/arcane/vouchers/configuration/vouchers.yml#colorstring), the color of the item, used for leather armor
* **flags:** List, a comma separated list of [ItemFlag](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html#enum-constant-summary) names
* **unbreakable:** make the item unbreakable, this argument doesn't require a value
* **model**: Integer, the custom model data of this item (1.14.4+)
* **nbt:** String, a JSON string representing item's NBT, some escaping should be done, mostly for quotes. This argument must be the last one since it takes everything that's after `nbt:` as value

For enchantments simply use `Enchantment:level`\
For `name` and `lore` , if you want to use `_` and `|` you will have to escape them by adding a `\` before.
{% endtab %}

{% tab title="Examples" %}
`[item] LEATHER_CHESTPLATE 1 lore:<red>What's</red>_<blue>up?</blue>` - a leather chestplate with a lore saying <mark style="color:red;">What's</mark> <mark style="color:blue;">up?</mark>
{% endtab %}
{% endtabs %}

#### \[voucher] - give vouchers to the player <a href="#voucher" id="voucher"></a>

{% tabs %}
{% tab title="Arguments" %}
**Required**

* **name**: String, the name of a voucher

**Optional**

* **amount**: Integer, the amount of vouchers to give (default: 1)
* **args**: String, similar to the [give command](/resources/arcane/vouchers/commands#give)
  {% endtab %}

{% tab title="Examples" %}
`[voucher] MoneyPouch 1` - one 'MoneyPouch' voucher

`[voucher] Rank 1 VIP 7d` - one 'Rank' voucher
{% endtab %}
{% endtabs %}

{% hint style="info" %} <mark style="color:blue;">**Message**</mark>
{% endhint %}

#### \[bossbar] - display a boss bar on player's screen <a href="#bossbar" id="bossbar"></a>

{% tabs %}
{% tab title="Arguments" %}
**message**: String, the message that will be displayed
{% endtab %}

{% tab title="Properties" %}
**color**: String, the name of a [Color](https://jd.adventure.kyori.net/api/4.9.3/net/kyori/adventure/bossbar/BossBar.Color.html#enum.constant.summary) (default: [WHITE](https://jd.adventure.kyori.net/api/4.9.3/net/kyori/adventure/bossbar/BossBar.Color.html#WHITE))

**duration**: Ticks, how long the bar will be displayed (default: 200 or 10 seconds)

**flags**: List, comma separated list of [Flag](https://jd.adventure.kyori.net/api/4.9.3/net/kyori/adventure/bossbar/BossBar.Flag.html#enum.constant.summary) names (default: empty)

**overlay**: String, the name of an [Overlay ](https://jd.adventure.kyori.net/api/4.9.3/net/kyori/adventure/bossbar/BossBar.Overlay.html#enum.constant.summary)(default: [PROGRESS](https://jd.adventure.kyori.net/api/4.9.3/net/kyori/adventure/bossbar/BossBar.Overlay.html#PROGRESS))

**progress**: Float, the progress of the bar (default: [MAX\_PROGRESS](https://jd.adventure.kyori.net/api/4.9.3/constant-values.html#net.kyori.adventure.bossbar.BossBar.MAX_PROGRESS))
{% endtab %}

{% tab title="Examples" %}
`{color=BLUE progress=0.5 display=200} [bossbar] <green>Hey</green>` - a blue bar that will stay on the screen for 10 seconds, with 50% progress and a green text saying <mark style="color:green;">Hey</mark>
{% endtab %}
{% endtabs %}

#### \[chat] - make the player send a message in chat <a href="#chat" id="chat"></a>

{% tabs %}
{% tab title="Arguments" %}
**message**: String, the message that will be sent
{% endtab %}

{% tab title="Examples" %}
`[chat] <yellow>Hello everyone, my name is %player_name%!<yellow>` - a yellow message saying <mark style="color:yellow;">Hello everyone, my name is \<name>!</mark>
{% endtab %}
{% endtabs %}

#### \[message] - send a message to the player <a href="#message" id="message"></a>

{% tabs %}
{% tab title="Arguments" %}
**message**: String, the message that will be sent.
{% endtab %}

{% tab title="Properties" %}
**broadcast:** see [Properties/Broadcast](/resources/arcane/vouchers/actions/properties#broadcast) (default: none)

**type**: String, the type of the message (ACTION\_BAR, CHAT, TITLE) (default: `CHAT`).\
\
**Properties for** `TITLE`:

* **fadeIn:** Ticks, the time the title will fade-in (default: 10 or 0.5 seconds)
* **fadeOut:** Ticks, the time the title will fade-out (default: 20 or 1 second)
* **stay**: Ticks, the time the title will stay (default: 70 or 3.5 seconds)

For `TITLE`, use `[n]` to separate the title from subtitle (`This is the title[n]And this is the subtitle`)
{% endtab %}

{% tab title="Examples" %}
`{type=TITLE stay=100] [message] <blue>You have won</blue>[n]<dark_green>$</dark_green><green>50,000</green>`- a title that will stay on the screen for 5 seconds saying `You have won` `$50,000`

`[message] <red>Hey %player_name%, how are you?<red>` - a red chat message saying <mark style="color:red;">Hey \<name>, how are you?</mark>
{% endtab %}
{% endtabs %}

{% hint style="info" %} <mark style="color:blue;">**Other**</mark>
{% endhint %}

#### \[data] - store a value that can be reused on the next actions <a href="#data" id="data"></a>

{% tabs %}
{% tab title="Arguments" %}
**key**: String, the key of the value, must not contain spaces

**value**: Anything, the value
{% endtab %}

{% tab title="Examples" %}
`[data] %random% randomL:{100,200}`\
`[addmoney] %random%`\
`[message] You have received $%amount%`\
Generate a random number and use it to give money and inform the player how much they got.
{% endtab %}
{% endtabs %}

#### \[effect] - give a potion effect to the player <a href="#effect" id="effect"></a>

{% tabs %}
{% tab title="Arguments" %}
**Required**:

* **effect**: String, the name of a [PotionEffectType](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/potion/PotionEffectType.html#field-summary)
* **duration**: Ticks, the duration of the effect

**Optional**:

* **amplifier:** Integer, the amplifier of the effect (default: 1)
  {% endtab %}

{% tab title="Properties" %}
**Universal**: (available on all game versions)

* **ambient:** Boolean, makes potion effect produce more, translucent, particles (default: `true`)
* **particles**: Boolean, whether the effect has particles (default: `true`)

**1.9 - 1.12.2**:

* **color**: [ColorString](/resources/arcane/vouchers/configuration/vouchers.yml#colorstring), the color of the particles (default: none)

**1.13+**:

* **icon**: Boolean, whether the icon of the effect will be displayed (default: `true`)
  {% endtab %}

{% tab title="Examples" %}
`{particles=false} [effect] SPEED 200 1` - Speed II for 10s with no particles
{% endtab %}
{% endtabs %}

#### \[sound] - play a sound to the player <a href="#sound" id="sound"></a>

{% tabs %}
{% tab title="Arguments" %}
**sound**: NamespacedKey, the key of the sound
{% endtab %}

{% tab title="Properties" %}
**broadcast**: see [Properties/Broadcast](/resources/arcane/vouchers/actions/properties#broadcast) (default: none)

**pitch**: Float, the pitch of the sound (default: `0`)

**source**: String, the name of a [Source](https://jd.adventure.kyori.net/api/4.9.3/net/kyori/adventure/sound/Sound.Source.html#enum.constant.summary) (default: [MASTER](https://jd.adventure.kyori.net/api/4.9.3/net/kyori/adventure/sound/Sound.Source.html#MASTER))

**volume**: Float, the volume of the sound (default: `0`)
{% endtab %}

{% tab title="Examples" %}
`{source=AMBIENT} [sound] minecraft:ambient.cave` - play the sound from `AMBIENT` source

`[sound] custom:sound_name` - play a custom sound
{% endtab %}
{% endtabs %}

### Actions with dependencies

{% hint style="info" %} <mark style="color:blue;">**Vault**</mark>
{% endhint %}

#### \[addmoney] - add money to player's balance <a href="#addmoney" id="addmoney"></a>

<mark style="color:green;">An economy plugin is required to use this action.</mark>

{% tabs %}
{% tab title="Arguments" %}
**amount**: Double, the amount of money to give
{% endtab %}

{% tab title="Examples" %}
`[addmoney] 125.50`
{% endtab %}
{% endtabs %}

#### \[permission] add or remove a permission to the player <a href="#permission" id="permission"></a>

<mark style="color:green;">A permissions plugin is required to use this action.</mark>

{% tabs %}
{% tab title="Arguments" %}
**Required**:

* **action:** String, the name of the action to perform, `ADD` or `REMOVE`
* **permission**: String, the permission node

**Optional**:

* **world**: String, the name of the world where the permission will be added / removed (default: player's world)
  {% endtab %}

{% tab title="Examples" %}
`[permission] ADD some.permission world_nether` - add the permission only on world\_nether

`[permission] REMOVE some.permission` - remove the permission global
{% endtab %}
{% endtabs %}


# Properties

{% hint style="info" %}

## Generic properties

{% endhint %}

These properties are available for all actions.

### Chance

The chance out of 100 for this action to be executed (supports decimals)\
Format: `chance=<chance>` (e.g. `chance=25` for 25%)

### Delay

Delay an action by n ticks\
Format: `delay=<delay>` (e.g. `delay=20` for 1s)

### Permission

Execute the action depending on player's permission.\
Format: `permission=<PermissionMode>:<permission>`

* **PermissionMode:**
  * ADD: The action will be executed only if the player doesn't have this permission and will be added after the first execution
  * ADD\_TEMP: The permission is added, the the action is executed and then the permission is removed
  * NO\_PERMISSION: The action will be executed only if the player doesn't have this permission
  * REQUIRE: The action will be executed only if the player has this permission
  * REMOVE: Same as REQUIRE but the permission is removed after the first execution
* **\<permission>**: String, a permission node

{% hint style="info" %}

## Specific properties

{% endhint %}

These properties are available only for certain actions.

### Broadcast

Broadcast the action to certain players.\
Actions: [\[bossbar\]](/resources/arcane/vouchers/actions#bossbar), [\[message\]](/resources/arcane/vouchers/actions#message), [\[sound\]](/resources/arcane/vouchers/actions#sound)\
**Format:** `broadcast=<condition>:(value),<condition>:(value)...` or `broadcast=*` to broadcast to all players with no exceptions

* `permission:<permission>`: Broadcast to players with a certain permission
* `radius:<radius>`: Broadcast to players within a radius (supports decimals)
* `world`: Broadcast to players from player's world world

Example:

* `broadcast=permission:example.permission,world`&#x20;
* `broadcast=permission:some.permission,radius:50`


# Tags

Built-in placeholders for generating random elements or evaluate math equations

### Chance <a href="#chance" id="chance"></a>

Get an element from a list using a chance system (0 to 100, supporting decimals).\
Format: `chance:{(chance)=(item),(chance)=(item),default=(default item)}`\
\
Placeholders can be used for `chance` and using the `default` keyword instead of a chance, you can specify a default value for when the player is unlucky. If no default value is specified, nothing \
will be returned.\
\
Examples:

* `chance:{85=STONE 65,10=COAL 64,5=DIAMOND 4,default=DIRT 1}` - 85% for `STONE 64`, 10% for `COAL 64`, 5% for `DIAMOND 4` and the default value `DIRT 1`

### Math

Powered by [EvalEx](https://github.com/uklimaschewski/EvalEx), the math tag allows to evaluate math equations to get the result.\
Format: `math:{(scale),<equation>}` or `math:{<equation>}`\
Examples:

* `math:{3,10 / 3}` = 3.000
* `math:{10 / 3}` = 3

### Random Double

Generate a random [Double ](https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html)between a min (inclusive) and max (inclusive) value.\
Format: `random:{(precision),<min>,<max>}` or `math:{<min>,<max>`\
Examples:

* `random:{0,100}` = 5.215616126 (without `precision` all decimals are returned)
* `random:{3,0-100}` = 5.231

### Random Element

Pick a random element from a comma separated list\
Format: `randomE:{E1,E2,E3...,En}`\
Examples:

* `randomE:{Epic,Rare,Common}` - pick a random String
* `randomE:{112,1948,9684,132}` - pick a random number
* `randomE:{Text,14918,AnotherText,1515}` - the elements can be anything

### Random Long

Generate a random Long between a min (inclusive) and max (inclusive) value.\
Format: randomL:{\<min>,\<max>}\
Examples:

* `randomL:{0,12345678901234567}`


# Comet

Automatic updater to v2.0.0

### Usage

1. Download the latest Comet jar and a start file (`.bat` for Windows or `.sh` for Linux/MacOS) from [here](https://ci.codemc.io/job/iGabyTM/job/ArcaneVouchers/)
2. Place the files in a folder with the files you want to update (`config.yml`, `vouchers.yml` and `limits.yml`) or to convert
3. Open the start file and add the following flags at the end of the command, depending on what you want to do:
   1. To update: `--action update`
   2. To convert: `--action convert --plugin <plugin>`
4. Save the file and execute it (double-click on Windows/MacOs or `./start.sh` on Linux)

#### Notes for conversion

For [Vouchers by BadBones](https://www.spigotmc.org/resources/vouchers.13654/), add `Config.yml`

For [EpicVouchers by Songoda](https://songoda.com/marketplace/product/epicvouchers-advanced-vouchers-by-gui.25), rename its `vouchers.yml` file to `EpicVouchers.yml`

### Flags

`-h, --help` Display the help menu\
`-a,--action <action>` Available actions: convert, update\
`-p,--plugin <plugin>` Available plugins for conversion: [badbones](https://www.spigotmc.org/resources/vouchers.13654/), [songoda](https://songoda.com/marketplace/product/epicvouchers-advanced-vouchers-by-gui.25)


# Commands

To access any admin command, you need [this ](/resources/arcane/vouchers/permissions#admin-commands)permission.

### Give

Syntax: **/av give \[player/\*] \[voucher] (amount) (arguments...)**\
To give vouchers to all online players, use `*` instead of a player name.\
\
Anything that's after `amount` can be accessed using `%args%` / `%args[INDEX]%` from messages or voucher item / name. By default, arguments are separated by space, but if you need multiple words for one argument, surround them with quotes (`"`).\
\
Example:\
Input: `FirstArgument "Second Argument" ThirdArgument` \
Output: `%args[1]%` - `FirstArgument`, `%args[2]%` - `Second Argument`, `%args[3]%` - `ThirdArgument`<br>

### Help

Syntax: **/av help**

### List

Syntax: **/av list**

### Reload

Syntax: **/av reload**

### Usages

Syntax: **/av usages \[voucher] \[action] (arguments...)**

#### **Actions**

* **check** - See how many times a voucher was used, requires a player name if the limit type of that voucher is PERSONAL
* **modify** -&#x20;


# Configuration


# config.yml

Configuration for v2.0.0

{% code title="config.yml" %}

```yaml
settings:
  disable:
    #
    # If 'true', people won't be able to craft items using vouchers
    #
    crafting: true
  command: arcanevouchers
  alias:
    - av
  #
  # Any cooldown lower than the threshold won't be saved to database
  # Set it to 0 to save all cooldowns. The value supports formatting with letters:
  # h - hours
  # m - minutes
  # s - seconds
  #
  cooldownSaveThreshold: 1m

confirmationGui:
  size: 3 # The number of rows, min 1 and max 6
  title: 'Confirmation GUI' # The title
  #
  # All items listed below accept the same configuration
  # options as the vouchers (see vouchers.yml)
  #
  items:
    #
    # The buttons must be here, otherwise the GUI won't work
    #
    buttons:
      confirmation:
        material: EMERALD_BLOCK
        slot: 12
        name: '<green><b>YES</b></green>'
      cancel:
        material: REDSTONE_BLOCK
        slot: 14
        display_name: '<red><b>NO</b><red>'
    #
    # Items listed here are only used for design
    #
    other: {}
```

{% endcode %}


# vouchers.yml

Vouchers configuration for v2.0.0

## <mark style="color:red;">Format</mark>

Below you will find a detailed structure of a voucher, with all the available options and what values they require. Please see to the [Resources ](#resources)section to learn more about each type of value.

<pre class="language-yaml" data-title="vouchers.yml" data-full-width="true"><code class="lang-yaml">vouchers:
  voucherId:
    item:
      #
      # REQUIRED VALUES
      #
      # The name of a material https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html
      material: String # default: PAPER
      #
      # OPTIONAL VALUES
      #
      lore: List of String # default: empty
      name: String # default: empty
      damage: Short # default: 0
      glow: Boolean # default: false
      customModelData: Integer # default: 0 | 1.14.4+
      texture: TextureString # default: none
      color: ColorString # default: none | Available only for leather armor
      enchantments: List of EnchantmentString # default: empty
      flags: List of ItemFlag # default: empty
      unbreakable: Boolean # default: false
      banner:
        patterns: List of BannerPatternString # default: empty
    actions: List of Action # default: empty
    #
    # A list of actions that are executed when multiple vouchers are used.
    # Leave this empty to execute 'actions' n times (n = vouchers redeemed)
    #
    bulkActions: List of Action # default: empty
    #
    # Starting with v2.0.0, all settings are optional
    #
    settings:
      #
      # Messages sent when the voucher is received and redeemed
      #
      messages:
        #
        # {amount} - how many vouchers were received
        #
        receive: Message # default: none
        #
        # {amount} - how many vouchers were redeemed
        #
        redeem: Message # default: none
      #
      # Sounds played when the voucher is received or redeemed
      #
      sounds:
        receive: SoundObject # default: none
        redeem: SoundObject # default: none
      #
      # Make the voucher usable only by the player who received it
      #
      bindToReceiver:
        enabled: Boolean # default: false
        #
        # {player} - the name of the player who can redeem the voucher
        #
        message: Message # default: none
        sound: SoundObject # default: none
      #
      # Whether multiple vouchers can be redeem at one time
      #
      bulkOpen:
        enabled: Boolean # default: false
        limit: Integer # default: MAX
      #
      # Whether the player has to confirm the redeem through a GUI
      #
      confirmation:
        enabled: Boolean # default: false
      #
      # Put the voucher on a cooldown after each usage
      #
      cooldown:
        enabled: Boolean # default: false
        cooldown: TimeString # default: none
        #
        # {left} - the time left
        #
        message: Message # default: none
        sound: SoundObject # default: none
      #
      # Limit how many times a voucher can be used by a player or global
      #
      limit:
        enabled: Boolean # default: false
        type: LimitType # default: NONE
        limit: Long # default: <a data-footnote-ref href="#user-content-fn-1">max value</a>
        message: Message # default: none
        sound: SoundObject # default: none
      #
      # Allow or disallow players to use this voucher based on their permissions
      #
      permissions:
        #
        # Players with one of thes permissions can't use this voucher
        #
        blacklist:
          list: List of Option # default: empty
          message: Message # default: none
          sound: SoundObject # default: none
        #
        # Only players with one of these permissions can use this voucher
        #
        whitelist:
          list: List of Option # default: empty
          message: Message # default: none
          sound: SoundObject # default: none
      #
      # REQUIRE WORLDGUARD 6.X.X or 7.X.X https://dev.bukkit.org/projects/worldguard
      # Allow or disallow players to use this voucher based on the region they
      # are standing on
      #
      regions:
        #
        # Players that are in any of these regions can't use this voucher
        #
        blacklist:
          list: List of Option # default: empty
          message: Message # default: none
          sound: SoundObject # default: none
        #
        # Only players that are in any of these regions can use this voucher
        #
        whitelist:
          list: List of Option # default: empty
          message: Message # default: none
          sound: SoundObject # default: none
      #
      # Allow or disallow players to use this voucher based on their world
      #
      worlds:
        #
        # Players that are in any of these worlds can't use this voucher
        #
        blacklist:
          list: List of Option # default: empty
          message: Message # default: none
          sound: SoundObject # default: none
        #
        # Only players that are in any of these worlds can use this voucher
        #
        whitelist:
          list: List of Option # default: empty
          message: Message # default: none
          sound: SoundObject # default: none
</code></pre>

## <mark style="color:red;">Resources</mark>

* Java (8)
  * [Boolean](https://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html) - true or false
  * [Short](https://docs.oracle.com/javase/8/docs/api/java/lang/Short.html) - whole numbers without decimal points with values between -32,768 and +32,767
  * [Integer](https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html) - similar to Short, but the range is between -2.1 billions and + 2.1 billions
  * [Long](https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html) - similar to Short and Integer but the limits are much larger (\~9 quintillions)
  * [Float ](https://docs.oracle.com/javase/8/docs/api/java/lang/Float.html)- numbers with decimal points, with values between 0.0 and 1.0 in Minecraft
  * [String](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html) - the name Java uses for text, nothing special about this one
  * List<**Type**> - a list that expects elements of the said type, for example `lore: List<String>` expects a list of texts (Strings) that will be set as lore
* [MiniMessage](https://docs.adventure.kyori.net/minimessage)
* [RegEx](https://www.w3schools.com/java/java_regex.asp) - regular expression
* Spigot (latest)
  * [Color](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Color.html#field-summary)
  * [DyeColor](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/DyeColor.html#enum-constant-summary)
  * [Enchantment](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html#field-summary)
  * [ItemFlag](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html#enum-constant-summary)
  * [Material](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html#enum-constant-summary)
  * [PatternType](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/block/banner/PatternType.html#enum-constant-summary) - different patterns a Banner can have

#### <mark style="color:green;">ColorString</mark>

Format: `<red>,<green>,<blue>` (e.g. `255,000,000`), `RRGGBB` (e.g. `FF0000` [HEX](https://htmlcolorcodes.com/color-picker/)) or the name of a [Color](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Color.html#field-summary) (e.g. `RED`)

Example:

<pre class="language-yaml" data-overflow="wrap"><code class="lang-yaml"># A leather chestplate colored orange
item:
<strong>    material: LEATHER_CHESTPLATE
</strong>    # Spigot default color
    color: ORANGE
    # HEX format
    color: FFA500
    # R,G,B format
    color: 255,165,0
</code></pre>

#### <mark style="color:green;">**EnchantmentString**</mark>

Format: `Enchantment;<level>`

* **Enchantment**: String, the name of an [Enchantment](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html#field-summary) (e.g. `MENDING`), for 1.13+ could also use the `namespace:key` format (e.g. `minecraft:sharpness`)
* **\<level>**: Integer, the level of the enchantment

Example:

{% code overflow="wrap" fullWidth="false" %}

```yaml
# A diamond sword with mending and sharpness 3
item:
  material: DIAMOND_SWORD
  enchantments:
  - MENDING;1
  # The name spigot uses for sharpness
  - DAMAGE_ALL;3
  # Alternative for the previous option available for 1.13+ servers
  - minecraft:sharpness;3
```

{% endcode %}

#### <mark style="color:green;">LimitType</mark>

Values: GLOBAL, PERSONAL, NONE (default, if disabled)

#### <mark style="color:green;">Message</mark>

Format: `Type;<message>` or `<message>` and CHAT will be the default `Type`

* **Type**: ACTION\_BAR, CHAT, TITLE
* **\<message>**: String, the actual message that will be sent, use `[n]` for TITLE to separate the title from subtitle

Examples:

<pre class="language-yaml" data-overflow="wrap"><code class="lang-yaml"><strong>settings:
</strong>  messages:
    # Simple chat message
    redeem: You have received a voucher
    redeem: CHAT;You have received a voucher
    # Action bar message
    redeem: ACTION_BAR;You have received a voucher
    # Title message
    # 'You have received' will be the title and 'a voucher' the subtitle
    redeem: TITLE;You have received[n]a voucher
</code></pre>

#### <mark style="color:green;">Option</mark>

Format: `regex:<expression>` for [RegEx ](https://www.w3schools.com/java/java_regex.asp)or just a normal String

Examples: Allow the voucher to be used at `spawn` or on a "player world", same thing applies for regions.

{% code overflow="wrap" %}

```yaml
# Allow the voucher to be used at spawn or on a "player world"
# same format and logic applies for regions.
worlds:
  whitelist:
    list:
      # When using normal Strings, you can also use %args% but your
      # String must be 1:1 with the world name (e.g. 'Spawn' is not
      # the same as 'spawn')
      - spawn
      # This will match all worlds that start with 'player_world-'
      - regex:player_world-.+
```

{% endcode %}

#### <mark style="color:green;">BannerPatternString</mark>

Format: `PatternType;DyeColor`

* **PatternType**: String, the name of a [PatternType](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/block/banner/PatternType.html#enum-constant-summary) (e.g. `CREEPER`)
* **DyeColor**: String, the name of a [DyeColor](#format) (e.g. `RED`)

Example

```yaml
# A banner with a black gradient and red border
item: WHITE_BANNER
banner:
  patterns:
    - GRADIENT;BLACK
    - BORDER;RED
```

<figure><img src="https://2131565496-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M2tMwfdmbkIiQujWQbO%2Fuploads%2FPguSCmbaHMNmbDdOtZ7l%2Fimage.png?alt=media&amp;token=89105e76-94aa-47d2-8250-036754d4af84" alt=""><figcaption></figcaption></figure>

#### <mark style="color:green;">SoundObject</mark>

Format:

```yaml
<section-name>:
  sound: (1) # Required
  source: (2) # Optional | default: MASTER
  volume: (3) # Optional | default: 1.0
  pitch: (4) # Optional | default: 1.0
```

1. **sound**: String, the name of a sound ('[namespace:path](https://minecraft.fandom.com/wiki/Resource_location)' or just 'path' for vanilla sounds from the 'minecraft' namespace), example: `minecraft:block.note_block.pling` or simply `block.note_block.pling`
2. **source**: String, the name of a sound [Source](https://jd.adventure.kyori.net/api/4.11.0/net/kyori/adventure/sound/Sound.Source.html#enum.constant.summary), example: `MASTER`
3. **volume**: Float, the volume of the sound, example: `0.25`
4. **pitch**: Float, the pitch of the sound, example: `1.50`

Example:

```yaml
sounds:
  redeem:
    sound: 'minecraft:block.note_block.pling'
    volume: 0.75
    pitch: 1.0 # Which is also the default value
```

#### <mark style="color:green;">TextureString</mark>

Format: `Type;<value>` or `<value>` and BASE64 will be the default `Type`

* **Type**: BASE64, HDB, PLAYER
* **\<value>**:
  * BASE64: String, texture value (e.g. `BASE64;eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZGNlYjE3MDhkNTQwNGVmMzI2MTAzZTdiNjA1NTljOTE3OGYzZGNlNzI5MDA3YWM5YTBiNDk4YmRlYmU0NjEwNyJ9fX0=`)
  * HDB: Integer, the id of a head from [HeadDatabase](https://www.spigotmc.org/resources/head-database.14280/) (e.g. `HDB;21899`)
  * PLAYER: String, the name of a player (e.g. `PLAYER;MHF_Chest`)

[^1]: Which is about 9 quintillion


# vouchers-nbt.txt

From here you can add custom NBT tags to vouchers

## Format

{% code title="vouchers-nbt.txt" %}

```
voucher-id {SNBT here}
```

{% endcode %}

[SNBT](https://minecraft.fandom.com/wiki/NBT_format#SNBT_format) or stringified NBT is the format used by Minecraft for stuff like `/give` commands for NBT. It is very easy to use, you can copy the SNBT from a `/give` command and paste it in the file.

## Examples

A colored leather item\
`/give NAME minecraft:leather_chestplate{display:{color:14574937}} 1`&#x20;

```
voucher-id {display:{color:14574937}}
```

## Resources

* [/give command generator](https://www.gamergeeks.net/apps/minecraft/give-command-generator)


# Permissions

List of permissions used across the plugin

### Admin commands

To access all admin commands: `arcanevouchers.admin`.

### Cooldowns

To bypass all cooldowns: `arcanevouchers.cooldownbypass` \
To bypass the cooldown of a specific voucher: `arcanevouchers.cooldownbypass.VOUCHER`, where VOUCHER is the name of the voucher (case insensitive).

### Limits

To bypass all limits: `arcanevouchers.limitbypass`\
To bypass all global limits: `arcanevouchers.limitbypass.*.global`\
To bypass all personal limits: `arcanevouchers.limitbypass.*.personal`\
To bypass the global limit of a specific voucher: `arcanevouchers.limitbypass.VOUCHER.global`\
To bypass the personal limit of a specific voucher: `arcanevouchers.limitbypass.VOUCHER.personal`


# Requirements

## General format

```yaml
settings:
  requirements:
    list:
      minimumRequirements: Integer # the minimum amount of requirements a player must pass (default: -1, all) (OPTIONAL)
      'unique requirement name':
        # use !<type> to negate a requirement, for example '!string equals'
        type: String # the name of a valid requirement (see 'Types' below) (REQUIRED)
        optiona: Boolean # whether a requirement is optional (default: false) (OPTIONAL)
        failActions: List<Action> # actions executed if the requirement fails (OPTIONAL)
```

## Types

* [Location](#location)
* [Numbers](#numbers)
* [Strings](#strings)

## Location

Requirements for player's current location\
**Variables**: [Location](#variable-types-location)

### Distance <a href="#location-distance" id="location-distance"></a>

Check if the distance between player's location and a specific location is ≤ than `n`

#### Format <a href="#location-distance-format" id="location-distance-format"></a>

```yaml
type: 'distance'
location: Location # or placeholder that returns one (see 'Variable Types')
distance: Number   # or placeholder that returns a number
```

```yaml
# The player must be close to world 25/100/200 (X/Y/Z)
type: 'distance'
location: world;25;100;200
distance: 10
```

## Numbers

Compare two numbers using math operations. The requirement uses [Doubles](https://docs.oracle.com/javase/9/docs/api/java/lang/Double.html), meaning decimals are supported.

### Format <a href="#numbers-format" id="numbers-format"></a>

```yaml
type: operation # See below
left: number    # or placeholder that returns a number
right: number   # or placeholder that returns a number
```

### Equal (==) <a href="#numbers-equal" id="numbers-equal"></a>

Check if the numbers are equal

```yaml
type: '=='
left: 10
right: 15
# Result: false, 10 and 15 are not equal
```

### Greater (>) <a href="#numbers-greater" id="numbers-greater"></a>

Check if `left` is greater than `right`

```yaml
type: '>'
left: 10
right: 15
# Result: false, 10 is not greater than 15
```

### Greater or equal (>=) <a href="#numbers-great_or_equal" id="numbers-great_or_equal"></a>

Check if `left` is greater or equal to `right`

```yaml
type: '>='
left: 20
right: 15
# Result: true, 20 is greater or equal to 15
```

### Smaller (<) <a href="#numbers-smaller" id="numbers-smaller"></a>

Check if `left` is smaller than `right`

```yaml
type: '<'
left: 10
right: 15
# Result: true, 10 is smaller than 15
```

### Smaller or equal (<=) <a href="#numbers-smaller_or_equal" id="numbers-smaller_or_equal"></a>

Check if `left` is smaller or equal to `right`

```yaml
type: '<='
left: 20
right: 15
# Result: false, 20 is not greater or equal to 15
```

## Strings <a href="#strings" id="strings"></a>

Compare two strings

### Format <a href="#strings-format" id="strings-format"></a>

```yaml
type: operation # See below
left: string    # or placeholder that returns a string
right: string   # or placeholder that returns a string
```

### Equals (string equals) <a href="#strings-equals" id="strings-equals"></a>

Check if `left` is equal to `right` - **case sensitive**

```
type: string equals
left: Steve
right: steve
# Result: false, 'Steve' is not the same as 'steve'
```

### Equals ignore case (string equals ignore case) <a href="#strings-equals_ignore_case" id="strings-equals_ignore_case"></a>

Check if `left` is equal to `right` - **case insensitive**

```yaml
type: string equals ignore case
left: Steve
right: steve
# Result: true, 'Steve' is equal to 'steve'
```

### Contains (string contains) <a href="#strings-contains" id="strings-contains"></a>

Check if `left` contains `right` - **case sensitive**

```yaml
type: string contains
left: ArcaneVouchers
right: vouchers
# Result: false, 'ArcaneVouchers' does not contain 'vouchers'
```

### Contains ignore case (string contains ignore case)

Check if `left` contains `right` - **case insensitive**

```yaml
type: string contains ignore case
left: ArcaneVouchers
right: vouchers
# Result: true, 'ArcaneVouchers' contains 'vouchers'
```

## Variable types

### Location <a href="#variable-types-location" id="variable-types-location"></a>

**Format**: `world;x;y;z`\
**Example**: `world_the_end;25;100;30` - The End at 25/100/30

## Examples

> Check if the player has ≤ 10 HP

```yaml
# %player_health% ≤ 10
left: '%player_health%'
type: '<='
right: 10
failActions:
  - '[message] <red>You can not use this item at full HP'
```

> Check if the player is the owner of the WorldGuard region he's standing in

```yaml
left: '%worldguard_region_owner%'
type: string equals
right: '%player_name%'
failActions:
  - '[message] <red>You can use this item only in your own protection'
```


# Master


# TokenEnchant


# TEUpgrades


# Other


# GUIHelper