UltiKits - Kit System

UltiKits is the kit/gift package management module for UltiTools, allowing you to create, manage, and distribute item kits to players.

Feature Overview

UltiKits provides a full-featured kit system. Admins can quickly create kits in-game from their inventory or use a visual editor to modify kit contents. Players browse available kits through a paginated GUI and claim them with a click. Each kit supports independent pricing (requires Vault economy plugin), level requirements, permission nodes, cooldown timers, and one-time claim restrictions. Kits can also trigger player commands and console commands on claim. Kit configurations are stored as individual YAML files for easy management.

Installation

Method 1: Via UPM (Recommended)

Run in-game or from the console:

/upm install UltiKits

Method 2: Manual Installation

1. Download the UltiKits JAR file
2. Place the JAR file in the plugins/UltiTools/plugins/ directory
3. Restart the server

Quick Start

After installation, follow these steps to create your first kit:

1. Prepare items - Place the items you want in the kit into your inventory
2. Create the kit - Run /kits create starter to save all items in your inventory as a kit named starter
3. Browse kits - Run /kits to open the GUI browser and see the kit you just created
4. Claim a kit - Click the kit icon in the GUI, or run /kits claim starter
5. Edit a kit - Run /kits edit starter to open the visual editor where you can drag and drop items

On first run, the plugin automatically generates an example kit configuration file called starter that you can use as a reference.

Commands

Command	Description	Who Can Run	Example
/kits	Open the kit browser GUI	Player only	/kits
/kits claim <name>	Claim a specific kit	Player only	/kits claim starter
/kits list	List all available kits	Player / Console	/kits list
/kits create <name>	Create a kit from current inventory	Player only	/kits create vip
/kits edit <name>	Open the kit content editor	Player only	/kits edit starter
/kits delete <name>	Delete a kit	Player / Console	/kits delete oldkit
/kits reload	Reload all kit configurations	Player / Console	/kits reload

Command aliases: both /kit and /kits work.

Permissions

Permission	Description	Default
ultikits.kits.use	Basic access: browse GUI, claim kits, list kits	All players
ultikits.kits.admin	Admin access: create, edit, delete, reload kits	OP only

Additionally, each kit can have its own custom permission node (see the permission field in kit configuration).

Configuration

Main Configuration File

File path: plugins/UltiTools/UltiKits/config/config.yml

# Enable the kit system
enabled: true

# GUI click debounce in milliseconds (prevents duplicate claims from rapid clicking)
# Range: 50-5000
click_cooldown_ms: 200

# Number of kits displayed per page in the browser GUI
# Range: 7-28
kits_per_page: 28

Kit Configuration Files

Each kit has its own YAML file stored in plugins/UltiTools/UltiKits/kits/. The filename (lowercase) becomes the kit name.

Below is the complete bundled example file kits/starter.yml:

# Kit display name (supports color codes)
displayName: "&aStarter Kit"

# Description lines (displayed as lore on the GUI icon)
description:
  - "&7A starter pack for new players"
  - "&7Contains basic gear and tools"

# GUI display icon material (Bukkit Material enum name)
icon: GRASS_BLOCK

# Cost to claim (0 = free, requires Vault economy plugin)
price: 0

# Minimum player level required (0 = no requirement)
levelRequired: 0

# Required permission node (empty string = no requirement)
permission: ""

# Can be claimed multiple times (false = one-time kit)
reBuyable: false

# Cooldown in seconds between claims (only applies when reBuyable is true)
cooldown: 0

# Commands executed as the player on claim (supports {player} placeholder)
playerCommands: []

# Commands executed as console on claim (supports {player} placeholder)
consoleCommands: []

# Serialized item data (auto-generated by /kits create or /kits edit, do not modify manually)
items: ""

Usage Tutorials

Creating a Paid VIP Kit

Suppose you want to create a VIP kit that costs 500 in-game currency and requires VIP permission:

1. Place diamond sword, diamond armor, etc. in your inventory
2. Run /kits create vip
3. Edit the config file plugins/UltiTools/UltiKits/kits/vip.yml:

displayName: "&b&lVIP Exclusive Kit"
description:
  - "&7Exclusive items for VIP players"
  - "&eIncludes full diamond gear"
icon: DIAMOND_SWORD
price: 500
levelRequired: 0
permission: "ultikits.kit.vip"
reBuyable: false
cooldown: 0
playerCommands: []
consoleCommands:
  - "broadcast &a{player} claimed the VIP Kit!"
items: "..."  # Auto-generated by /kits create

4. Run /kits reload to apply changes
5. Grant VIP players the ultikits.kit.vip permission

Creating a Daily Kit

A free kit that can be claimed once every 24 hours:

displayName: "&e&lDaily Reward"
description:
  - "&7Claim once per day"
  - "&aFree"
icon: CAKE
price: 0
levelRequired: 0
permission: ""
reBuyable: true
cooldown: 86400  # 24 hours = 86400 seconds
playerCommands: []
consoleCommands: []
items: "..."

Creating a Kit with Command Rewards

A kit that also runs commands on claim (e.g., giving XP):

displayName: "&d&lReward Kit"
description:
  - "&7Grants bonus rewards on claim"
icon: EXPERIENCE_BOTTLE
price: 100
levelRequired: 10
permission: ""
reBuyable: true
cooldown: 3600  # 1 hour
playerCommands:
  - "me claimed the Reward Kit"
consoleCommands:
  - "xp give {player} 100"
  - "broadcast &e{player} claimed the Reward Kit"
items: "..."

Using the GUI Editor

1. Run /kits edit starter to open a 6-row chest interface
2. The first 5 rows (45 slots) are the item area -- drag and drop items freely
3. The bottom row contains controls:
   • Emerald - Save
   • Book - Kit info display
   • Barrier - Cancel and close
4. Arrange items as desired, then click the emerald to save

FAQ

What if the plugin doesn't work after installation?

Check the following:

• The JAR file is in plugins/UltiTools/plugins/ (not the plugins/ root directory)
• The server has been fully restarted (not just /reload)
• There are no errors in the console
• UltiTools-API version is >= 6.2.0

Config changes not taking effect?

After modifying kit YAML files, run /kits reload to reload them. After modifying the main config.yml, run /ul reload or restart the server.

How to set up permissions?

1. The basic permission ultikits.kits.use is granted to all players by default
2. Admin permission ultikits.kits.admin is OP-only by default
3. Individual kit permissions are set in each kit's permission field -- leave it empty for unrestricted access
4. Use a permissions plugin (e.g., LuckPerms) to assign permissions to players or groups

Economy system not working?

UltiKits pricing requires Vault and an economy plugin (e.g., EssentialsX, CMI). Make sure:

• Vault is installed on the server
• At least one Vault-compatible economy plugin is installed
• The kit's price field is set to a value greater than 0

How do I create a kit if my inventory is empty?

The /kits create command reads non-empty items from your current inventory. If your inventory is completely empty, it will show an "Inventory is empty" error. Place the desired items in your inventory first, then run the command. Alternatively, create a kit first, then use /kits edit <name> to open the editor and place items directly.

How to set up cooldown timers?

1. Set reBuyable to true (allow repeated claims)
2. Set cooldown to the number of seconds, for example:
   • cooldown: 3600 for 1 hour
   • cooldown: 86400 for 1 day
   • cooldown: 604800 for 1 week
3. If reBuyable is false, the kit can only be claimed once and the cooldown setting has no effect

Changelog

v1.0.0 (2026-02-13)

Added: Kit system core features

• Added: Paginated GUI browser for viewing all available kits
• Added: GUI editor for admins to drag-and-drop edit kit contents
• Added: /kits create command to quickly create kits from current inventory
• Added: /kits claim command and GUI click-to-claim
• Added: /kits list command to list all kits
• Added: /kits edit command to open the visual editor
• Added: /kits delete command to remove kits
• Added: /kits reload command to reload configurations
• Added: Vault economy integration for kit pricing
• Added: Per-kit cooldown timers
• Added: One-time kits (non-repeatable)
• Added: Player level requirements
• Added: Per-kit permission nodes
• Added: Player and console commands on claim (with {player} placeholder)
• Added: YAML configuration with one file per kit
• Added: Base64 item serialization for storage
• Added: Chinese and English language support

Contributors

Ling Bao

Claude Opus 4.6

Changelog

Last edited 16 minutes ago

View full history

5c9d900-chore: upgrade VitePress to 1.6+ with modern plugin ecosystem