# Kits Tutorial

In this page you will find all properties of kits configuration files. Everytime you modify something in these files you must reload the plugin using `/kit reload`.

## Items

Each kit has it items. They are automatically saved in the kit config when you create the kit, but you can modify them manually if you need to (only if you save the items using `/kit create <kit> configurable`). You can find all item properties [**HERE**](/playerkits-2/items-tutorial.md).

```yaml
items:
  1:
    id: IRON_AXE
    name: "&bBasic Iron Axe"
    amount: 1
  2:
    id: IRON_PICKAXE
    name: "&bBasic Iron Pickaxe"
    amount: 1
```

{% hint style="info" %}
All items in the plugin, even the ones placed in the `inventory.yml` file follow the same structure and contain the same properties.
{% endhint %}

{% hint style="warning" %}
If you save the kit without using the configurable parameter, you'll see something like this:

```
items:
  '1':
    original:
      ==: org.bukkit.inventory.ItemStack
      v: 3953
      type: GOLDEN_APPLE
      amount: 64
```

{% endhint %}

## Display Items

A kit will display a certain item on the GUI depending on the status of the kit for the player. There are 5 possibilities `(default, no_permission, cooldown, one_time, one_time_requirements)`. The format is the following:

```yaml
display:
 <type>:
   <item>
```

Remember that the `item` to be displayed has the properties listed [**HERE**](/playerkits-2/items-tutorial.md).

### Default Display Item

The item displayed when the player is able to claim the kit.

```yaml
display:
  default:
    id: IRON_AXE
    name: '&c&lIron &cKit'
    lore:
      - '&fThis kit includes:'
      - '&8- &7x1 Iron Axe'
      - '&8- &7x1 Iron Pickaxe'
      - '&8- &7x1 Iron Sword'
      - ' '
      - '&7Cooldown: &c3 hours'
      - ''
      - '&aLeft Click to claim!'
      - '&bRight Click to preview!'
    item_flags:
      - HIDE_ATTRIBUTES
```

{% hint style="info" %}
On this item you could specify the items provided by this kit, and the cooldown when claiming it.
{% endhint %}

### No Permissions Display Item&#x20;

The item displayed when the player doesn't have the permissions to claim the kit.

```yaml
display:
  no_permission:
    id: BARRIER
    name: '&c&lDiamond &cKit'
    amount: 1
    lore:
      - '&fThis kit includes:'
      - '&8- &7x1 Diamond Axe'
      - '&8- &7x1 Diamond Pickaxe'
      - '&8- &7x1 Diamond Sword'
      - ''
      - "&cYou don''t have permissions"
      - '&cto claim this kit.'
      - ''
      - '&7You need: &bVIP&6+ &7rank.'
```

{% hint style="info" %}
On this item you should tell the player that a permission/rank is required to claim the kit.
{% endhint %}

### Cooldown Display Item

The item displayed when the kit is on cooldown, and the player must wait to claim the kit again.

```yaml
display:
  cooldown:
    id: IRON_AXE
    name: "&c&lIron &cKit"
    lore:
      - '&fThis kit includes:'
      - '&8- &7x1 Iron Axe'
      - '&8- &7x1 Iron Pickaxe'
      - '&8- &7x1 Iron Sword'
      - ' '
      - "&cYou need to wait &7%time%"
      - "&cto claim this kit again."
    item_flags:
      - HIDE_ATTRIBUTES
```

{% hint style="info" %}
On this item you should use the `%time%` variable to tell the player the remaining time to claim the kit again.
{% endhint %}

### One Time Display Item

The item displayed when the kit has the `one_time` option enabled, and the player has already claimed the kit once.

```yaml
display:
  one_time:
    id: BARRIER
    name: "&c&lIron &cKit"
    lore:
      - "&cYou can't claim this kit again."
    item_flags:
      - HIDE_ATTRIBUTES
```

{% hint style="info" %}
On this item you should tell the player that he already claimed the kit and is not possible to do it again.
{% endhint %}

### One Time Requirements Display Item

The item displayed when the kit has the `one_time_requirements` option enabled, and the player has already accomplished the requirements once.

```yaml
display:
  one_time_requirements:
    id: DIAMOND_SWORD
    name: '&c&lDiamond &cKit'
    amount: 1
    lore:
      - '&fThis kit includes:'
      - '&8- &7x1 Diamond Axe'
      - '&8- &7x1 Diamond Pickaxe'
      - '&8- &7x1 Diamond Sword'
      - ''
      - '&7Cooldown: &c12 hours'
      - ''
      - '&aLeft Click to claim!'
      - '&bRight Click to preview!'
    item_flags:
      - HIDE_ATTRIBUTES
```

{% hint style="info" %}
On this item you should only tell the player the cooldown to claim the kit, since it has already been bought (or requirements have already been accomplished)
{% endhint %}

## Cooldown

The cooldown to claim the kit in seconds.

```yaml
cooldown: 10800
```

## Permission Required

Whether the player needs a permission to claim the kit (true/false).

```yaml
permission_required: true
```

{% hint style="info" %}
If this option is set to `true`, the player will need the following permission to claim the kit: `playerkits.kit.<kit>` (unless you use a custom permission explained below)
{% endhint %}

## Custom Permission

Allows to customize the permission required to use the kit. `permission_required` must be enabled.

```yaml
custom_permission: "scorpionsmc.kits"
```

## One Time

Whether the kit is only claimable once (true/false).

```yaml
one_time: false
```

## Auto Armor

Whether kit armor should be equipped automatically when claiming the kit (true/false).

```yaml
auto_armor: true
```

## Clear Inventory

When enabled, player inventory will be emptied before giving the kit.

```yaml
clear_inventory: true
```

## Save Original Items

Whether the items from the kit should be saved as an EXACT COPY of the original items. You should not modify this option, and let the plugin add it to the config automatically when using `/kit create <kit> original`. Click [**HERE**](/playerkits-2/commands-and-permissions.md#kit-creation-with-original-parameter) to know more.

```yaml
save_original_items: false
```

## Allow Placeholders on Original Items

Whether the items from the kit can contain PlaceholderAPI variables in the name/lore and should be replaced. Only works when the `save_original_items` option is set to true.

```yaml
allow_placeholders_on_original_items: true
```

## Actions

You can define certain actions to execute when the player claims a kit, or there is an error when claiming the kit. The format is the following:

```yaml
actions:
 <action_type>:
   <number>:
     <action>
```

### Claim Actions

Actions that will be executed when the player claims the kit.

```yaml
actions:
  claim:
    1:
      action: "playsound: BLOCK_NOTE_BLOCK_PLING;10;2"
    2:
      action: "firework: colors:YELLOW,RED type:BALL fade:AQUA power:0"
    3:
      action: 'console_command: bc &6%player% &ejust claimed a &aDIAMOND KIT&e!'
      execute_before_items: false
      count_as_item: false
      display_item:
        id: BOOK
        name: '&4Announcement'
        amount: 1
        lore:
        - '&7Claiming this kit will send an announcement'
        - '&7to the whole server.'
```

### Error Actions

Actions that will be executed when there is an error when claiming the kit (for example, the player doesn't have permissions)

```yaml
actions:
  error:
    1:
      action: "playsound: BLOCK_NOTE_BLOCK_PLING;10;0.1"
```

### Actions Properties

#### Action

The action to be executed. All actions [**HERE**](/playerkits-2/actions.md). You can use the `%player%` variable to replace the player name.

```yaml
action: "playsound: BLOCK_NOTE_BLOCK_PLING;10;0.1"
```

#### Execute Before Items

Whether the action should be executed before giving the kit items to the player (true/false).

```yaml
execute_before_items: true
```

#### Count as Item

When enabled, this action will count as an item, and therefore will be used to count empty slots on the player inventory when claiming the kit. Useful when you want to give items through a command.

```yaml
count_as_item: true
```

#### Display Item

You can set a display item to a certain action, it is optional. This item will be displayed when previewing the kit.

```yaml
display_item:
  id: "BOOK"
  name: "&4Announcement"
  lore:
  - "&7Claiming this kit will send an announcement"
  - "&7to the whole server."
```

## Requirements

You can make the kit buyable, or even add some extra requirements/conditions.

```yaml
requirements:
  one_time_requirements: false
  price: 5000
  message:
  - '&fYou need $5000'
  - '&8Status: &7$%vault_eco_balance% %status_symbol_price%'
  - ''
  - '&fYou need level 20+'
  - '&8Status: &7$%player_level% %status_symbol_requirement_1%'
  extra_requirements:
  - "%player_level% >= 20"
```

### Price

Add this option if the player must pay to buy the kit.

```yaml
price: 5000
```

{% hint style="warning" %}
For this option to work, you need [**Vault**](https://www.spigotmc.org/resources/vault.34315/) and an economy plugin such as **EssentialsX** or **XConomy**.
{% endhint %}

### One Time Requirements

If this option is enabled, the player will need to pay for the kit (or accomplish the requirements) only once.

<pre class="language-yaml"><code class="lang-yaml"><strong>one_time_requirements: false
</strong></code></pre>

### Extra Requirements

Additional requirements that the player must accomplish to claim the kit. Needs [**PlaceholderAPI**](https://www.spigotmc.org/resources/placeholderapi.6245/). Use the following format: `<variable> <conditional> <value>`. Example: `%player_level% >= 15`

The previous example will check if the player is level 15 or more, if so then the kit could be claimed.

{% hint style="info" %}
This is the list of conditionals you can use:

`==` (equals)\
`!=` (not equals)\
`>=` (greater or equal than)\
`<=` (less or equal than)\
`>` (greater than)\
`<` (less than)
{% endhint %}

{% hint style="warning" %}
Remember to download the PlaceholderAPI expansion of variables you are using, with the following command: `/papi ecloud download <expansion>`
{% endhint %}

```yaml
extra_requirements:
- "%player_level% >= 20"
- "%player_world% == Survival1"
```

### Message

It is very important to also specify a requirements message, which will appear when using the `%kit_requirements_message%` variable in the **buy\_requirements\_inventory** inventory (on the **inventory.yml** file). This message should tell the player what additional requirements are needed, you can customize it completely.

{% hint style="info" %}
To show whether or not the player accomplishes a condition, you must use the `%status_symbol_requirement_<value>%` variable. This will be replaced with the symbol specified in the **requirementsMessageStatusSymbolTrue** and **requirementsMessageStatusSymbolFalse** messages on the **messages.yml** file.

You must replace `<value>` with the number of the condition.&#x20;

The same you can do to get the status symbol of the price requirement, this time using the  `%status_symbol_price%` variable.

In the following example, the %status\_symbol\_price% will be replaced with a ✔ if the player has $5000 and with ✖ if not. The same goes for the level requirement.
{% endhint %}

```yaml
requirements:
  one_time_requirements: false
  price: 5000
  message:
  - '&fYou need $5000'
  - '&8Status: &7$%vault_eco_balance% %status_symbol_price%'
  - ''
  - '&fYou need level 20+'
  - '&8Status: &7$%player_level% %status_symbol_requirement_1%'
  extra_requirements:
  - "%player_level% >= 20"
```


---

# 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://ajneb97.gitbook.io/playerkits-2/kits-tutorial.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.