Kits

modules/kits.yml

/kit on its own opens the same grid /kits does; /kit <name> takes one straight away.

kits:
  first-join: starter

The kit handed out the first time a player ever joins. Empty for none.

Writing a kit#

kits:
  definitions:

    starter:
      display: '<green><bold>Starter'
      lore:
        - '<gray>Everything you need to begin'
      icon: LEATHER_CHESTPLATE
      cooldown-seconds: 0
      one-time: true
      price: 0.0
      permission: ''
      items:
        - material: STONE_SWORD
        - material: STONE_PICKAXE
        - material: BREAD
          amount: 16
        - material: LEATHER_CHESTPLATE
          name: '<green>Starter Chestplate'
          lore:
            - '<dark_gray>Welcome to the server'
          enchantments:
            protection: 1

Anything that will not fit in the player's inventory lands at their feet rather than vanishing.

The icon#

Either a material name, or the same block an item takes — which is what /kitedit writes when you drop a real item into the icon slot:

      icon: DIAMOND_SWORD

      icon:
        material: DIAMOND_SWORD
        name: '<gold>VIP Sword'
        enchantments: { sharpness: 5 }

Items#

      items:
        - material: DIAMOND_SWORD      # required
          amount: 1
          name: '<gold>Blade'
          lore:
            - '<gray>A line'
          enchantments:
            sharpness: 5
            unbreaking: 3
          unbreakable: true

Enchantments are written the way the game writes them today — protection, sharpness, unbreaking — not the old PROTECTION_ENVIRONMENTAL spellings, so the same file works on every supported version.

Placeholders in items#

      placeholders: true
      items:
        - material: DIAMOND_SWORD
          name: "<gold>%player%'s Blade"
          lore:
            - '<gray>Claimed on %date%'

%player%, %date% and %time% are this plugin's own; anything PlaceholderAPI knows works too when it is installed.

Off by default, and only the items that actually hold a % are rebuilt per player, so a kit of sixty plain items pays nothing for leaving it on.

Requirements#

What has to be true before a kit may be taken. Each one is written type: value, and takes either shape:

      requirements:
        - 'permission: chorus.kits.vip'
        - condition: 'placeholder: %player_level% >= 10'
          deny: '<red>Come back at level 10.'

placeholder is the one that makes the rest optional: anything any plugin exposes through PlaceholderAPI can gate a kit, compared with >=, <=, ==, !=, >, < or contains.

Without a deny line the player gets the message from messages.yml instead.

Actions#

      claim-actions:
        - 'message: <green>Enjoy your %kit% kit.'
        - 'broadcast: <gray>%player% just claimed %kit%.'
        - 'actionbar: <green>Claimed'
        - 'title: <gold><bold>VIP;<gray>Welcome aboard'
        - 'sound: entity.player.levelup 1 1.4'
        - 'console: lp user %player% parent add vip'
        - 'player: spawn'
        - 'close'

      fail-actions:
        - 'sound: block.note_block.bass 0.5 0.7'

Run in the order listed. claim-actions happen when the kit is taken; fail-actions when the player is refused, whatever the reason.

console runs as the server, which is how a kit hands out something the player could not give themselves — a rank, a permission, another plugin's reward. It is also how a kit could hand out anything at all, so it is worth reading twice.

%player% and %kit% work in all of them, as does anything PlaceholderAPI knows.

The editor#

/kitedit opens the whole of that as a screen. Every setting is a button.

A line the plugin cannot make sense of is shown in red rather than hidden, so a typo can be found here instead of only being missed in game.

The Add button on the requirement and action screens lists every type it accepts with an example of each, and the prompt that asks for the line repeats them. Nothing has to be looked up elsewhere.

Nothing in the screen sends you away to type a command, and nothing you type in a prompt becomes a chat message.

Whatever the screen writes goes back into modules/kits.yml in exactly the form above, so a kit built in game can still be opened in a text editor afterwards.

By command#

/kitedit vip create            makes it out of whatever you are carrying
/kitedit vip items             replaces its items with what you carry now
/kitedit vip icon DIAMOND
/kitedit vip display <gold>VIP
/kitedit vip cooldown 3600
/kitedit vip maxclaims 5
/kitedit vip price 500
/kitedit vip permission chorus.kits.use.vip
/kitedit vip onetime true
/kitedit vip delete

Leaving the value off puts a setting back to its default.

Items are written in the form above, so anything it cannot describe, such as custom model data, is not carried over. The command says so when it happens.

The editor's own look#

kits:
  editor:
    item-rows: 4
    filler: ''
    icon: ITEM_FRAME
    lore: BOOK
    items: CHEST
    preview: ENDER_CHEST
    cooldown: CLOCK
    max-claims: PAPER
    price: GOLD_INGOT
    permission: NAME_TAG
    enabled: LIME_DYE
    disabled: GRAY_DYE
    requirements: COMPARATOR
    claim-actions: EXPERIENCE_BOTTLE
    fail-actions: FIRE_CHARGE
    add: EMERALD
    new-kit: WRITABLE_BOOK
    back: ARROW
    delete: LAVA_BUCKET
    close: BARRIER

Every one falls back to something that has existed far longer than the oldest version this jar runs on, so a name you leave out can never break the screen.

What the buttons say is in menus.yml under menu.editor.

/kitreset#

/kitreset daily Notch      clears one cooldown
/kitreset * Notch          every kit at once

Also lets a one-time kit be taken again. The player has to be online, since the record of what they have taken is only loaded while they are.

The menu#

kits:
  menu:
    enabled: true
    rows: 3
    icon: CHEST
    filler: ''
    navigation-filler: GRAY_STAINED_GLASS_PANE
    previous-page: ARROW
    next-page: ARROW
    close: BARRIER

A kit on cooldown, already taken, or whose requirements are not met shows why rather than disappearing.

Kit signs#

[Kit]
starter

100

Runs /kit starter as the player who clicked, so its permission and cooldown still apply. See Utility, signs and powertools.

Permissions#