# 📋 COMPLETE INSTALLATION & ADMIN GUIDE ## Timed Kit System with LuckPerms + DeluxeMenus --- ## 🔧 PART 1: DEPENDENCIES REQUIRED You **must** have these plugins installed: 1. **Skript** (latest version) 2. **DeluxeMenus** (1.13.x or newer) 3. **EssentialsX** (core plugin) 4. **LuckPerms** (for timed permission locks) 5. **PlaceholderAPI** (for placeholder expansion) 6. **Vault** (dependency for most plugins) ### Required PAPI Expansions: ``` /papi ecloud download Essentials /papi ecloud download LuckPerms /papi reload ``` Verify placeholders work: ``` /papi parse YourName %essentials_kit_is_available_daily% /papi parse YourName %luckperms_expiry_time_kits.daily.locked% ``` --- ## 📦 PART 2: FILE INSTALLATION ### Step 1: Upload the Skript 1. Navigate to `/plugins/Skript/scripts/` 2. Upload `auto_kits.sk` 3. Run `/sk reload auto_kits` or `/skript reload auto_kits` 4. Check console for errors ### Step 2: Upload the DeluxeMenus Config 1. Navigate to `/plugins/DeluxeMenus/gui_menus/` 2. Upload `kits_menu.yml` 3. Run `/dm reload` 4. Test with `/kits` in-game --- ## ⚙️ PART 3: CONFIGURE ESSENTIALSX KITS You need to create **5 kits** in `/plugins/Essentials/kits.yml`: ### Example Kit Configuration: ```yaml kits: starter: delay: 0 items: - diamond_sword 1 name:&eStarter_Sword - cooked_beef 32 - golden_apple 5 claim: delay: 43200 # 12 hours in seconds items: - diamond 5 - emerald 10 daily: delay: 86400 # 24 hours items: - netherite_scrap 1 - diamond 10 weekly: delay: 604800 # 7 days items: - netherite_ingot 2 - diamond_block 5 monthly: delay: 2592000 # 30 days items: - nether_star 1 - diamond_block 10 ``` **After editing**, run `/essentials reload` or restart the server. --- ## 🔐 PART 4: HOW THE SYSTEM WORKS ### When a Player Joins for the First Time: 1. **Skript triggers** the `on first join:` event 2. **Console runs** these commands: ``` /lp user permission settemp kits.daily.locked true 1d /lp user permission settemp kits.weekly.locked true 7d /lp user permission settemp kits.monthly.locked true 30d ``` 3. **After 5 seconds**, player receives a welcome message 4. **Player can immediately claim:** - ✅ Starter Kit (one-time) - ✅ Claim Kit (12h cooldown) - ❌ Daily (locked for 1 day) - ❌ Weekly (locked for 7 days) - ❌ Monthly (locked for 30 days) ### Kit Priority System Explained: #### Starter & Claim Kits (2 Priorities): - **Priority 1**: Kit is available → Click to claim - **Priority 2**: Kit is on cooldown/claimed → Shows "unavailable" message #### Daily/Weekly/Monthly Kits (3 Priorities): - **Priority 1 (HIGHEST)**: Player has `kits..locked` → Shows LP timer - **Priority 2**: Kit is on Essentials cooldown → Shows Essentials timer - **Priority 3 (FALLBACK)**: Kit is available → Click to claim --- ## 🎮 PART 5: PLAYER USAGE ### Commands: - `/kits` or `/kit` or `/kitmenu` — Opens the kit GUI ### What Players See: **Day 1 (New Player):** - Starter: ✅ Available - Claim: ✅ Available - Daily: 🔒 Unlocks in 23h 59m (LP lock) - Weekly: 🔒 Unlocks in 6d 23h (LP lock) - Monthly: 🔒 Unlocks in 29d 23h (LP lock) **Day 2 (After claiming Starter once):** - Starter: ❌ Already Claimed - Claim: ✅ Available (if 12h passed) - Daily: ✅ Available (LP lock expired) - Weekly: 🔒 Unlocks in 5d 23h - Monthly: 🔒 Unlocks in 28d 23h --- ## 🛠️ PART 6: ADMIN COMMANDS & MANAGEMENT ### Check a Player's LP Permissions: ``` /lp user info /lp user permission info ``` ### Manually Give a Player Locked Permissions: ``` /lp user Steve permission settemp kits.daily.locked true 1d /lp user Steve permission settemp kits.weekly.locked true 7d /lp user Steve permission settemp kits.monthly.locked true 30d ``` ### Remove a Lock Early (Unlock Kit for Testing): ``` /lp user Steve permission unset kits.daily.locked ``` ### Reset a Player's Kit Cooldown: Edit `/plugins/Essentials/userdata/.yml` and remove the kit timestamp, OR use: ``` /essentials:kit ``` This bypasses cooldowns and forces the kit to be given. ### Check if Placeholders Work: ``` /papi parse %essentials_kit_is_available_daily% /papi parse %essentials_kit_time_until_available_daily% /papi parse %luckperms_expiry_time_kits.daily.locked% ``` --- ## 🎨 PART 7: CUSTOMIZING THE GUI ### Where to Edit Items: Open `kits_menu.yml` and find sections like this: ```yaml lore: - '' - '&7Rewards:' - '&f [CUSTOMIZE YOUR ITEMS HERE]' - '' ``` **Replace `[CUSTOMIZE YOUR ITEMS HERE]` with your actual lore**, for example: ```yaml lore: - '' - '&7Rewards:' - '&f • &b5 Diamonds' - '&f • &610 Emeralds' - '&f • &eStarter Sword' - '' ``` ### Changing the Item Icons: Find the `material:` line for each kit, for example: ```yaml material: CHEST ``` Change it to any Minecraft material: ```yaml material: DIAMOND_SWORD material: GOLDEN_APPLE material: NETHER_STAR ``` ### Changing Sounds: Find `left_click_commands:` and modify: ```yaml - '[sound] ENTITY_PLAYER_LEVELUP' # Success sound - '[sound] ENTITY_VILLAGER_NO' # Deny sound ``` Valid sounds: `ENTITY_EXPERIENCE_ORB_PICKUP`, `BLOCK_NOTE_BLOCK_PLING`, `UI_BUTTON_CLICK`, etc. --- ## 🧪 PART 8: TESTING THE SYSTEM ### Test as Admin: 1. **Clear your player data** (or test on alt account): ``` /lp user YourName clear ``` Delete your file in `/plugins/Essentials/userdata/` 2. **Rejoin the server** to trigger first-join event 3. **Check your permissions:** ``` /lp user YourName info ``` You should see 3 temporary permissions. 4. **Open the GUI:** ``` /kits ``` 5. **Test each kit:** - Starter: Should claim successfully - Daily/Weekly/Monthly: Should show LP lock timer - Claim: Should claim successfully 6. **Wait or manually remove locks:** ``` /lp user YourName permission unset kits.daily.locked ``` Reopen `/kits` — Daily should now be available! --- ## ❗ PART 9: TROUBLESHOOTING ### Problem: GUI doesn't open - Check `/dm reload` ran without errors - Verify file is in `/plugins/DeluxeMenus/gui_menus/` - Check console for YAML errors ### Problem: Kits show "Internal Placeholder Error" - Install PAPI expansions: `/papi ecloud download Essentials` - Reload PAPI: `/papi reload` - Verify kits exist in EssentialsX: `/essentials:kit` ### Problem: LP locks don't apply on first join - Check Skript loaded: `/sk reload auto_kits` - Check console for errors during join - Manually test: `/lp user YourName permission settemp kits.daily.locked true 1d` ### Problem: Timer shows "Never" or blank - LuckPerms permission expired or was never set - Check: `/lp user permission info` ### Problem: Player can spam-claim kits - Check EssentialsX kit delays configured correctly - Verify `delay:` in kits.yml is in **seconds** --- ## 📊 PART 10: QUICK REFERENCE | Kit Name | Slot | Cooldown | LP Lock | Priority Count | |----------|------|----------|---------|----------------| | Starter | 20 | One-time | None | 2 | | Claim | 21 | 12 hours | None | 2 | | Daily | 22 | 24 hours | 1 day | 3 | | Weekly | 23 | 7 days | 7 days | 3 | | Monthly | 24 | 30 days | 30 days | 3 | ### Time Conversions (for EssentialsX delays): - 12 hours = `43200` seconds - 24 hours = `86400` seconds - 7 days = `604800` seconds - 30 days = `2592000` seconds --- ## 🎯 SUMMARY FOR ADMINS ### What you need to do: 1. ✅ Install dependencies (Skript, DeluxeMenus, EssentialsX, LuckPerms, PAPI, Vault) 2. ✅ Install PAPI expansions (Essentials + LuckPerms) 3. ✅ Upload both files (`auto_kits.sk` and `kits_menu.yml`) 4. ✅ Configure 5 kits in `/plugins/Essentials/kits.yml` 5. ✅ Customize lore/items in DeluxeMenus YAML 6. ✅ Test with alt account or cleared data ### What happens automatically: - New players get LP locks on join - GUI updates every second (20 ticks) - Timers count down in real-time - Kits claim via EssentialsX system **No further admin intervention needed** — system is fully automatic once configured! --- ## 📞 SUPPORT If you encounter issues: 1. Check console for errors 2. Verify all dependencies are installed 3. Test placeholders with `/papi parse` 4. Review the troubleshooting section above 5. Join the plugin support Discord servers for Skript, DeluxeMenus, or EssentialsX --- **System Version:** 1.0 **Last Updated:** 2024 **Compatible with:** Minecraft 1.16+ (Paper/Spigot)