All documentation
Documentation

mcVkits

Chance-based virtual kits with pity, a live roll animation and a full in-game editor.

v2.0.1 Paper 1.21.4+Java 21PlaceholderAPI (optional)

Quick start

  1. Drop mcVkits-2.0.1.jar in plugins/ and restart the server.
  2. Run /vkitadmin to open the editor. Create a kit, set its icon, chance, pity and cooldown, and drop its items in.
  3. Give a shard with /vkit give <player> <kit> [amount]. Use the same command in your store.
  4. Players right-click the shard to roll, then claim their kits from /vkit.
  5. Use /vkit test <kit> to watch the roll without changing anything.

#Installation and requirements

mcVkits adds chance-based virtual kits to a Paper server. Players use a shard item to roll for a kit. A win unlocks the kit forever and lets them claim it again on a cooldown. A loss still gives the kit once and raises their chance for next time.

RequirementDetails
ServerPaper 1.21.4 or newer
Java21 or newer
PlaceholderAPI (optional)Enables the %mcvkits_...% placeholders.
  1. Stop the server and put mcVkits-2.0.1.jar in plugins/.
  2. Start the server. mcVkits creates plugins/mcVkits/ with config.yml, messages.yml, animations.yml, a guis/ folder and a vkits/ folder with three example kits (Starter, Gladiator, Royal).
  3. Run /vkitadmin in game to open the editor.
Example kits come back only once

The three example kits are written only on the first install. If you delete them, they will not return.

Upgrading from 1.x

Replace the old jar. Kits, player data, config.yml and messages.yml stay. The old menu and animation files move to plugins/mcVkits/backups/1.x/ and the new ones take their place.

#Files and folders

Path in plugins/mcVkits/What it holds
config.ymlShard item, default pity, join reminder, anti-dupe, unlock broadcast, confirm menu, update checks.
vkits/<id>.ymlOne file per kit. The file name is the kit id. A kit can override the hologram and sequences.
guis/vkits.yml, guis/preview.yml, guis/confirm.ymlEvery menu, button and lore line.
animations.ymlThe roll hologram and the effect sequences.
messages.ymlAll chat text.
playerdata/<uuid>.ymlPlayer progress per kit.
shards.ymlThe anti-dupe record of how many shards each stack really has.

Text takes MiniMessage (<red>, <#B57CFF>, <gradient:...>) or legacy codes (&a, &#B57CFF). Do not mix the two in one line. Run /vkit reload to apply changes.

#How kits work

  1. You give a player a shard for a kit (/vkit give, for example from your store).
  2. The player right-clicks the shard. It is used up and a roll starts: a floating shard spins in front of them while a label flashes between the two outcomes.
  3. Win: the kit is unlocked forever. Nothing is handed out on the win itself. The kit can be claimed at once from /vkit, and then again each time the cooldown ends. A server-wide unlock announcement is sent if broadcast-unlock is on.
  4. Loss: the kit stays locked, but the player still receives the full kit contents once, and their chance for that kit goes up (pity).

The chance for each player and kit starts at the kit's base chance and goes up by the pity increase after every loss, up to the cap. Example from the config comments: base 25 percent, increase 5, cap 95 means that after 3 losses the player rolls at 40 percent.

Store friendly

Run /vkit give %player% starter as the delivery command in your store. If the buyer is offline, the shard is waiting for them when they join.

Shards

  • Shards stack. Giving 10 gives one stack of 10, and new shards join a stack the player already has.
  • The shard tooltip shows the holder's own current chance (%chance%) and updates after rolls, on join and when inventories open.
  • You can give up to 64 shards in one command.
  • If the player already owns the kit and the kit has owned-shard-commands, the shard is turned into those commands (right-click, or at once on /vkit give). If the kit has none, the player keeps the spare shard.
  • Only one roll can run at a time per player. A shard is used up only once its roll actually starts.
  • If a player logs out in the middle of a roll, the result is saved so pity is never lost.

Anti-dupe

Every shard stack has a hidden id, and the server records how many shards each stack really has. If the same id turns up twice in one inventory or on the cursor, every copy is removed, a copied shard cannot be used, and players with the alert permission are told.

anti-dupe:
  enabled: true
  alert-permission: mcvkits.admin

#The /vkit menu

/vkit opens the kit menu for players. Each kit shows as locked, ready to claim or on cooldown. Left-click a kit to claim it, right-click to preview what is inside. Timers count down live while the menu is open (refresh-ticks).

  • A profile head shows kits owned, kits ready and shards used.
  • Claim all claims every ready kit in one click.
  • A category button appears when kits use more than one category.
  • A sort button switches between Ready first, Default, Category, Best chance and Shortest cooldown. The default is set by sort.default.
  • Arrows appear when there is more than one page.
  • Hidden kits (hidden: true) are not shown until the player owns them.

The preview menu (right-click, or /vkit preview <kit>) shows what a kit gives, a status icon with the player's chance, cooldown and stats, and a Claim button when the kit is ready. Kits with no preview items show their real contents.

Menu lore placeholders

In guis/vkits.yml the lore of each state (locked, unlocked, cooldown) can use %kit% %chance% %base% %pity% %cap% %time% %cooldown% %rolls% %fails% %claims% %category% %chance_bar% %cooldown_bar%. Two lines expand into several: %description% (the kit's description: list) and %contents% (an automatic list of what the kit gives).

contents-line: "<color:#6E6589> - <color:#F3EEFF>%amount%x <color:#A69CC4>%item%"
contents-max-lines: 6
contents-more: "<color:#6E6589>   and %more% more..."

Menu size, border, sounds, button slots and the per-state icon overrides are also in this file. To give one kit its own lore, add a lore: section with locked:, unlocked: and cooldown: lists to its kit file.

#Building kits in game

/vkitadmin (alias /vka) opens the editor. It lists your kits with Create Kit, Reload All, Close and page buttons. Create Kit asks for the new kit id in chat. Click a kit to edit it. Everything you change is written to the kit's file.

ButtonWhat it edits
Display Name, Category, DescriptionHow the kit is named and grouped in menus.
Set IconThe kit's menu icon. Hold an item and use the button to set it.
Base Chance, Pity Increase, Pity Cap, CooldownThe odds and claim timer. Cooldown uses shorthand such as 3d or 2h30m.
Lore: Locked, Unlocked, CooldownCustom menu lore for this kit only.
Kit ContentsDrop the real items the kit gives. Items keep their enchantments, names and lore.
Preview ItemsWhat the preview menu shows. Leave empty to show the real contents.
Kit CommandsConsole commands run when the kit is given. %player% is the player's name.
Owned-Shard CommandsCommands that replace a shard when the player already owns the kit.
Hologram Settings, Animation SequencesThe roll look and effects for this kit only.
HiddenToggles whether the kit is hidden until owned.
Test RollPlays the roll. Left-click for a win, right-click for a loss. Nothing is saved.
Give Me a ShardGives you one shard for this kit.
Delete KitAsks for confirmation, then deletes the kit.

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

#The roll animation

animations.yml controls the floating shard (hologram:) and the effects played at each moment (sequences:). Copy any key into a kit file's own hologram: or sequences: section to change it for that kit only (the bundled Royal kit sets its own item, label and glow color this way).

The hologram

hologram:
  # Item shown floating in front of the player.
  item: AMETHYST_SHARD
  custom-model-data: -1
  scale: 0.9
  follow-distance: 2.5
  vertical-offset: 0.3
  spin: true
  spin-speed: 8.0               # degrees per tick

  # How long the roll takes before the result (20 ticks = 1 second).
  suspense-ticks: 80

  label-success: "<bold><gradient:#5EEAD4:#B57CFF>UNLOCKED FOREVER</gradient></bold>"
  label-fail: "<bold><gradient:#FF5C7A:#FFC857>ONE-TIME REWARD</gradient></bold>"
  # Line under the label. %chance% = the chance this roll used. "" = none.
  info-line: "<color:#A69CC4>Chance <color:#F3EEFF>%chance%%"
  flicker-start-interval: 6.0
  flicker-end-interval: 1.0

  glow: true
  glow-color-success: "#5EEAD4"
  glow-color-fail: "#FF5C7A"
  progress-bar: true

  land-scale-success: 1.4        # the shard grows on a win...
  land-scale-fail: 0.6           # ...and shrinks on a loss
  particle-burst: END_ROD        # NONE = no burst
  linger-ticks: 40               # how long the result stays up

The label flashes between the two outcomes faster and faster until the result lands. The file also has sound options (flicker-sound, land-sound-success, land-sound-fail) and progress bar styling.

Sequences

Each sequence is a list of steps. A step is { type: ..., delay: ..., ... }. The delay is in ticks after the step before it. Sequences: suspense (while the shard is in the air), success, fail, claim (claiming an owned kit) and pity (right after a loss).

Step typeParameters
PARTICLEpattern (SPIRAL, RING, BURST, HELIX, TRAIL_HOLOGRAM), particle, count, offset-x/y/z, speed, duration-ticks
SOUNDsound, volume, pitch
TITLEtitle, subtitle, fade-in, stay, fade-out
ACTIONBARmessage
MESSAGEmessage, broadcast: true|false
BOSSBARtext, color, duration, progress, fill: true (grows from empty to full)
FIREWORKshape (BALL, BALL_LARGE, STAR, BURST, CREEPER), color, fade, trail, flicker, power. For show only, never hurts anyone.
EFFECTeffect, duration, amplifier
LIGHTNINGA harmless flash at the shard.
COMMANDcommand, as: console|player
DELAYJust waits.

Text in steps can use %player%, %kit%, %chance% and %pity%. Sounds use vanilla ids with dots, like block.anvil.use. Colors are dye names (LIME) or hex (#5EEAD4).

A real step from the success sequence:

- { type: FIREWORK, delay: 4, shape: BALL_LARGE, color: "#B57CFF", fade: "#FF7AC6", trail: true, flicker: true, power: 1 }

Use /vkit test <kit> [success|fail] to watch a roll while you tune it. Nothing is saved or given.

#The shard item and pity defaults

The shard item and the default pity values are in config.yml:

pity:
  # Chance on the first roll (%).
  base-chance: 25.0
  # Added to that player's chance for the kit after each failed roll (%).
  increase: 5.0
  # The chance never goes above this (%). 100.0 = no cap.
  cap: 95.0

shard:
  material: AMETHYST_SHARD
  glint: true
  custom-model-data: -1
  name: "<gradient:#B57CFF:#FF7AC6><bold>%kit% Shard</bold></gradient>"
  lore:
    - "<color:#A69CC4>Roll for the %kit%<color:#A69CC4> vKit."
    - ""
    - "<color:#A69CC4>Your chance: <color:#FF7AC6><bold>%chance%%</bold>"

Shard placeholders are %kit%, %player% and %chance%. The lore in the file continues with the win and loss explanation; edit it freely. Use custom-model-data for a resource pack texture.

Other settings

# Announce to the whole server when a player unlocks a kit forever.
broadcast-unlock: true

# Your store link. Shown as a clickable link in the unlock broadcast (%store-url%).
store-url: "https://store.yourserver.net"

# Ask "are you sure?" before a shard is used. Look: guis/confirm.yml.
confirm-menu:
  enabled: false

join:
  # Ticks to wait before the messages below (20 ticks = 1 second).
  delay-ticks: 40
  # "You have 2 vKits ready to claim" with a clickable /vkit.
  ready-reminder: true
  • The unlock broadcast text is the broadcast-unlock list in messages.yml.
  • With confirm-menu.enabled: true, a confirmation menu shows the kit and the player's live chance before the shard is used.
  • Shards given while a player was offline are always handed over on join. There is nothing to turn on for that.
Set your store link

Change store-url to your real store address, or the unlock broadcast links to the placeholder.

#Commands

/vkit has the aliases /vk and /vkits. /vkitadmin has the alias /vka. Commands are registered through Paper's command system, so tab completion offers kit ids and player names, and only shows what you have permission for. Player arguments accept players who are offline but have joined before.

CommandWhat it doesPermission
/vkitOpen the kit menu. From the console it shows the help list.mcvkits.use
/vkit helpShow the commands you have permission for.
/vkit claim <kit>Claim an owned kit that is off cooldown.mcvkits.use
/vkit preview <kit>See what a kit gives. Hidden kits show as not found until owned.mcvkits.use
/vkit give <player> <kit> [amount]Give shards (1 to 64). Offline players get them when they join.mcvkits.give
/vkit giveall <kit> [amount]Give shards to everyone online (1 to 64 each).mcvkits.give
/vkit unlock <player> <kit>Grant a kit directly with no shard or roll. It is claimable at once.mcvkits.unlock
/vkit lock <player> <kit>Take a kit away and reset its progress, chance and cooldown.mcvkits.lock
/vkit info <player>Show a player's state, chance, rolls, misses, claims and waiting shards for every kit.mcvkits.admin
/vkit test <kit> [success|fail]Play the roll animation for yourself. Nothing is saved or given.mcvkits.admin
/vkit setchance <player> <kit> <value>Set a player's current chance for a kit (0 to 100).mcvkits.admin
/vkit resetpity <player> [kit]Set the chance back to the kit's base chance, for one kit or all.mcvkits.resetpity
/vkit resetcooldown <player> [kit]Clear claim cooldowns, for one kit or all.mcvkits.resetcooldown
/vkit reloadReload config, messages, menus, animations and all kit files.mcvkits.reload
/vkitadminOpen the in-game kit editor (players only).mcvkits.admin

#Permissions

Players only need mcvkits.use, which is on by default. Everything else is for operators by default.

PermissionWhat it allowsDefault
mcvkits.useOpen /vkit, claim owned kits, preview kits and use shards.true
mcvkits.giveUse /vkit give and /vkit giveall.op
mcvkits.reloadUse /vkit reload.op
mcvkits.unlockUse /vkit unlock.op
mcvkits.lockUse /vkit lock.op
mcvkits.resetcooldownUse /vkit resetcooldown.op
mcvkits.resetpityUse /vkit resetpity.op
mcvkits.adminUse /vkitadmin, /vkit info, /vkit test and /vkit setchance. Also receives anti-dupe alerts and update notices.op

#Placeholders

Needs PlaceholderAPI. The expansion registers automatically and survives /papi reload. Unknown kits give false, 0 or empty text, never an error. <kit> is the kit id.

PlaceholderValue
%mcvkits_owned_<kit>%true or false: the player owns the kit.
%mcvkits_ready_<kit>%true when the kit is owned and off cooldown.
%mcvkits_chance_<kit>%The player's current chance, like 42.5.
%mcvkits_cooldown_<kit>%Time left, or the text of placeholder-ready in messages.yml (Ready by default).
%mcvkits_rolls_<kit>%How many shards the player used on the kit.
%mcvkits_fails_<kit>%How many rolls on the kit were losses.
%mcvkits_claims_<kit>%How many times the player claimed the kit.
%mcvkits_name_<kit>%The kit's display name (raw MiniMessage text).
%mcvkits_owned_count%How many kits the player owns.
%mcvkits_ready_count%How many kits the player can claim right now.
%mcvkits_total%How many kits exist.
%mcvkits_rolls_total%Total rolls the player has made.

#Troubleshooting and FAQ

Players cannot use /vkit

They need mcvkits.use, which is on by default. If your permissions plugin removes it, add it back.

A shard does nothing when right-clicked

Only one roll runs at a time per player, so wait for the current one to end. If the player already owns the kit and the kit has no owned-shard-commands, they are told it is already unlocked and keep the shard. A shard that was copied is removed and reported to admins by the anti-dupe system.

A win gave no items

That is how it works. A win unlocks the kit and the player claims the items from /vkit (the first claim is available at once). Only a loss gives the contents straight away, once.

A player cannot claim a kit

Left-click an unlocked kit in /vkit, or run /vkit claim <kit>. If it says cooldown, wait, or clear it with /vkit resetcooldown <player> [kit].

I gave a shard to an offline player. Where is it?

It is queued and handed over the next time they join. It works for anyone who has joined the server before.

How do I make a player start with a better chance?

Run /vkit setchance <player> <kit> <value>. To go back to the base chance use /vkit resetpity.

I changed a kit file but nothing changed

Run /vkit reload. A kit with an invalid cooldown falls back to 7d, and unknown materials or enchantments are skipped with a warning in the console.

Items did not fit in the inventory

The remaining items are dropped at the player's feet and the player gets the inventory-full message.

The roll effects look different from my settings

A kit file can have its own hologram: and sequences: sections that override animations.yml for that kit. Check the kit file.

#Updating

Replace the jar in plugins/ with the new version and restart. Kits, player data and your settings are kept.

Update checker

updates:
  enabled: true
  check-on-startup: true
  check-interval-hours: 24
  # Downloads the new jar into plugins/update. It is installed on the next restart.
  # The current jar is copied to plugins/mcVkits/backup first.
  auto-download: false
  # Tells the console and players with mcvkits.admin.
  notify: true
  # Leave these as they are to use the built-in values.
  shared-token: ""
  resource-id: 0

mcVkits checks BuiltByBit on startup and once a day (copies downloaded from BuiltByBit only) and tells the console and players with mcvkits.admin. Only the check itself is sent. With auto-download: true the new jar is downloaded into plugins/update and installed on the next restart, after a backup of the current jar to plugins/mcVkits/backup. Every download is checked before use: it must be a valid mcVkits jar of the right version.