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?

• 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

Permission & Access Control

Cooldown System

Usage Limits

World Management

GUI System

Storage Options

Integrations

Effects & Feedback

Advanced Features

---

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

1. 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:

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