** 🎮 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
```yaml
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
```yaml
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
```yaml
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
1. Download `UltraStarterKits`

Step 2: Install
```bash
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
```bash
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)
```yaml
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
```bash
In-game or console
/skit reload
```

Step 6: Create Your First Kit
```bash
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
```yaml
Enable verbose logging for troubleshooting
debug-mode: false

Check for updates on startup
check-updates: true
```

Storage Configuration
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
economy:
enabled: true Requires Vault
format: "&a$%amount%"
refund-percentage: 100 Refund if claim fails
```

Cooldown Settings
```yaml
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
```yaml
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
```yaml
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
```yaml
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**
```yaml
prefix: "&FFD700&l✦ &6UltraKits &8» &r"
```

**Kit Messages**
```yaml
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**
```yaml
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**
```yaml
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**
```yaml
usage:
skit-claim: "&cUsage: &e/skit claim <kit>"
skit-give: "&cUsage: &e/skit give <player> <kit> [bypass]"
```

Placeholders in Messages
```yaml
%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
```yaml
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
```yaml
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:**
```bash
/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:**
```bash
/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:**
```bash
/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:**
```bash
/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:**
```bash
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:**
1. Put items in your inventory (arrange them as you want)
2. Run the create command
3. Plugin captures all inventory items
4. Kit is created with default settings
5. Further customize with other commands or edit GUI

---

`/skit delete <kit>`
Deletes a kit permanently.

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

**Example:**
```bash
/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:**
```bash
/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:**
```bash
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:**
```bash
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:**
```bash
/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:**
```bash
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:**
```bash
/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:**
```bash
/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:**
```bash
/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:**
```bash
/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:**
```bash
/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:**
```bash
/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:**
```bash
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:**
```bash
/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)
```bash
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
```bash
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:**
1. Base cooldown is set in kit config
2. LuckPerms group names are detected
3. If player's group has an override, it's used instead

**Example Configuration:**
```yaml
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.

```yaml
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.

```yaml
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
1. Install Vault + economy plugin (EssentialsX, etc.)
2. Enable in config:
```yaml
economy:
enabled: true
format: "&a$%amount%"
```

Kit Configuration
```yaml
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:**
1. Install MySQL server
2. Create database: `CREATE DATABASE ultrakits;`
3. Configure plugin with credentials
4. Restart server (tables auto-create)

**Network Setup (BungeeCord):**
```yaml
Same MySQL config on all servers
Players' data syncs automatically across network
```

---

📊 PlaceholderAPI Integration

Installation
1. Install PlaceholderAPI: `/papi download ultrakits`
2. 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:
1. MySQL server is running
2. Database exists (`CREATE DATABASE ultrakits;`)
3. Credentials are correct
4. Port is correct (default 3306)
5. Host is correct (usually `localhost`)
6. 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:
```yaml
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:
```yaml
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](https://discord.gg/xctckUQukB)

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! 🚀****