#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.
| Requirement | Details |
|---|---|
| Server | Paper 1.21.4 or newer |
| Java | 21 or newer |
| PlaceholderAPI (optional) | Enables the %mcvkits_...% placeholders. |
- Stop the server and put
mcVkits-2.0.1.jarinplugins/. - Start the server. mcVkits creates
plugins/mcVkits/withconfig.yml,messages.yml,animations.yml, aguis/folder and avkits/folder with three example kits (Starter, Gladiator, Royal). - Run
/vkitadminin game to open the editor.
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.yml | Shard item, default pity, join reminder, anti-dupe, unlock broadcast, confirm menu, update checks. |
vkits/<id>.yml | One 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.yml | Every menu, button and lore line. |
animations.yml | The roll hologram and the effect sequences. |
messages.yml | All chat text. |
playerdata/<uuid>.yml | Player progress per kit. |
shards.yml | The 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
- You give a player a shard for a kit (
/vkit give, for example from your store). - 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.
- 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 ifbroadcast-unlockis on. - 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.
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
#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.
| Button | What it edits |
|---|---|
| Display Name, Category, Description | How the kit is named and grouped in menus. |
| Set Icon | The kit's menu icon. Hold an item and use the button to set it. |
| Base Chance, Pity Increase, Pity Cap, Cooldown | The odds and claim timer. Cooldown uses shorthand such as 3d or 2h30m. |
| Lore: Locked, Unlocked, Cooldown | Custom menu lore for this kit only. |
| Kit Contents | Drop the real items the kit gives. Items keep their enchantments, names and lore. |
| Preview Items | What the preview menu shows. Leave empty to show the real contents. |
| Kit Commands | Console commands run when the kit is given. %player% is the player's name. |
| Owned-Shard Commands | Commands that replace a shard when the player already owns the kit. |
| Hologram Settings, Animation Sequences | The roll look and effects for this kit only. |
| Hidden | Toggles whether the kit is hidden until owned. |
| Test Roll | Plays the roll. Left-click for a win, right-click for a loss. Nothing is saved. |
| Give Me a Shard | Gives you one shard for this kit. |
| Delete Kit | Asks 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: []
| Key | Meaning |
|---|---|
display-name, description | Name and description lines (MiniMessage). |
category | Used by the category button and sort mode. Default general. |
icon.material, icon.custom-model-data | Menu icon. |
gui-slot | Fixed menu slot, or -1 for automatic placement. |
sort-priority | Higher numbers appear earlier in the default order. |
hidden | Keep the kit out of /vkit until the player owns it. |
chance | First-roll chance in percent. If left out, pity.base-chance from config.yml is used. |
pity.increase, pity.cap | Per-kit pity. If left out, the defaults from config.yml are used. |
cooldown | Time between claims. Shorthand like 7d, 2h30m, 45s, 1d12h. An invalid value falls back to 7d and a warning is logged. |
rewards.items | Items 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.commands | Console commands run together with the items. %player% is replaced. |
owned-shard-commands | Console commands that replace a spare shard when the player already owns the kit. |
preview.items | Items for the preview menu. Empty shows the real contents. |
lore.locked, lore.unlocked, lore.cooldown | Custom menu lore for this kit only. |
hologram, sequences | Override 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.
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 type | Parameters |
|---|---|
PARTICLE | pattern (SPIRAL, RING, BURST, HELIX, TRAIL_HOLOGRAM), particle, count, offset-x/y/z, speed, duration-ticks |
SOUND | sound, volume, pitch |
TITLE | title, subtitle, fade-in, stay, fade-out |
ACTIONBAR | message |
MESSAGE | message, broadcast: true|false |
BOSSBAR | text, color, duration, progress, fill: true (grows from empty to full) |
FIREWORK | shape (BALL, BALL_LARGE, STAR, BURST, CREEPER), color, fade, trail, flicker, power. For show only, never hurts anyone. |
EFFECT | effect, duration, amplifier |
LIGHTNING | A harmless flash at the shard. |
COMMAND | command, as: console|player |
DELAY | Just 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-unlocklist inmessages.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.
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.
| Command | What it does | Permission |
|---|---|---|
| /vkit | Open the kit menu. From the console it shows the help list. | mcvkits.use |
| /vkit help | Show 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 reload | Reload config, messages, menus, animations and all kit files. | mcvkits.reload |
| /vkitadmin | Open 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.
| Permission | What it allows | Default |
|---|---|---|
| mcvkits.use | Open /vkit, claim owned kits, preview kits and use shards. | true |
| mcvkits.give | Use /vkit give and /vkit giveall. | op |
| mcvkits.reload | Use /vkit reload. | op |
| mcvkits.unlock | Use /vkit unlock. | op |
| mcvkits.lock | Use /vkit lock. | op |
| mcvkits.resetcooldown | Use /vkit resetcooldown. | op |
| mcvkits.resetpity | Use /vkit resetpity. | op |
| mcvkits.admin | Use /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.
| Placeholder | Value |
|---|---|
| %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.