Kits
Item sets, cooldowns, usage limits and giving kits to other players.
Commands 7#
Examples#
Build a starter kit from your inventory#
You need a set that a new player claims once a day, without editing files by hand.
/createkit starter "Starter Kit" 86400 Bread and a sword for the first day
/showkit starter
/kit starter
createkit takes copies of the items in the main inventory (slots 0…size-5: no armor or offhand); an empty inventory gives "empty_inventory". Chat shows created/updated, the item count, the cooldown and a hint with the neoessentials.kits.starter permission. showkit prints the displayName, description, "24h" and lines of count + item name. /kit starter gives the items to you and prints given; if there is no room, the excess drops at your feet.
Give a kit to another player and reset the limit#
A player hit the cooldown or maxUses — you need to give the kit now and let them claim it again.
/kit starter Steve
/kitreset starter Steve
The first command requires neoessentials.kit.others; Steve must be online, otherwise "player not found". Cooldown and maxUses are checked on Steve, the kit permission on you. Steve gets "received_from". kitreset clears both the timer and the usage counter (without it maxUses would keep blocking the kit) and sends Steve a notify.
Browse the catalogue and delete a kit#
Before deleting, make sure the kit contains what you think and do not wipe it with a single typo.
/listkits
/listkits 2
/delkit starter
/delkit starter confirm
listkits without an argument is page 1, 10 entries each: name, displayName, item count, cooldown if > 0. A non-existent page gives the invalid_page error. The first delkit deletes nothing, only confirm_prompt + instructions. The second removes the record from the kits DataStore collection; a repeated /kit starter gives not_found.
Edge cases#
Kit definitions live in the DataStore; kits.json is dead after import#
KitManager stores kits in the kits collection of the active storage.type (JSON in neoessentials/store/ by default), cooldowns in kit_cooldowns, counters in kit_usages. The shipped config/neoessentials/kits.json is read once: only if all three collections are empty and storage.autoMigrate is on. After that the file is neither written nor re-read — edits to it are visible neither in /kit nor after /neoe reload. /neoe reload calls KitManager.reload() and re-reads the DataStore, not kits.json.
What to do: New kits — /createkit, deletion — /delkit … confirm. /createkit does not set the commands field or maxUses: edit them in the record of the kits collection (or keep the defaults: maxUses −1, commands empty).
Commands on claim exist, but /createkit does not write them#
The English wiki claims kits are "items only". In code Kit has a commands array: after the items are given successfully, runKitCommands runs each line from the console with {player} substituted (a leading / is stripped). /createkit always creates a kit with an empty array and maxUses: -1. The template in kits.json does show commands: ["say Welcome…"] — that reaches the DataStore only on that very first import.
What to do: Add the console command you need to the kit's JSON record in storage and run /neoe reload. Commands cannot be added through /createkit.
skipUsedOneTimeKitsFromKitList also hides "unlimited" kits#
canUseKit treats maxUses > 0 as a limit and −1 as unlimited. The /listkits filter with kits.skipUsedOneTimeKitsFromKitList: true hides a kit if maxUses == 1 or maxUses < 0 and the player has claimed it at least once. /createkit writes exactly maxUses: -1. Result: the kit can still be claimed with /kit <name>, but disappears from /kits//listkits after the first claim.
What to do: For a one-time kit, set maxUses: 1 in the record. Better not to enable the list filter until kits made with /createkit have an explicit maxUses.
/kit and /kits are different commands with different permissions#
/kit needs neoessentials.kits.use plus the per-kit neoessentials.kits.<name> (or the record's permission field). /kits//listkits need neoessentials.kits.list. Without neoessentials.kits.override (and kits.allowKitOverride enabled), /listkits shows the same kits as /kit completion, not "all kits on the server". neoessentials.kits.nocooldown and neoessentials.kits.<name>.nocooldown bypass only the cooldown; override also bypasses enabled/maxUses/maxKitsPerPlayer. The console does not check the per-kit permission in /kit.
What to do: Give players kits.use + the kits.<name> they need. For staff to see all kits — kits.list together with kits.override.
Kit name and contents at creation#
The Kit constructor keeps only lower-case [a-z0-9_] in the name. /createkit rejects a hyphen up front (otherwise vip-kit would silently become vipkit and not match what was typed). Armor and the offhand do not go into the kit: the loop is 0 … containerSize-5. Repeating /createkit with the same name updates the items, displayName, cooldown and description, but does not keep the existing record's commands/maxUses — createKit builds a new object with empty commands and −1.
What to do: Do not use hyphens in ids. For armor, put it in the main inventory before /createkit. When updating a kit via the command, re-enter commands/maxUses in storage if they were set.
pastebinCreatekit does not save the kit#
With kits.pastebinCreatekit: true, /createkit does not call kitManager.createKit. Instead it serializes JSON and returns a URL like https://pastebin.com/mock/<hash> — there is no upload to Pastebin in the code. The kit does not appear on the server.
What to do: Keep pastebinCreatekit at false (the default). To export, copy the record from the kits collection.
Online targets only, prices and newPlayerKit#
/kit <name> <player> and /kitreset <kit> <player> look the player up via getPlayerByName — offline players are not found and there is no queue. kits.commandCosts.<command> is charged to the sender before the kit is given (kit, createkit, listkits, delkit on confirm). kits.newPlayerKit.enabled + kitName give a kit on first join; a kit with that name may not exist at join time — this is a separate path, not /kit.
What to do: Give offline players their kit when they join. Check prices if the economy is enabled. The name in newPlayerKit.kitName must match the kit id after sanitization.
Known issues#
kits.pastebinCreatekit returns a fake URL and does not create the kit#
uploadToPastebin in CreateKitCommand is a stub: it always returns https://pastebin.com/mock/…, with no HTTP call. With the flag on, the branch that saves to the DataStore is skipped entirely, so /kit does not see this kit.
What to do: Keep kits.pastebinCreatekit: false. If you need the JSON, take it from the kits collection in storage.
Configuration#
kits.json#
Permissions 8#
Detailed guide#
The section below is the project's original documentation (docs/Wiki/KitManagement.md). Links to other wiki pages are rewritten to this site; the guides themselves are not edited, so upstream syncs stay conflict-free.
Version: 1.0.5+build.54 · Last verified: 2026-08-25 · Config: config.json → kits section (kit definitions themselves live in the DataStore, not kits.json — see below)
Overview#
Create item kits with cooldowns, permission gates, and command execution on claim. Players can preview kits before claiming. Staff can give kits to other players and reset cooldowns.
Commands#
| Command |
Syntax |
Permission |
Description |
/kit |
/kit |
neoessentials.kits.use |
List kits available to you, with cooldown status |
/kit |
/kit <name> [player] |
per-kit permission (see below) + neoessentials.kit.others to target another player |
Claim a kit (or give to another player) |
/kits, /listkits |
/kits [page] |
neoessentials.kits.list |
Admin overview: paginated list of all kits with item counts, cooldowns, permissions, and descriptions — not an alias of /kit |
/showkit |
/showkit <name>[,<name2>,...] |
neoessentials.showkit |
Preview one or more kits' contents without claiming |
/createkit |
/createkit <name> [displayname] [cooldownSeconds] [description] |
neoessentials.kits.create |
Create/update a kit from your current inventory (main inventory only; armor/offhand excluded) |
/makekit, /addkit |
alias |
same |
Aliases |
/delkit |
/delkit <name> then /delkit <name> confirm |
neoessentials.kits.delete |
Delete a kit (two-step confirmation) |
/deletekit, /removekit, /rkit |
alias |
same |
Aliases |
/kitreset |
/kitreset <kit> [player] |
neoessentials.kitreset / neoessentials.kitreset.others |
Reset a kit cooldown |
Note: /kit, /kits//listkits, and /showkit are three distinct commands with different permissions and purposes — /kit is for claiming, /kits//listkits is an admin-facing overview of every kit, and /showkit previews a specific kit's contents.
There is no built-in support for running server commands on kit claim — kits only grant items.
Permissions#
| Node |
Default |
Description |
neoessentials.kits.use |
✅ |
Use /kit to list/claim kits |
neoessentials.kits.list |
✅ |
Use /kits//listkits (admin overview) |
neoessentials.kit.others |
🔒 |
Give a kit to another player via /kit <name> <player> |
neoessentials.kits.create |
🔒 |
Create kits with /createkit |
neoessentials.kits.delete |
🔒 |
Delete kits with /delkit |
neoessentials.kits.override |
🔒 |
Bypass all kit cooldowns/restrictions (requires allowKitOverride also enabled) |
neoessentials.kits.nocooldown |
🔒 |
Bypass cooldowns only (kept even if allowKitOverride is off) |
neoessentials.showkit |
✅ |
Preview kit contents with /showkit |
neoessentials.kitreset |
🔒 |
Reset your own kit cooldown |
neoessentials.kitreset.others |
🔒 |
Reset another player's cooldown |
neoessentials.kits.<name> |
auto-registered per kit |
Default per-kit permission, required to see/claim that kit |
neoessentials.kits.<name>.nocooldown |
🔒 |
Bypass cooldown for one specific kit |
Kit definitions are persisted through the pluggable DataStore backend (JSON by default — see
Storage Backend), one record per kit under the kits collection — not a single
kits.json file anymore. Each record has this shape (shown here as JSON for reference; edit kits
via /createkit//delkit rather than hand-editing storage files):
{
"name": "starter",
"displayName": "Starter Kit",
"description": "Given to new players",
"cooldownMillis": 86400000,
"permission": "neoessentials.kits.starter",
"maxUses": -1,
"enabled": true,
"items": [
{ "item": "minecraft:stone_sword", "count": 1, "components": {} },
{ "item": "minecraft:bread", "count": 16 }
]
}
| Field |
Description |
name |
Kit name (used in /kit <name>) |
displayName |
Human-readable name shown in messages/previews (defaults to name) |
description |
Shown by /showkit and /kits (defaults to empty) |
cooldownMillis |
Milliseconds between claims (0 = no cooldown). A legacy cooldown field (in seconds) is still read for backward compatibility if cooldownMillis is absent |
permission |
Permission required to see/claim the kit; defaults to neoessentials.kits.<name> if omitted |
maxUses |
Max claims per player (-1 = unlimited); /listkits's skipUsedOneTimeKitsFromKitList treats maxUses == 1 (or a negative legacy value) as "one-time" |
enabled |
Whether the kit is currently claimable (defaults to true) |
items |
List of items — item (registry ID), count, and either components (preferred — the item's full DataComponentMap: enchantments, custom name, dyed color, etc.) or a legacy nbt string (CUSTOM_DATA only, from kits saved before components support was added) |
There is no commands field — kits only grant items, they do not run server commands on claim.
Legacy file: config/neoessentials/kits.json is the pre-DataStore on-disk format. It's
only read once, automatically, to migrate its contents into the DataStore kits collection —
never written to again afterward. If it still exists alongside DataStore data, editing it has
no effect; /neoe startup logs (and isLegacyKitsFileNowInert()) flag this case.
Config (config.json → kits)#
| Key |
Default |
Description |
skipUsedOneTimeKitsFromKitList |
false |
Hide one-time kits from /listkits once claimed |
kitAutoEquip |
false |
Auto-equip armour from kits into empty armour slots |
maxKitsPerPlayer |
10 |
Max simultaneous active cooldowns (-1/any non-positive = unlimited) |
allowKitOverride |
true |
Allow neoessentials.kits.override bypass |
newPlayerKit.enabled |
false |
Enable/disable giving a kit automatically on first join (nested under kits.newPlayerKit, not a flat key) |
newPlayerKit.kitName |
(none) |
Kit name to auto-give on first join when newPlayerKit.enabled is true (nested under kits.newPlayerKit, not a flat key) |
logKitUsage |
true |
Log kit claims to console |
pastebinCreatekit |
false |
If enabled, /createkit uploads the kit JSON instead of saving it locally |
commandCosts.<command> |
0 |
Economy cost to run a given kit command (e.g. createkit, kit, delkit, listkits) |
/showkit has no dedicated config toggle — it's always available to anyone with neoessentials.showkit.
How Cooldowns Work#
- Cooldown starts the moment a kit is successfully claimed
- Staff with
neoessentials.kits.override bypass everything (requires allowKitOverride: true); neoessentials.kits.nocooldown (or the per-kit neoessentials.kits.<name>.nocooldown) bypasses just the cooldown
/kitreset <kit> clears a specific cooldown/kitreset <kit> <player> requires neoessentials.kitreset.others- A kit becomes permanently unclaimable for a player once
maxUses is reached (there's no -1 "cooldown" sentinel — use maxUses: 1 for one-time kits)
Back to Wiki Home
