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.

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

All items in the plugin, even the ones placed in the inventory.yml file follow the same structure and contain the same properties.

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

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:

display:
 <type>:
   <item>

Remember that the item to be displayed has the properties listed HERE.

Default Display Item

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

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

On this item you could specify the items provided by this kit, and the cooldown when claiming it.

No Permissions Display Item

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

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.'

On this item you should tell the player that a permission/rank is required to claim the kit.

Cooldown Display Item

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

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

On this item you should use the %time% variable to tell the player the remaining time to claim the kit again.

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.

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

On this item you should tell the player that he already claimed the kit and is not possible to do it again.

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.

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

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)

Cooldown

The cooldown to claim the kit in seconds.

cooldown: 10800

Permission Required

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

permission_required: true

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)

Custom Permission

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

custom_permission: "scorpionsmc.kits"

One Time

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

one_time: false

Auto Armor

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

auto_armor: true

Clear Inventory

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

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 to know more.

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.

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:

actions:
 <action_type>:
   <number>:
     <action>

Claim Actions

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

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)

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

Actions Properties

Action

The action to be executed. All actions HERE. You can use the %player% variable to replace the player name.

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).

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.

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.

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.

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.

price: 5000

For this option to work, you need Vault and an economy plugin such as EssentialsX or XConomy.

One Time Requirements

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

one_time_requirements: false

Extra Requirements

Additional requirements that the player must accomplish to claim the kit. Needs PlaceholderAPI. 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.

This is the list of conditionals you can use:

== (equals) != (not equals) >= (greater or equal than) <= (less or equal than) > (greater than) < (less than)

Remember to download the PlaceholderAPI expansion of variables you are using, with the following command: /papi ecloud download <expansion>

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.

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.

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.

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"