** 🎮 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!" - "&a&l[CLICK HERE TO PURCHASE]" - "" 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 " skit-give: "&cUsage: &e/skit give [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 ` Claims a specific kit by name. **Usage:** `/skit claim ` **Permission:** `ultrakits.use` + kit-specific permission **Arguments:** - `` - 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 ` Opens a view-only preview of the kit contents. **Usage:** `/skit preview ` **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 ` Displays detailed kit information in chat. **Usage:** `/skit info ` **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 ` Checks remaining cooldown time for a kit. **Usage:** `/skit cooldown ` **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 ` Creates a new kit from your current inventory. **Usage:** `/skit create ` **Permission:** `ultrakits.admin.create` **Arguments:** - `` - Kit internal name (lowercase, no spaces) - `` - Required permission (e.g., `kit.use.vip`) - `` - Max uses (`1`, `5`, `unlimited`, `-1`) - `` - Cooldown time (`30s`, `5m`, `24h`, `never`, `-1`) - `` - 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 ` Deletes a kit permanently. **Usage:** `/skit delete ` **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 ` Opens the visual kit editor GUI. **Usage:** `/skit edit ` **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 ` Sets kit items from your current inventory. **Usage:** `/skit setitems ` **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 ` Adds your held item to the kit. **Usage:** `/skit additem ` **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 ` Removes an item from a specific slot. **Usage:** `/skit removeitem ` **Permission:** `ultrakits.admin.edit` **Arguments:** - `` - Slot number (0-based index) **Example:** ```bash /skit removeitem vip 5 Output: Removed item at slot 5 from kit 'vip'! ``` --- `/skit seticon ` Sets the GUI icon to your held item. **Usage:** `/skit seticon ` **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 ` Changes the required permission. **Usage:** `/skit setpermission ` **Permission:** `ultrakits.admin.edit` **Example:** ```bash /skit setpermission vip kit.use.vipplus Output: Set permission for 'vip' to kit.use.vipplus! ``` --- `/skit setuses ` Sets maximum uses. **Usage:** `/skit setuses ` **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 ` Sets cooldown time. **Usage:** `/skit setcooldown ` **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 ` Sets world restriction. **Usage:** `/skit setworld ` **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 ` Toggles starter kit status. **Usage:** `/skit setstarterkit ` **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 [bypass]` Gives a kit to a player. **Usage:** `/skit give [bypass]` **Permission:** `ultrakits.admin.give` **Arguments:** - `` - Player name (must be online) - `` - 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 [kit|all]` Resets player kit data. **Usage:** `/skit reset [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.` | 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_%` | `3` | Remaining uses for kit | | `%ultrakit_uses_total_%` | `5` | Total max uses | | `%ultrakit_cooldown_%` | `3600` | Cooldown in seconds | | `%ultrakit_cooldown_formatted_%` | `1h 30m` | Formatted time | | `%ultrakit_can_claim_%` | `true` | If player can claim | | `%ultrakit_has_permission_%` | `false` | If has permission | | `%ultrakit_kit_displayname_%` | `&a&lStarter Kit` | Kit display name | | `%ultrakit_kit_exists_%` | `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 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 **Plugin Name:** UltraStarterKits **Version:** 1.0.0 **Author:** 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! 🚀****

JustErikSK