** 🎮 UltraStarterKits - Complete Plugin Documentation

🌟 Overview

UltraStarterKits is a premium, enterprise-grade kit management plugin designed for Minecraft 1.21.x servers running Paper or Spigot. It provides a complete solution for managing player kits with an intuitive GUI, powerful permission system, and extensive customization options.

🎯 What Makes It Ultimate?

Production-Ready: Battle-tested code with error handling and optimization
Network-Compatible: Full MySQL support for BungeeCord/Velocity networks
Highly Customizable: Every message, GUI, and feature is configurable
Performance-Optimized: Async operations, connection pooling, smart caching
Developer-Friendly: Clean code architecture and comprehensive API

🏆 Perfect For

Survival Servers - Starter kits, daily rewards, rank perks
Skyblock Networks - Island starter packs, VIP kits, monthly rewards
Prison Servers - Rank-based kits, mine rewards, progression systems
PvP Servers - Arena kits, loadouts, quick gear access
Minigame Networks - Game-specific kits, team loadouts

✨ Key Features

🎁 Kit Management

Feature	Description
Unlimited Kits	Create as many custom kits as needed
Full NBT Support	Preserves all item data including custom model data, names, lore, enchantments
Item Serialization	Base64 encoding ensures 100% item data preservation
Random Items	Chance-based loot system (e.g., 50% chance for rare items)
Kit Categories	Organize kits into categories (Basic, Premium, Daily, PvP, etc.)
Kit Expiry	Time-limited kits that expire on specific dates
Scheduled Availability	Weekend-only kits, time-of-day restrictions

🔐 Permission & Access Control

Feature	Description
LuckPerms Integration	Direct API integration (not just Vault)
Per-Kit Permissions	Individual permission nodes per kit
Rank-Based Overrides	Different cooldowns/uses for different ranks
Group Detection	Checks both primary and inherited groups
Display Names	Show "VIP" instead of "kit.use.vip"
Bypass Permissions	Admin permissions to bypass all restrictions

⏱️ Cooldown System

Feature	Description
Flexible Time Format	Support for seconds, minutes, hours, days, weeks
Rank Overrides	VIPs get 12h cooldown, MVPs get 6h, etc.
Cooldown Tracking	Persistent cooldown storage across restarts
Expiry Notifications	Optional notifications when cooldowns expire
Display Formats	Full (1d 2h 30m), Short (1d 2h), Seconds (95400)
No Cooldown Option	Use "never" or -1 for instant re-claim

🎫 Usage Limits

Feature	Description
Limited Uses	1-time, 5-time, 100-time kits
Unlimited Uses	Infinite re-claims with cooldown
Rank-Based Limits	Different use counts per rank
Use Tracking	Persistent storage of claim counts
Use Reset	Admin command to reset usage data

🌍 World Management

Feature	Description
Global Whitelist	Restrict plugin to specific worlds
Per-Kit Worlds	Kit only works in designated worlds
Multi-World Support	Different kits for different worlds
World Change Detection	Auto-give starter kits on world entry
Bypass Permission	Admins can use kits anywhere

🎮 GUI System

Feature	Description
Main Kit Menu	Beautiful paginated kit selection GUI
Preview Mode	100% secure view-only kit preview
Locked Kit Display	Shows unavailable kits with requirements
Clickable Store Links	MiniMessage-powered clickable URLs
Admin Edit GUI	Visual drag-and-drop kit editor
Confirmation Dialogs	Deletion confirmations with warnings
Pagination	Auto-pagination for 30+ kits
Custom Icons	Per-kit custom materials and model data
Glowing Icons	Optional enchantment glow effect
Dynamic Lore	Real-time cooldown/uses display

💾 Storage Options

Type	Use Case	Pros	Cons
YAML	Single servers	Easy setup, human-readable	Not network-compatible
SQLite	Small-medium servers	No external DB needed, fast	Not network-compatible
MySQL	Networks, large servers	Network sync, scalable	Requires MySQL server

🔌 Integrations

Plugin	Integration Level	Features
LuckPerms	⭐⭐⭐⭐⭐ Deep	Groups, permissions, prefixes, suffixes, rank detection
Vault	⭐⭐⭐⭐ Full	Economy costs, permission fallback
PlaceholderAPI	⭐⭐⭐⭐⭐ Deep	15+ custom placeholders
bStats	⭐⭐⭐ Standard	Anonymous usage metrics

🎨 Effects & Feedback

Effect Type	Customizable	Per-Kit
Sounds	✅ Yes	✅ Yes
Particles	✅ Yes	✅ Yes
Titles	✅ Yes	✅ Yes
Subtitles	✅ Yes	✅ Yes
Action Bar	✅ Yes	✅ Yes
Chat Messages	✅ Yes	✅ Yes
Broadcasts	✅ Yes	✅ Yes
Fireworks	✅ Yes	✅ Yes

🚀 Advanced Features

Feature	Description
Starter Kits	Auto-give on first join per world
Economy Costs	Charge money for kit claims (Vault)
XP Requirements	Require XP levels to claim
Item Requirements	Consume items to claim kit
Command Execution	Run commands on kit claim (console/player/op)
One-Time Bonuses	Extra items on first claim only
Auto-Save	Configurable auto-save intervals
Cache System	Smart caching for performance
Async Operations	Non-blocking database operations
Connection Pooling	HikariCP for MySQL optimization

🔧 Technical Specifications

System Requirements

Minecraft Version: 1.21+
Server Software: Paper (recommended) or Spigot
Java Version: 17 or higher
RAM: Minimum 512MB allocated to plugin operations
Database: MySQL 5.7+ or MariaDB 10.3+ (optional)

Dependencies

Required:
  - None (fully standalone)

Soft Dependencies (Optional):
  - LuckPerms 5.4+ (for advanced permissions)
  - Vault 1.7+ (for economy features)
  - PlaceholderAPI 2.11+ (for placeholders)

Performance Metrics

Average RAM Usage: 20-50MB (depends on kit count)
Database Queries: Fully async, non-blocking
Cache Expiry: 5 minutes (configurable)
GUI Render Time: <5ms
Kit Claim Time: <10ms
Startup Time: <1 second

📥 Installation Guide

Step 1: Download

Download UltraStarterKits

Step 2: Install

 Stop your server
stop

 Place JAR in plugins folder
cp UltraStarterKits-1.0.0.jar /path/to/server/plugins/

 Start server (generates config files)
start

Step 3: Initial Configuration

 Wait for server to fully start
 Plugin generates default configs in plugins/UltraStarterKits/

 Files created:
plugins/UltraStarterKits/
├── config.yml           Main configuration
├── kits.yml             Kit definitions
├── messages.yml         All messages
├── guis.yml             GUI layouts
└── playerdata.yml       Player data (if using YAML storage)

Step 4: Configure Storage (Optional)

 Edit config.yml
storage:
  type: "MYSQL"   Change from YAML to MYSQL
  mysql:
    host: "localhost"
    port: 3306
    database: "ultrakits"
    username: "root"
    password: "your_password"

Step 5: Reload Configuration

 In-game or console
/skit reload

Step 6: Create Your First Kit

 Method 1: Command
1. Put items in your inventory
2. /skit create starter kit.use.starter 1 never all

 Method 2: GUI
1. /skit edit starter
2. Place items in GUI
3. Click "Save Kit"

⚙️ Configuration

config.yml - Main Settings

General Settings

 Enable verbose logging for troubleshooting
debug-mode: false

 Check for updates on startup
check-updates: true

Storage Configuration

storage:
   YAML = File storage (simple)
   SQLITE = Local database (better performance)
   MYSQL = Remote database (for networks)
  type: "YAML"
  
  mysql:
    host: "localhost"
    port: 3306
    database: "ultrakits"
    username: "root"
    password: "password"
    pool-size: 10   Increase for busy servers
    use-ssl: false
  
   Auto-save every X minutes (0 = manual save only)
  auto-save-interval: 5

World Whitelist

world-whitelist:
  enabled: false   Set to true to restrict worlds
  
  worlds:
    - "world"
    - "world_nether"
    - "world_the_end"
    - "skyblock"
  
  denied-message: "&cKits are not available in this world!"

Starter Kit Settings

starter-kit:
  enabled: true
  
   Delay before giving (allows other plugins to load player data)
  delay-seconds: 3
  
   Send welcome message
  message-on-receive: true
  
   Give to players who joined before plugin installation
  give-to-existing-players: false

GUI Settings

gui:
  main-menu:
    title: "&8&l✦ &6&lKit Selection &8&l✦"
    rows: 6   1-6 rows
    
    filler:
      enabled: true
      material: "GRAY_STAINED_GLASS_PANE"
      name: " "

Locked Kit Settings

locked-kit:
  icon: "BARRIER"
  name: "&c&l🔒 %kit_name% &c(Locked)"
  
  lore:
    - "&c&l✘ &cYou don't have access!"
    - "&7Required: &e%required_rank%"
    - "&eClick for store link!"
  
  click-message:
    - ""
    - "&c&l✘ &cYou don't have access to &e%kit_name%&c!"
    - "<click:open_url:'%store_url%'>&a&l[CLICK HERE TO PURCHASE]</click>"
    - ""
  
  store-url: "https://store.yourserver.com"
  sound: "ENTITY_VILLAGER_NO"

Effects Settings

effects:
  default-claim-sound: "ENTITY_PLAYER_LEVELUP"
  
  default-claim-particles:
    enabled: true
    type: "TOTEM_OF_UNDYING"
    count: 50
  
  default-title:
    enabled: true
    title: "&a&l✓ Kit Claimed!"
    subtitle: "&7You received &e%kit_name%"
    fade-in: 10
    stay: 40
    fade-out: 10

Economy Settings

economy:
  enabled: true   Requires Vault
  format: "&a$%amount%"
  refund-percentage: 100   Refund if claim fails

Cooldown Settings

cooldowns:
   FULL: 1d 2h 30m 15s
   SHORT: 1d 2h
   SECONDS: 95415
  display-format: "FULL"
  
  notify-on-expire: true
  notify-message: "&a&l✓ &aYour &e%kit_name% &akit is now available!"

Inventory Settings

inventory:
   DROP = Drop items on ground
   DENY = Cancel kit claim
   PARTIAL = Give what fits, drop rest
  full-inventory-action: "DROP"
  
  dropped-items-message: "&eSome items were dropped on the ground!"

kits.yml - Kit Definitions

Basic Kit Structure

kits:
  kitname:
     Display name (supports color codes)
    display-name: "&a&lStarter Kit"
    
     Description (shown in GUI)
    description:
      - "&7Basic items to get started"
      - "&7Claim once per lifetime"
    
     GUI icon
    icon:
      material: "CHEST"
      custom-model-data: 0
      glowing: true
    
     Permission required
    permission: "kit.use.starter"
    
     Rank display name (for GUI)
    required-rank-display: "Default"
    
     Category (optional)
    category: "Basic"
    
     Max uses (-1 = unlimited)
    max-uses: 1
    
     Cooldown (30s, 5m, 2h, 1d, 1w, never)
    cooldown: "never"
    
     Rank-based cooldown overrides
    cooldown-overrides:
      vip: "12h"
      mvp: "6h"
      elite: "3h"
    
     Worlds where kit is available
    worlds:
      - "all"   or list specific worlds
    
     Starter kit settings
    is-starter-kit: true
    starter-kit-worlds:
      - "world"
    
     Kit items
    items:
      0:
        slot: 0
        material: "DIAMOND_SWORD"
        amount: 1
        name: "&b&lStarter Sword"
        lore:
          - "&7Your first weapon!"
        enchantments:
          sharpness: 2
          unbreaking: 1
        custom-model-data: 0
        unbreakable: false
        chance: 1.0   1.0 = 100%, 0.5 = 50%
    
     Effects
    sound: "ENTITY_PLAYER_LEVELUP"
    
    particles:
      type: "TOTEM_OF_UNDYING"
      count: 100
    
    title-message: "&a&l✓ Kit Claimed!"
    subtitle-message: "&7Enjoy your items!"
    actionbar-message: "&aSuccessfully claimed kit!"
    
    chat-messages:
      - "&aYou received the starter kit!"
    
    broadcast-message: "&e%player% &aclaimed the starter kit!"
    
    firework-effect: true
    
     Commands on claim
    commands-on-claim:
      - "[console] give %player% apple 1"
      - "[player] me received a kit!"
      - "[op] gamemode survival"
    
     Advanced features
    economy-cost: 1000   Requires Vault
    required-xp-level: 5
    
    required-items:
      - material: "DIAMOND"
        amount: 5
    consume-required-items: true
    
    expiry-date: -1   Unix timestamp or -1
    
    available-days:   Leave empty for always
      - "SATURDAY"
      - "SUNDAY"
    
    available-time-start: "08:00"   HH:mm format
    available-time-end: "20:00"
    
    one-time-bonus: true
    bonus-items:
      0:
        material: "DIAMOND_BLOCK"
        amount: 1

Item Properties Reference

items:
  0:
     Required
    material: "DIAMOND_SWORD"       Material name
   
     Optional
    amount: 1                        Stack size (1-64)
    slot: 0                          Inventory slot (0-35)
    
     Display
    name: "&b&lCustom Name"          Item name
    lore:                            Item lore
      - "&7Line 1"
      - "&7Line 2"
    
     Enchantments
    enchantments:
      sharpness: 5
      unbreaking: 3
      fire_aspect: 2
      looting: 3
      mending: 1
    
     Special properties
    custom-model-data: 12345         Custom model data
    unbreakable: true                Unbreakable flag
    
     Random items
    chance: 0.5                      50% chance to give
    
     Base64 serialization (auto-generated)
    base64: "..."                    Full NBT preservation

messages.yml - Customizable Messages

Message Categories

Prefix

prefix: "&FFD700&l✦ &6UltraKits &8» &r"

Kit Messages

kit-claimed: "&aYou successfully claimed &e%kit_name%&a!"
kit-on-cooldown: "&cThis kit is on cooldown! &7Available in: &e%time_remaining%"
kit-no-permission: "&cYou don't have permission to use this kit!"
kit-already-claimed: "&cYou've already claimed this kit the maximum number of times!"
kit-not-found: "&cKit '&e%kit_name%&c' was not found!"
kit-wrong-world: "&cThis kit is not available in this world!"
kit-inventory-full: "&cYour inventory is full! Please make some space."

Admin Messages

kit-created: "&aKit '&e%kit_name%&a' has been created successfully!"
kit-deleted: "&aKit '&e%kit_name%&a' has been deleted!"
kit-items-set: "&aSet &e%count% &aitems for kit '&e%kit_name%&a'!"
kit-given: "&aGave kit '&e%kit_name%&a' to &e%player%&a!"
data-reset: "&aReset &e%player%&a's data for kit '&e%kit_name%&a'!"
reload-success: "&aAll configurations reloaded successfully!"

Error Messages

player-not-found: "&cPlayer '&e%player%&c' not found or is offline!"
no-permission: "&cYou don't have permission to do that!"
wrong-world: "&cKits are not available in this world!"

Usage Messages

usage:
  skit-claim: "&cUsage: &e/skit claim <kit>"
  skit-give: "&cUsage: &e/skit give <player> <kit> [bypass]"

Placeholders in Messages

%player% - Player name
%kit_name% - Kit internal name
%kit_displayname% - Kit display name with colors
%time_remaining% - Formatted cooldown time
%uses_remaining% - Remaining uses
%max_uses% - Maximum uses
%cost% - Economy cost
%required_rank% - Required rank
%permission% - Required permission
%world% - World name

guis.yml - GUI Customization

Main Menu Layout

main-menu:
  title: "&8&l✦ &6&lKit Selection &8&l✦"
  rows: 6
  
  filler:
    enabled: true
    material: "GRAY_STAINED_GLASS_PANE"
    name: " "
  
   Slots where kits appear (auto-fill)
  kit-slots:
    - 10
    - 11
    - 12
    - 13
    - 14
    - 15
    - 16
    - 19
    - 20
     ... more slots
  
  buttons:
    previous-page:
      slot: 48
      material: "ARROW"
      name: "&a&l« Previous Page"
      hide-if-first-page: true
    
    next-page:
      slot: 50
      material: "ARROW"
      name: "&a&lNext Page »"
      hide-if-last-page: true
    
    page-indicator:
      slot: 49
      material: "PAPER"
      name: "&ePage %current% / %total%"
    
    close:
      slot: 53
      material: "BARRIER"
      name: "&c&lClose"

Preview Menu

preview-menu:
  title: "&8Previewing: &6%kit_name%"
  rows: 6
  
  buttons:
    back:
      slot: 49
      material: "ARROW"
      name: "&c&l« Back to Kits"
    
    info:
      slot: 45
      material: "BOOK"
      name: "&e&l%kit_name%"
      lore:
        - "&7Permission: &f%permission%"
        - "&7Uses: &f%uses%"
        - "&cThis is a preview only!"

📜 Commands Reference

Player Commands

/skit
Opens the main kit selection GUI.

Usage: /skit
Aliases: /kit, /kits, /starterkit, /ultrakits, /uk
Permission: ultrakits.use

Example:

/skit
 Opens GUI with all available kits

/skit list
Opens the kit list GUI (same as /skit).

Usage: /skit list
Permission: ultrakits.use

/skit claim <kit>
Claims a specific kit by name.

Usage: /skit claim <kitname>
Permission: ultrakits.use + kit-specific permission
Arguments:

<kitname> - The internal name of the kit

Examples:

/skit claim starter
/skit claim daily
/skit claim vip

Validation:

Checks if kit exists
Verifies permission
Validates cooldown
Confirms remaining uses
Checks world restriction
Verifies inventory space

/skit preview <kit>
Opens a view-only preview of the kit contents.

Usage: /skit preview <kitname>
Permission: ultrakits.use

Examples:

/skit preview vip
/skit preview mvp

Features:

100% secure (cannot take items)
Shows all kit items
Displays kit information
Back button to return

/skit info <kit>
Displays detailed kit information in chat.

Usage: /skit info <kitname>
Permission: ultrakits.use

Example Output:

✦ Kit Info: Starter Kit ✦

Name: starter
Permission: kit.use.starter
Description:
  Basic items to get started
  Claim once per lifetime
Max Uses: 1
Cooldown: None
Worlds: All Worlds
Starter Kit: Yes
Items: 8

Your Remaining Uses: 1
Your Cooldown: Ready!

/skit cooldown <kit>
Checks remaining cooldown time for a kit.

Usage: /skit cooldown <kitname>
Permission: ultrakits.use

Examples:

/skit cooldown daily
 Output: Daily Kit cooldown: 5h 32m 15s

/skit cooldown vip
 Output: VIP Kit is ready to claim!

Admin Commands

/skit create <name> <permission> <uses> <cooldown> <world>
Creates a new kit from your current inventory.

Usage: /skit create <name> <permission> <uses> <cooldown> <world>
Permission: ultrakits.admin.create

Arguments:

<name> - Kit internal name (lowercase, no spaces)
<permission> - Required permission (e.g., kit.use.vip)
<uses> - Max uses (1, 5, unlimited, -1)
<cooldown> - Cooldown time (30s, 5m, 24h, never, -1)
<world> - World restriction (all, world, skyblock)

Examples:

 Create a one-time starter kit
/skit create starter kit.use.starter 1 never all

 Create a VIP kit with 24h cooldown
/skit create vip kit.use.vip unlimited 24h all

 Create a PvP kit only for pvp world
/skit create pvpkit kit.use.pvp unlimited 5m pvp

 Create a weekly kit
/skit create weekly kit.use.weekly unlimited 7d all

Process:

Put items in your inventory (arrange them as you want)
Run the create command
Plugin captures all inventory items
Kit is created with default settings
Further customize with other commands or edit GUI

/skit delete <kit>
Deletes a kit permanently.

Usage: /skit delete <kitname>
Permission: ultrakits.admin.delete

Example:

/skit delete oldkit
 Opens confirmation GUI

Safety:

Opens confirmation dialog
Shows kit item count
Warns about permanent deletion
Click confirm to delete
Click cancel to abort

/skit edit <kit>
Opens the visual kit editor GUI.

Usage: /skit edit <kitname>
Permission: ultrakits.admin.edit

Example:

/skit edit vip
 Opens 6-row inventory editor

Features:

Drag-and-drop items
Visual item arrangement
Save button
Cancel button
Settings button (shows current config)

/skit setitems <kit>
Sets kit items from your current inventory.

Usage: /skit setitems <kitname>
Permission: ultrakits.admin.edit

Example:

 1. Arrange items in your inventory
 2. Run command
/skit setitems vip
 Output: Set 15 items for kit 'vip'!

/skit additem <kit>
Adds your held item to the kit.

Usage: /skit additem <kitname>
Permission: ultrakits.admin.edit

Example:

 1. Hold a diamond sword
 2. Run command
/skit additem vip
 Output: Added Diamond Sword to kit 'vip'!

/skit removeitem <kit> <slot>
Removes an item from a specific slot.

Usage: /skit removeitem <kitname> <slot>
Permission: ultrakits.admin.edit

Arguments:

<slot> - Slot number (0-based index)

Example:

/skit removeitem vip 5
 Output: Removed item at slot 5 from kit 'vip'!

/skit seticon <kit>
Sets the GUI icon to your held item.

Usage: /skit seticon <kitname>
Permission: ultrakits.admin.edit

Example:

 1. Hold a gold block
 2. Run command
/skit seticon vip
 Output: Set icon for 'vip' to GOLD_BLOCK!

/skit setpermission <kit> <permission>
Changes the required permission.

Usage: /skit setpermission <kitname> <permission>
Permission: ultrakits.admin.edit

Example:

/skit setpermission vip kit.use.vipplus
 Output: Set permission for 'vip' to kit.use.vipplus!

/skit setuses <kit> <amount>
Sets maximum uses.

Usage: /skit setuses <kitname> <amount|unlimited>
Permission: ultrakits.admin.edit

Examples:

/skit setuses starter 1
 Output: Set max uses for 'starter' to 1!

/skit setuses daily unlimited
 Output: Set max uses for 'daily' to Unlimited!

/skit setuses weekly 52
 Output: Set max uses for 'weekly' to 52!

/skit setcooldown <kit> <time>
Sets cooldown time.

Usage: /skit setcooldown <kitname> <time|never>
Permission: ultrakits.admin.edit

Time Format:

30s - 30 seconds
5m - 5 minutes
2h - 2 hours
1d - 1 day
1w - 1 week
never or -1 - No cooldown

Examples:

/skit setcooldown daily 24h
/skit setcooldown vip 12h
/skit setcooldown pvp 5m
/skit setcooldown starter never

/skit setworld <kit> <world>
Sets world restriction.

Usage: /skit setworld <kitname> <world|all>
Permission: ultrakits.admin.edit

Examples:

/skit setworld pvpkit pvp
 Output: Set world for 'pvpkit' to pvp!

/skit setworld daily all
 Output: Set world for 'daily' to All Worlds!

/skit setworld skyblock skyblock_world

/skit setstarterkit <kit> <true|false>
Toggles starter kit status.

Usage: /skit setstarterkit <kitname> <true|false>
Permission: ultrakits.admin.edit

Examples:

/skit setstarterkit starter true
 Output: Starter kit status for 'starter' set to Enabled!

/skit setstarterkit daily false
 Output: Starter kit status for 'daily' set to Disabled!

/skit give <player> <kit> [bypass]
Gives a kit to a player.

Usage: /skit give <player> <kitname> [bypass]
Permission: ultrakits.admin.give

Arguments:

<player> - Player name (must be online)
<kitname> - Kit to give
[bypass] - Optional: bypasses all restrictions

Examples:

/skit give Steve starter
 Gives starter kit (checks all restrictions)

/skit give Steve vip bypass
 Gives VIP kit (bypasses cooldown, uses, permissions)

/skit give Steve daily true
 Same as bypass

Use Cases:

Reward players
Compensate for bugs
Event prizes
Testing kits

/skit reset <player> [kit|all]
Resets player kit data.

Usage: /skit reset <player> [kitname|all]
Permission: ultrakits.admin.reset

Examples:

 Reset specific kit
/skit reset Steve starter
 Output: Reset Steve's data for kit 'starter'!

 Reset all kits
/skit reset Steve all
 Output: Reset all kit data for Steve!

What Gets Reset:

Use counts
Cooldown timestamps
Bonus received flags
(Does NOT delete kits themselves)

/skit reload
Reloads all configuration files.

Usage: /skit reload
Permission: ultrakits.admin.reload
Can be run from console: Yes

Example:

/skit reload
 Output: All configurations reloaded successfully!

What Gets Reloaded:

config.yml
kits.yml
messages.yml
guis.yml
All kits from file

Note: Player data in cache is NOT reset

🔐 Permissions System

Permission Hierarchy

ultrakits.*
├── ultrakits.admin
│   ├── ultrakits.admin.create
│   ├── ultrakits.admin.delete
│   ├── ultrakits.admin.edit
│   │   ├── ultrakits.admin.edit.items
│   │   ├── ultrakits.admin.edit.icon
│   │   └── ultrakits.admin.edit.settings
│   ├── ultrakits.admin.give
│   ├── ultrakits.admin.reset
│   └── ultrakits.admin.reload
│
├── ultrakits.use
│   ├── ultrakits.command.list
│   ├── ultrakits.command.claim
│   ├── ultrakits.command.preview
│   ├── ultrakits.command.info
│   ├── ultrakits.command.cooldown
│   └── ultrakits.command.help
│
└── ultrakits.bypass.*
    ├── ultrakits.bypass.cooldown
    ├── ultrakits.bypass.uses
    ├── ultrakits.bypass.world
    ├── ultrakits.bypass.permission
    └── ultrakits.bypass.cost

Permission Nodes Reference

Permission	Default	Description
`ultrakits.*`	op	Full access to everything
`ultrakits.admin`	op	All admin commands
`ultrakits.use`	true	Basic kit usage
`ultrakits.bypass.*`	op	Bypass all restrictions
`ultrakits.bypass.cooldown`	op	No cooldowns
`ultrakits.bypass.uses`	op	Unlimited uses
`ultrakits.bypass.world`	op	Use kits in any world
`ultrakits.bypass.permission`	op	Access all kits
`ultrakits.bypass.cost`	op	Free kits
`kit.use.<kitname>`	false	Access to specific kit

LuckPerms Setup Examples

Basic Player (Default Group)

 Give basic kit access
lp group default permission set ultrakits.use true
lp group default permission set kit.use.starter true
lp group default permission set kit.use.daily true

VIP Rank

 Create VIP group
lp creategroup vip

 Set parent group
lp group vip parent add default

 Add VIP kit permissions
lp group vip permission set kit.use.vip true
lp group vip permission set kit.use.daily true

 Set VIP as primary group for player
lp user Steve parent set vip

🚀 Advanced Features

Rank-Based Cooldown Overrides

How It Works:

Base cooldown is set in kit config
LuckPerms group names are detected
If player's group has an override, it's used instead

Example Configuration:

kits:
  daily:
    cooldown: "24h"   Default for everyone
    
    cooldown-overrides:
      vip: "18h"       VIPs wait 18 hours
      mvp: "12h"       MVPs wait 12 hours
      elite: "6h"      Elites wait 6 hours
      ultimate: "1h"   Ultimates wait 1 hour

Real-World Example:

Default player: Claims kit → waits 24 hours
VIP player:     Claims kit → waits 18 hours
MVP player:     Claims kit → waits 12 hours
Elite player:   Claims kit → waits 6 hours

World Restriction System

Global Whitelist
Restricts the entire plugin to specific worlds.

 config.yml
world-whitelist:
  enabled: true
  worlds:
    - "world"
    - "survival"
    - "skyblock"

Effect: Commands don't work in other worlds.

Per-Kit Worlds
Restricts individual kits to specific worlds.

 kits.yml
kits:
  pvp-kit:
    worlds:
      - "pvp"
      - "arena"
  
  survival-kit:
    worlds:
      - "survival"
  
  global-kit:
    worlds:
      - "all"

Use Cases:

PvP kits only in PvP worlds
Survival kits not in creative worlds
Skyblock-specific starter packs

Economy Integration (Vault)

Setup

Install Vault + economy plugin (EssentialsX, etc.)
Enable in config:

economy:
  enabled: true
  format: "&a$%amount%"

Kit Configuration

kits:
  premium:
    economy-cost: 5000   Costs $5000

Features

Automatic balance check
Deducts money on claim
Refunds if claim fails
Shows cost in GUI

Setup Steps:

Install MySQL server
Create database: CREATE DATABASE ultrakits;
Configure plugin with credentials
Restart server (tables auto-create)

Network Setup (BungeeCord):

 Same MySQL config on all servers
 Players' data syncs automatically across network

📊 PlaceholderAPI Integration

Installation

Install PlaceholderAPI: /papi download ultrakits
Reload: /papi reload

Available Placeholders

Per-Kit Placeholders

Placeholder	Output Example	Description
`%ultrakit_uses_remaining_<kit>%`	`3`	Remaining uses for kit
`%ultrakit_uses_total_<kit>%`	`5`	Total max uses
`%ultrakit_cooldown_<kit>%`	`3600`	Cooldown in seconds
`%ultrakit_cooldown_formatted_<kit>%`	`1h 30m`	Formatted time
`%ultrakit_can_claim_<kit>%`	`true`	If player can claim
`%ultrakit_has_permission_<kit>%`	`false`	If has permission
`%ultrakit_kit_displayname_<kit>%`	`&a&lStarter Kit`	Kit display name
`%ultrakit_kit_exists_<kit>%`	`true`	If kit exists

Global Placeholders

Placeholder	Output Example	Description
`%ultrakit_total_kits_claimed%`	`47`	Total kits claimed by player
`%ultrakit_available_kits_count%`	`8`	Kits currently available
`%ultrakit_next_available_kit%`	`Daily Kit`	Next claimable kit name
`%ultrakit_total_kits%`	`15`	Total kits on server
`%ultrakit_player_group%`	`vip`	Player's LuckPerms group

❓ FAQ & Troubleshooting

General Questions

Q: What Minecraft versions are supported?
A: Minecraft 1.21.x on Paper or Spigot.

Q: Do I need Paper or will Spigot work?
A: Both work, but Paper is recommended for better performance and native Adventure API support.

Q: Is this compatible with BungeeCord/Velocity?
A: Yes! Use MySQL storage and configure the same database on all servers.

Q: Can I translate messages to other languages?
A: Yes! All messages are in messages.yml and fully customizable.

Installation Issues

Q: Plugin doesn't load on startup
A: Check console for errors. Common issues:

Wrong Java version (need Java 17+)
Wrong Minecraft version (need 1.21+)
Corrupted JAR file (re-download)

Q: Commands don't work
A: Verify:

Plugin is enabled (/plugins shows green)
You have permission (ultrakits.use)
World is whitelisted (if whitelist is enabled)

Database Issues

Q: MySQL won't connect
A: Checklist:

MySQL server is running
Database exists (CREATE DATABASE ultrakits;)
Credentials are correct
Port is correct (default 3306)
Host is correct (usually localhost)
Firewall allows connection

Q: SQLite file is locked
A: Usually caused by:

Multiple servers using same file
Previous server crash
Solution: Restart server or delete .db file (WARNING: deletes data)

Q: Player data not saving
A: Check:

Auto-save is enabled
Database connection is working
Console for error messages
Manually save: /skit reload

Kit Issues

Q: Kit items aren't saving correctly
A: This usually happens with custom NBT data. Fix:

Use Paper (better NBT support than Spigot)
Recreate kit using /skit edit GUI
Check console for serialization errors

Q: Enchantments not working
A: Ensure:

Enchantment names are correct (lowercase, underscores)
Example: sharpness: 5 not Sharpness: V
Use Minecraft enchantment IDs

Q: Custom model data not saving
A: Set in config:

custom-model-data: 12345

Permission Issues

Q: Everyone can use all kits
A: Check:

Kit permissions are set correctly
Players don't have ultrakits.* wildcard
LuckPerms is installed and working

Q: LuckPerms groups not detected
A: Verify:

LuckPerms is installed and enabled
Plugin detects LuckPerms (check startup log)
Group names match exactly (case-sensitive)

Q: Rank overrides not working
A: Ensure:

Group name in config matches LuckPerms group
Player is in that group (/lp user <player> info)
Example:

cooldown-overrides:
  vip: "12h"   Must match LuckPerms group "vip"

Cooldown Issues

Q: Cooldown not working
A: Check:

Time format is correct (24h not 24hours)
Cooldown is set in kit config
Player doesn't have bypass permission

Q: Cooldown shows wrong time
A: Verify:

Server time is correct
No conflicting plugins modifying time
Reload plugin: /skit reload

GUI Issues

Q: GUI doesn't open
A: Causes:

Inventory is full (server blocks opening)
Permission missing
World not whitelisted

Q: Items can be taken from preview GUI
A: This shouldn't happen. If it does:

Report as a bug
Update to latest version
Check for conflicting inventory plugins

Q: Pagination not working
A: Usually happens when:

Too many kits (100+)
GUI config is wrong
Fix: Adjust kit-slots in guis.yml

Performance Issues

Q: Server lags when opening GUI
A: Optimization tips:

Reduce kit count (split into categories)
Use MySQL instead of YAML
Increase cache expiry time
Check for other laggy plugins

Q: High RAM usage
A: Normal usage is 20-50MB. If higher:

Too many kits cached
Clear cache: restart server
Reduce auto-save frequency

Error Messages

Q: "Kit not found" even though it exists
A: Common causes:

Typo in kit name (case-sensitive)
Kit not loaded (reload: /skit reload)
Corrupted kits.yml

Q: "Failed to serialize item"
A: Item has unsupported NBT:

Simplify the item
Remove custom NBT
Use vanilla items only

Q: "Database error" on startup
A: Check:

Database credentials
Database server is running
Network connection
Console for specific SQL error

📞 Support & Resources

Official Links

Discord: discord.gg/ultrakits

Getting Help

Ask in discord

Feature Requests
Submit feature requests on:

Discord server

Bug Reports
Include:

Server version
Plugin version
Error logs
Steps to reproduce
Screenshots (if GUI issue)

📜 License & Credits

🎉 Thank You!

Thank you for choosing UltraStarterKits! We hope it enhances your server and provides an excellent experience for your players.

If you enjoy the plugin, please:

⭐ Leave a 5-star review
📢 Recommend to other server owners
💬 Join our Discord community

Happy server management! 🚀**

UltraStarterKits

📖About UltraStarterKits