Using it

Kit files

Prefer editing files? Each kit is one YAML file in vkits/. This is the bundled Starter kit:

display-name: "<gradient:#5EEAD4:#B57CFF><bold>Starter</bold></gradient>"
# Shown where the menu lore has %description%.
description:
  - "<color:#A69CC4>Simple gear for a fresh start."
category: general
icon:
  material: WOODEN_SWORD
  custom-model-data: -1          # -1 = none
gui-slot: -1
sort-priority: 10                # higher = earlier in the menu
hidden: false                    # true = not shown in /vkit until owned

# Chance and pity
chance: 50.0                     # chance on the first roll (%)
pity:
  increase: 10.0                 # +10% after every miss
  cap: 90.0                      # the chance never goes above this
cooldown: "3d"                   # owners can claim again every 3 days (3d, 2h30m, 45s)

rewards:
  items:
    - material: STONE_SWORD
      name: "<color:#5EEAD4>Starter Blade"
      lore:
        - "<color:#A69CC4>A trusty first sword."
      enchants:
        SHARPNESS: 2
    - material: COOKED_BEEF
      amount: 16
  commands: []                   # console commands, %player% = the player

owned-shard-commands: []

# Items shown in the preview menu. Empty = show the real rewards above.
preview:
  items: []
KeyMeaning
display-name, descriptionName and description lines (MiniMessage).
categoryUsed by the category button and sort mode. Default general.
icon.material, icon.custom-model-dataMenu icon.
gui-slotFixed menu slot, or -1 for automatic placement.
sort-priorityHigher numbers appear earlier in the default order.
hiddenKeep the kit out of /vkit until the player owns it.
chanceFirst-roll chance in percent. If left out, pity.base-chance from config.yml is used.
pity.increase, pity.capPer-kit pity. If left out, the defaults from config.yml are used.
cooldownTime between claims. Shorthand like 7d, 2h30m, 45s, 1d12h. An invalid value falls back to 7d and a warning is logged.
rewards.itemsItems given on a loss (once) and on every claim. Item keys: material, amount, name, lore, enchants (NAME: level), glint, custom-model-data. Items made in the editor are stored in a serialized form and load the same way.
rewards.commandsConsole commands run together with the items. %player% is replaced.
owned-shard-commandsConsole commands that replace a spare shard when the player already owns the kit.
preview.itemsItems for the preview menu. Empty shows the real contents.
lore.locked, lore.unlocked, lore.cooldownCustom menu lore for this kit only.
hologram, sequencesOverride the roll look and effects for this kit.

If a kit's items do not fit in the player's inventory, the rest drop at their feet and the player is told. Unknown materials or enchantments are skipped with a console warning.

A rare kit example

The bundled Royal kit uses chance: 5.0, pity: {increase: 2.5, cap: 50.0}, cooldown: "14d" and gives spare shards 32 bottles o' enchanting through owned-shard-commands.