UltraStarterKits

** 🎮 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?

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

🏆 Perfect For

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

---

✨ Key Features

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

🔐 Permission & Access Control | Feature | Description | |---------|-------------| | Bypass Permissions | Direct API integration (not just Vault) | | Bypass Permissions | Individual permission nodes per kit | | Bypass Permissions | Different cooldowns/uses for different ranks | | Bypass Permissions | Checks both primary and inherited groups | | Bypass Permissions | Show "VIP" instead of "kit.use.vip" | | Bypass Permissions | Admin permissions to bypass all restrictions |

⏱️ Cooldown System | Feature | Description | |---------|-------------| | No Cooldown Option | Support for seconds, minutes, hours, days, weeks | | No Cooldown Option | VIPs get 12h cooldown, MVPs get 6h, etc. | | No Cooldown Option | Persistent cooldown storage across restarts | | No Cooldown Option | Optional notifications when cooldowns expire | | No Cooldown Option | Full (1d 2h 30m), Short (1d 2h), Seconds (95400) | | No Cooldown Option | Use "never" or -1 for instant re-claim |

🎫 Usage Limits | Feature | Description | |---------|-------------| | Use Reset | 1-time, 5-time, 100-time kits | | Use Reset | Infinite re-claims with cooldown | | Use Reset | Different use counts per rank | | Use Reset | Persistent storage of claim counts | | Use Reset | Admin command to reset usage data |

🌍 World Management | Feature | Description | |---------|-------------| | Bypass Permission | Restrict plugin to specific worlds | | Bypass Permission | Kit only works in designated worlds | | Bypass Permission | Different kits for different worlds | | Bypass Permission | Auto-give starter kits on world entry | | Bypass Permission | Admins can use kits anywhere |

🎮 GUI System | Feature | Description | |---------|-------------| | Dynamic Lore | Beautiful paginated kit selection GUI | | Dynamic Lore | 100% secure view-only kit preview | | Dynamic Lore | Shows unavailable kits with requirements | | Dynamic Lore | MiniMessage-powered clickable URLs | | Dynamic Lore | Visual drag-and-drop kit editor | | Dynamic Lore | Deletion confirmations with warnings | | Dynamic Lore | Auto-pagination for 30+ kits | | Dynamic Lore | Per-kit custom materials and model data | | Dynamic Lore | Optional enchantment glow effect | | Dynamic Lore | Real-time cooldown/uses display |

💾 Storage Options | Type | Use Case | Pros | Cons | |------|----------|------|------| | MySQL | Single servers | Easy setup, human-readable | Not network-compatible | | MySQL | 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 | |--------|------------------|----------| | bStats | ⭐⭐⭐⭐⭐ Deep | Groups, permissions, prefixes, suffixes, rank detection | | bStats | ⭐⭐⭐⭐ Full | Economy costs, permission fallback | | bStats | ⭐⭐⭐⭐⭐ Deep | 15+ custom placeholders | | bStats | ⭐⭐⭐ Standard | Anonymous usage metrics |

🎨 Effects & Feedback | Effect Type | Customizable | Per-Kit | |-------------|--------------|---------| | Fireworks | ✅ Yes | ✅ Yes | | Fireworks | ✅ Yes | ✅ Yes | | Fireworks | ✅ Yes | ✅ Yes | | Fireworks | ✅ Yes | ✅ Yes | | Fireworks | ✅ Yes | ✅ Yes | | Fireworks | ✅ Yes | ✅ Yes | | Fireworks | ✅ Yes | ✅ Yes | | Fireworks | ✅ Yes | ✅ Yes |

🚀 Advanced Features | Feature | Description | |---------|-------------| | Connection Pooling | Auto-give on first join per world | | Connection Pooling | Charge money for kit claims (Vault) | | Connection Pooling | Require XP levels to claim | | Connection Pooling | Consume items to claim kit | | Connection Pooling | Run commands on kit claim (console/player/op) | | Connection Pooling | Extra items on first claim only | | Connection Pooling | Configurable auto-save intervals | | Connection Pooling | Smart caching for performance | | Connection Pooling | 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.

Permission: `/skit` Permission: `/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`).

Permission: `/skit list` Permission: `ultrakits.use`

---

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

Arguments: `/skit claim <kitname>` Arguments: `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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Permission: `/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.

Can be run from console: `/skit reload` Can be run from console: `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:

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

License: UltraStarterKits License: 1.0.0 License: geturplugins License: All Rights Reserved

---

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