How to set up EssentialsX kits

A kit is a bundle of items, money or commands that a player claims with /kit <name>. EssentialsX has kits built in, so most servers never need a separate kits plugin: the starter tools a new player gets, the daily reward a VIP claims and the one-off welcome pack are all the same feature with different settings.

This guide sets up all three, then puts the kits behind ranks and in a clickable menu.

Where kits live#

EssentialsX keeps kits in plugins/Essentials/kits.yml. It ships with a few examples. Here is the first:

kits:
  tools:
    delay: 10
    items:
      - stonesword 1
      - stoneshovel 1
      - stonepickaxe 1
      - stoneaxe 1

Each kit has a name (tools), a delay in seconds before the same player can claim it again, and a list of items. Players claim it with /kit tools. /kit on its own lists every kit they're allowed to use, and /showkit tools shows what's inside.

Make a kit in game with /createkit#

The quickest way to make a kit is to build it in your own inventory. Lay the items out exactly as players should receive them, then run:

/createkit starter 3600

That saves your whole inventory as a kit called starter with a one-hour cooldown (3600 seconds), straight into kits.yml. Each item is saved with a slot: prefix, so it lands in the same slot it sat in. /delkit starter removes the kit again.

Two settings in config.yml change what /createkit does:

• pastebin-createkit: true gives you a link to the kit's code instead of writing it into kits.yml.
• use-nbt-serialization-in-createkit: true saves items as NBT, so shulker boxes and items with custom attributes survive intact. It only works on Paper 1.15.2 or newer, and you can't downgrade the server once kits are saved this way. Those items show up in kits.yml as long lines starting with @, which aren't meant to be edited by hand.

Write a kit by hand#

Each line under items is the item, then the amount, then any enchantments and item meta:

kits:
  starter:
    delay: 3600
    items:
      - stone_sword 1 sharpness:1 name:&aStarter_Sword
      - bread 16
      - leather_chestplate 1 name:&7Travel_Coat lore:Given_to_every_new_player|Look_after_it
      - $250
      - /broadcast {USERNAME} just claimed the starter kit!

• Items take either their Minecraft name (stone_sword) or an EssentialsX short name (stonesword).
• Enchantments are name:level, like sharpness:1. Levels above vanilla's limit need unsafe-enchantments: true in config.yml.
• Names and lore turn underscores into spaces; write \_ when you need a real underscore. A | starts a new lore line.
• Money: a line that starts with $ gives the player that much.
• Commands: a line that starts with / runs that command from the console when the kit is claimed. {USERNAME} becomes the player's username and {PLAYER} their display name.
• Slots: slot:<number> in front of an item puts it in that inventory slot. This is the form /createkit writes.

Set kit-auto-equip: true in config.yml and armour from a kit goes straight onto the player, as long as those armour slots are empty.

Save the file and run /essentials reload to load your changes. If the file doesn't parse, EssentialsX can't read the kits in it, so check it first:

For a server with a lot of kits, EssentialsX also reads every .yml file in a kits folder next to kits.yml. Each file uses the same format.

Cooldowns and one-time kits#

delay is in seconds:

Players with essentials.kit.exemptdelay skip cooldowns entirely, which is handy for staff. /kitreset starter Steve clears Steve's cooldown on starter, and leaving the name off clears your own.

Set skip-used-one-time-kits-from-kit-list: true in config.yml and a one-time kit drops out of /kit once the player has used it.

To charge for a kit, add it under command-costs in config.yml. This makes /kit starter cost $500 every time:

command-costs:
  kit-starter: 500

Give new players a kit on their first join#

This part needs the EssentialsX Spawn module, a separate jar from the main plugin. With it installed, find the newbies: section of config.yml and set its kit:

newbies:
  kit: starter

EssentialsX hands this kit out regardless of cost and permissions, and doesn't start its cooldown. So if new players are also allowed /kit starter, they can claim a second one straight away. When that matters, give first-joiners their own kit (welcome, say) and leave starter for /kit.

Lock kits to ranks with LuckPerms#

Two kinds of permission decide who can claim what:

• essentials.kit lets a player use /kit at all.
• essentials.kits.<name> lets them claim that one kit.

/lp group default permission set essentials.kit true
/lp group default permission set essentials.kits.starter true
/lp group vip permission set essentials.kits.vip true
/lp group vip parent add default

With the last line, VIP inherits everything default has, so VIPs can claim both kits. Staff with essentials.kit.others can also give a kit to someone else with /kit vip Steve.

With more than a couple of ranks, these commands get long. In the Server Planner, add a toggle perk for each kit with the node essentials.kits.<name>, tick it on the ranks that get it, and export the LuckPerms commands with the inheritance already worked out.

Colour your kit names#

name: and lore: understand & colour codes, and &#RRGGBB hex colours on 1.16 and newer. This is how &6&lStarter &eKit looks in game:

In a kit line, that becomes name:&6&lStarter_&eKit, with an underscore where the space was, because a space ends the name: value.

For a gradient, build it in the Text Studio and copy the Hex output, which uses the &#RRGGBB form EssentialsX reads. Swap each space for an underscore before you paste it into a kit line.

A kits menu with DeluxeMenus#

/kit lists kits in chat. For a menu players can click, DeluxeMenus can run /kit on the player's behalf:

menu_title: '&8Kits'
open_command: kitmenu
register_command: true
size: 27
items:
  starter:
    material: STONE_SWORD
    slot: 11
    display_name: '&aStarter'
    lore:
      - '&7Once an hour'
      - ''
      - '&eClick to claim'
    left_click_commands:
      - '[player] kit starter'
      - '[close]'
  vip:
    material: DIAMOND_SWORD
    slot: 15
    display_name: '&6VIP'
    lore:
      - '&7Once a day'
      - ''
      - '&eClick to claim'
    left_click_requirement:
      requirements:
        rank:
          type: has permission
          permission: essentials.kits.vip
      deny_commands:
        - '[message] &cThe VIP kit comes with the VIP rank.'
    left_click_commands:
      - '[player] kit vip'
      - '[close]'

Register the file in DeluxeMenus' own config.yml, then run /dm reload:

gui_menus:
  kits:
    file: kits.yml

/kit still checks permissions and cooldowns itself. The requirement on the VIP item only swaps EssentialsX's refusal for a friendlier message. With PlaceholderAPI's Essentials expansion installed, %essentials_kit_is_available_vip% and %essentials_kit_time_until_available_vip% let an item show a cooldown instead; the advanced_menu.yml that ships with DeluxeMenus does exactly that.

You can lay this menu out slot by slot in the GUI Builder, which exports the same YAML:

Mistakes that stop kits loading#

• Tabs. YAML only allows spaces for indentation, and one tab breaks the whole file.
• The amount in the wrong place. The amount goes straight after the item. diamond_sword sharpness:5 fails, because EssentialsX reads sharpness:5 as the amount. Write diamond_sword 1 sharpness:5.
• A space after a colon. name:&6Starter works. name: &6Starter turns the line into a YAML key and value, and the item breaks.
• Spaces in names and lore. A space ends the value. Use _.
• Unquoted colour codes in other plugins' files. DeluxeMenus values such as display_name: '&aStarter' need their quotes, because YAML reads a bare & at the start of a value as an anchor.
• Forgetting to reload. Edits to kits.yml take effect after /essentials reload or a restart.

Paste a kits.yml into the YAML Linter and it flags the tabs and unquoted colour codes before your server does.