# 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.md)
{% 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.md#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.md#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.md#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.md#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.md#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 %}


---

# 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://wiki.gabytm.me/resources/arcane/vouchers/actions.md?ask=<question>
```

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.