Kit Configuration

Complete guide to configuring the EssentialsC kit system. Set up starter kits, tools, member rewards, cooldowns, and item customization.

On This Page

Kit Settings

Main kit configuration options

Item Settings

Configure kit items

Example Configuration

Complete kit examples

Kit Settings

Kits are defined in plugins/EssentialsC/kits.yml. Each kit has a unique ID and contains settings for display, access control, and cooldowns.

kits.<kit-id> Configuration Section null

The root configuration section for a kit. Replace <kit-id> with a unique identifier (lowercase, no spaces). This ID is used in commands like /kit <kit-id>.

YAML 
kits:
  starter:    # Kit ID - used in /kit starter
    # kit configuration here
  tools:      # Another kit
    # kit configuration here
display-name String (MiniMessage) null

The display name shown to players for this kit. Supports MiniMessage formatting for colors and styles. This appears in kit list commands and GUI menus.

YAML 
display-name: "<#2791F5>Starter Kit"
# or with gradients:
display-name: "VIP Kit"
description String null

A brief description of what the kit contains. Displayed in kit listings and helps players understand the kit's purpose.

YAML 
description: "Basic items for new players"
description: "Premium tools and armor for VIP members"
cooldown Integer (Seconds) 0

The cooldown period in seconds before a player can claim this kit again. Set to 0 for no cooldown. Common values: 3600 (1 hour), 86400 (24 hours), 604800 (7 days).

YAML 
cooldown: 86400      # 24 hours
cooldown: 3600       # 1 hour
cooldown: 604800     # 7 days
cooldown: 0          # No cooldown (claim anytime)
one-time Boolean false

When set to true, this kit can only be claimed once per player ever. Useful for tutorial kits or one-time rewards. Overrides cooldown settings.

YAML 
one-time: false    # Can be claimed multiple times (with cooldown)
one-time: true     # Can only be claimed once ever
first-join Boolean false

When set to true, this kit is automatically given to players when they first join the server. Useful for starter kits. Players will still be able to claim it manually later if cooldown permits.

YAML 
first-join: true   # Given automatically on first join
first-join: false  # Must be claimed manually with /kit
max-claims Integer 0

Maximum number of times a player can claim this kit. Set to 0 for unlimited claims. Once a player reaches this limit, they cannot claim the kit again.

YAML 
max-claims: 0      # Unlimited claims
max-claims: 5      # Can only claim 5 times total
max-claims: 1      # Same as one-time: true
permission String null

Optional permission required to claim this kit. If set, players without this permission will not see or be able to claim the kit. Leave empty for no restriction.

YAML 
permission: "essentialsc.kit.vip"     # VIP only kit
permission: "essentialsc.kit.starter" # Permission node for starter
permission: ""                        # No permission required

Item Settings

Each kit contains a list of items that players receive when claiming. Items support extensive customization including names, lore, enchantments, and NBT data.

items List<ItemStack> Empty list

A list of items that make up this kit. Each item is a configuration section with properties defining the item's appearance and attributes.

YAML 
items:
  - type: STONE_SWORD
    amount: 1
    name: "<#2791F5>Starter Sword"
  - type: BREAD
    amount: 16
type Material (Required) null

The Minecraft material type for this item. Must be a valid Bukkit Material enum value. This determines the base item (e.g., DIAMOND_SWORD, OAK_LOG, GOLDEN_APPLE).

YAML 
type: "STONE_SWORD"
type: "IRON_PICKAXE"
type: "COOKED_BEEF"
type: "PLAYER_HEAD"  # Use with skullOwner or textureUrl
amount Integer 1

The quantity of this item to give. If the amount exceeds the item's max stack size, multiple stacks will be given automatically.

YAML 
amount: 1    # Single item
amount: 16   # 16 items (one stack for most items)
amount: 64   # Full stack
name String (MiniMessage) null

Custom display name for the item. Supports MiniMessage formatting. If not set, uses the default Minecraft item name.

YAML 
name: "<#2791F5>Kit Starter"
name: "Legendary Sword"
name: "Basic Pickaxe"
lore List<String> (MiniMessage) Empty list

Description lines shown when hovering over the item. Supports MiniMessage formatting. Each string in the list becomes a new line in the lore.

YAML 
lore:
  - "A starter weapon"
  - "for new adventurers"
  - ""
  - "Kit Item"
enchantments Map<Enchantment, Integer> Empty map

Enchantments to apply to the item. Use Bukkit enchantment names as keys and level numbers as values. Common enchantments: SHARPNESS, EFFICIENCY, UNBREAKING, FORTUNE, MENDING.

YAML 
enchantments:
  SHARPNESS: 5
  FIRE_ASPECT: 2
  UNBREAKING: 3

# Empty for no enchantments:
enchantments: {}
unbreakable Boolean false

When set to true, the item will not lose durability when used. The item still shows a durability bar but never breaks.

YAML 
unbreakable: true   # Item never breaks
unbreakable: false  # Normal durability behavior
flags List<ItemFlag> Empty list

Hide specific item attributes from the tooltip. Useful for hiding enchantments, durability, or other vanilla item information.

YAML 
flags:
  - "HIDE_ENCHANTS"
  - "HIDE_ATTRIBUTES"
  - "HIDE_UNBREAKABLE"
  - "HIDE_DESTROYS"
  - "HIDE_PLACED_ON"
  - "HIDE_POTION_EFFECTS"
  - "HIDE_DYE"
custom-model-data Integer 0

Custom model data value for resource pack support. Used to display custom textures/models when using a server resource pack. Set to 0 to disable.

YAML 
custom-model-data: 0     # No custom model
custom-model-data: 1001  # Custom texture ID
nbt Map<String, Object> Empty map

Custom NBT data stored in the item's PersistentDataContainer. Useful for plugin integration or tracking items. Keys are stored under the EssentialsC namespace.

YAML 
nbt:
  kit_item: "starter_sword"
  tier: "common"
  soulbound: true

Example Configuration

Here's a complete example of a kits.yml file with three different kit types: starter, tools, and member.

YAML 
kits:
  starter:
    display-name: "<#2791F5>Starter Kit"
    description: "Basic items"
    cooldown: 86400 # 24 hours
    one-time: false
    first-join: true
    max-claims: 10
    items:
      - type: STONE_SWORD
        amount: 1
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: STONE_PICKAXE
        amount: 1
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: STONE_SHOVEL
        amount: 1
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: BREAD
        amount: 16
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: SUGAR_CANE
        amount: 16
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: CARROT
        amount: 4
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: { }
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: POTATO
        amount: 4
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: GOLDEN_APPLE
        amount: 1
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: APPLE
        amount: 8
        name: "<#2791F5>Kit Starter"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

  tools:
    display-name: "<#FF5D00>Tools Kit"
    description: "Basic tools for gathering resources"
    cooldown: 43200 # 12 hours
    one-time: false
    first-join: false
    max-claims: 0
    items:
      - type: IRON_PICKAXE
        amount: 1
        name: "<#FF5D00>Kit Tools"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: IRON_AXE
        amount: 1
        name: "<#FF5D00>Kit Tools"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: IRON_SHOVEL
        amount: 1
        name: "<#FF5D00>Kit Tools"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: IRON_SWORD
        amount: 1
        name: "<#FF5D00>Kit Tools"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: IRON_HOE
        amount: 1
        name: "<#FF5D00>Kit Tools"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: FLINT_AND_STEEL
        amount: 1
        name: "<#FF5D00>Kit Tools"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: FISHING_ROD
        amount: 1
        name: "<#FF5D00>Kit Tools"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

  member:
    display-name: "<#FFD400>Member Kit"
    description: "Rewards for server members"
    cooldown: 604800 # 7 days
    one-time: false
    first-join: false
    max-claims: 0
    items:
      - type: GOLDEN_SWORD
        amount: 1
        name: "<#FFD400>Kit Member"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: GOLDEN_PICKAXE
        amount: 1
        name: "<#FFD400>Kit Member"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: COOKED_BEEF
        amount: 32
        name: "<#FFD400>Kit Member"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: GOLDEN_APPLE
        amount: 8
        name: "<#FFD400>Kit Member"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}

      - type: OAK_LOG
        amount: 32
        name: "<#FFD400>Kit Member"
        lore: []
        enchantments: {}
        unbreakable: false
        flags: []
        custom-model-data: 0
        nbt: {}