# Actions System

### Overview

The Actions System allows for dynamic and interactive features to be added to **armor attributes** and **armor items** section within the plugin. Each action provides unique functionality, enhancing gameplay through various effects, commands, and custom interactions. These actions are executed based on triggers, providing players with rewards, visual effects, sounds, and more.

This system is designed to support placeholders for dynamic values and includes a **Requirement Check** feature to ensure specific conditions are met before an action is performed. Below are the available actions and their respective examples for implementation.

{% hint style="success" %}
The **Actions** below are currently functional and useable.
{% endhint %}

{% hint style="warning" %}
Please view each action and check if it's compatible, as some do not work on versions above 1.20.5+
{% endhint %}

{% tabs %}
{% tab title="Reward-Type" %}
The **Reward-Type** action allows you to make items that can affect the armors experience or levels.

## Registry-Tag

`[REWARD_TYPE]` **->** Used to declare a reward type

## Action-Options

`(EXP / LEVEL / BOOST)` **->** Options that are available for Reward-Type action

`(Ranged OR Static)` **->** Must be one of these, see below for examples on how to use.

## Action-Example

`[REWARD_TYPE] EXP [1-500]`  **->** This example shows us there is a reward type of **EXP** and it can give between **1-500** experience when applied.

&#x20;`[REWARD_TYPE] LEVEL 2` **->** This example shows us there is a reward type of **LEVEL** and it can apply **2** levels to the applied armor piece.

## Configuration Example

```yaml
    Script:
      - "[REWARD_TYPE] EXP [1-500]"
      - "[MESSAGE] &6&l+ &e%amount% Armor Experience &8&l(&7%armor_piece%&8)"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}
{% endtab %}

{% tab title="Requirement" %}
The **Requirement** action allows you to make items that can only be used if the player has the specified requirement.

You can create some very complex requirements if you are good at placeholder parsing, and could introduce new gameplay features if used correctly.

## Registry-Tag

`[REQUIREMENT]` **->** Used to declare a requirement.

## Action-Options

`(Expression)` **->** Options that are available for Reward-Type action

## Action-Example

`[REQUIREMENT] %edprison_economy_blocks% > 10000`  **->** This example shows us that to get through this requirement, the player must have more than **10,000** blocks. This placeholder is apart of a different plugin, demonstration purposes only.

## Configuration Example

```yaml
    Script:
      - "[REQUIREMENT] %edprison_economy_blocks% > 10000"
      - "[REWARD_TYPE] EXP [1-500]"
      - "[MESSAGE] &6&l+ &e%amount% Armor Experience &8&l(&7%armor_piece%&8)"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}
{% endtab %}

{% tab title="Particle Effect" %}
The **Particle Effect** action allows you integrate particles into the armor item. For particle types, please use the particles on the Spigot API which can be found [here](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html).

## Registry-Tag

`[PARTICLE_EFFECT]` **->** Used to declare a particle effect action.

## Action-Options

`(Particle Type)` **->** Options that are available for particle effect action.

## Action-Example

`[PARTICLE_EFFECT] FLAME`  **->** This is an example of how to summon a flame particle on the player when executed.

## Configuration Example

```yaml
    Script:
      - "[PARTICLE_EFFECT] FLAME"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}
{% endtab %}

{% tab title="Sound" %}


The **Sound** action allows you integrate sound into the armor item. For sound types, please use the sounds on the Spigot API which can be found [here](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html).

## Registry-Tag

`[SOUND]` **->** Used to declare a sound action.

## Action-Options

`(Sound)` **->** Options that are available for Sound action

`(Volume & Pitch)` **->** Options that are available for Sound action.

## Action-Example

`[SOUND] ENTITY_PLAYER_LEVELUP;1.0;1.0` **->** This is an example of how sounds can be played to the player that executed the item.

## Configuration Example

```yaml
    Script:
      - "[SOUND] ENTITY_PLAYER_LEVELUP;1.0;1.0"
      - "[REWARD_TYPE] EXP [1-500]"
      - "[MESSAGE] &6&l+ &e%amount% Armor Experience &8&l(&7%armor_piece%&8)"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}
{% endtab %}

{% tab title="Message" %}
The **Message** action allows you integrate messages into your items, displaying some additional information or even placeholders.

## Registry-Tag

`[MESSAGE]` **->** Used to declare a message action.

## Action-Options

`(Message)` **->** Options that are available for Message action

## Action-Example

`[MESSAGE] &6&l+ &e%amount% Armor Experience &8&l(&7%armor_piece%&8)` **->** This is an example of how to display messages to the player who executed the item.

## Configuration Example

```yaml
    Script:
      # You can use Placeholder API in these messages & %raw_amount% if needed.
      - "[MESSAGE] &6&l+ &e%amount% Armor Experience &8&l(&7%armor_piece%&8)"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}

{% hint style="warning" %}
The **%amount%** placeholder will not work correctly if **\[REWARD\_TYPE]** is not above.
{% endhint %}
{% endtab %}

{% tab title="Console" %}
The **Console** action allows you integrate commands that can be only executed via console into your items.

## Registry-Tag

`[CONSOLE]` **->** Used to declare a console action.

## Action-Options

`(Message)` **->** Options that are available for Console action

## Action-Example

`[CONSOLE] give %player% diamond_sword` **->** This is an example of how to give a diamond sword to a player via console.

## Configuration Example

```yaml
    Script:
      - "[CONSOLE] give %player% diamond_sword"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}
{% endtab %}

{% tab title="Change Color" %}
The **Change Color** action allows you to give some customization to the wearers armor, however this only works on leather armor.

## Registry-Tag

`[CHANGE_COLOR]` **->** Used to declare a change color action.

## Action-Options

`(r, g, b)` **->** Options that are available for change color action

## Action-Example

`[CHANGE_COLOR] 255,0,0` **->** This is an example of how to dye the wearers leather armor red

## Configuration Example

```yaml
    Script:
      - "[CHANGE_COLOR] 255,0,0"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}

{% hint style="warning" %}
**Warning!** This action do not work on versions above 1.20.5
{% endhint %}
{% endtab %}

{% tab title="Title" %}
The **Title** action allows you to send titles to the executed player

## Registry-Tag

`[TITLE]` **->** Used to declare a title action.

## Action-Options

`(Title & Subtitle)` **->** Options that are available for title action

## Action-Example

`[TITLE] Welcome,%player% to the battlefield!` **->** This is an example of how to send a player a title and subtitle with some text. You must separate title and subtitle with a **comma**.

## Configuration Example

```yaml
    Script:
      - "[TITLE] Welcome,%player% to the battlefield!"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}
{% endtab %}

{% tab title="Change Material" %}
The **Change Material** action allows you to customize the material of the item, it also has some additional advanced options.

## Registry-Tag

`[CHANGE_MATERIAL]` **->** Used to declare a change material action.

## Action-Options

`(Material)` **->** Option that are available for change material action\
`(~Armor Type)` **->** Option that is available for the change material action (\~ALL\~HELMET\~CHESTPLATE\~LEGGINGS\~BOOTS)\
`(Apply Chance)` **->** Option that is available for change material action

## Action-Example

\[CHANGE\_MATERIAL] NETHERITE\~ALL\~30% **->** This is an example of how to send a player a title and subtitle with some text. You must separate title and subtitle with a **comma**.

## Configuration Example

```yaml
    Script:
      - "[CHANGE_MATERIAL] NETHERITE~ALL~30%"
      - "[SOUND] ENTITY_BAT_TAKEOFF;1;1"
```

{% hint style="success" %}
This action is marked as **working**.
{% endhint %}
{% endtab %}

{% tab title="Custom-Sound" %}
The **Custom-Sound** action allows you send custom sounds to the player that executed the action.

## Registry-Tag

`[CUSTOM_SOUND]` **->** Used to declare a custom sound action.

## Action-Options

`(Sound)` **->** Options that are available for Sound action

`(Volume & Pitch)` **->** Options that are available for Sound action.

## Action-Example

`[CUSTOM_SOUND] mysound:custom.sound;1.0;1.0` **->** Please be aware that some plugins may execute custom sounds differently, this example was from items adder.

## Configuration Example

```yaml
    Script:
      - "[CUSTOM_SOUND] mysound:custom.sound;1;1"
```
{% endtab %}

{% tab title="Action-Bar" %}
The **Action-Bar** action will send an action bar to the player with the same placeholders from normal messaging.

## Registry-Tag

`[ACTION_BAR]` **->** Used to declare a action-bar action.

## Action-Options

`(Message)` **->** Options that are available for the Action-Bar action.

## Action-Example

`[ACTION_BAR] &6You received &f%amount% &eArmor EXP!` **->** This is an example of how to send an action-bar to the player with some placeholders.

## Configuration Example

```yaml
    Script:
      - "[ACTION_BAR] &6You received &f%amount% &eArmor EXP!"
```
{% endtab %}

{% tab title="Change-Backpack" %}
The **Change-Backpack-Owner** action will transfer the backpack to the player who executed this script, you **MUST** have soulbound-backpack set to true in the backpack config.

## Registry-Tag

`[CHANGE_BACKPACK_OWNER]` **->** Used to declare a change-backpack script.

## Action-Options

`(Player)` **->** Options that are available for the Change-Backpack action.

## Action-Example

`[CHANGE_BACKPACK_OWNER] %player%` **->** This is an example on how to change the backpack to the player who executed the script.

## Configuration Example

```yaml
    Script:
      - "[CHANGE_BACKPACK_OWNER] %player%"
      - "[MESSAGE] &3&lTransferred! &bSuccessfully transferred backpack ownership to you."
```
{% endtab %}

{% tab title="Multi-Line" %}
The **Multi-Line** action will allow you to send multiple lined messages

## Registry-Tag

`[MULTI_LINE]` **->** Used to declare a change-backpack script.

## Action-Options

`(Message)` **->** Options that are available for the Multi-Line action.

## Action-Example

`[MULTI_LINE] \nNew Line \nAnother New Line` **->** This is an example on how to use the multi-line action type.

## Configuration Example

```yaml
    Script:
      - "[MULTI_LINE] \nNew Line \nAnother New Line"
```
{% endtab %}
{% endtabs %}

## Custom Actions

If you are wanting to implement your own custom actions, you can visit the [Action Implementation](actions-system/action-implementation) page, as it contains all the information on how to do so. It however does require you to know java and understand basic concepts, if you need help in this or have any additional questions, open a ticket in our discord.











