QKits

QKits is a modern Paper/Purpur 1.21.11 kit management, customization, and distribution plugin built for competitive PvP events, content creator SMPs, and tournament servers. Designed as the companion to QTeams and QWorlds, QKits combines lossless binary NBT item serialization with Mojang's Native Dialog UI (io.papermc.paper.dialog) and 1.21.11 2D Atlas Sprite components (ObjectContents.sprite), rendering graphical 2D item grids directly inside hover tooltips and the in-menu kit editor without requiring any client mods or resource packs.

---

Core Architecture & Features

1. Three Kit Categories & Naming Prefixes (Full, Inventory i_, Armor a_)

QKits organizes loadouts into three independent namespaces so kits can share base names across categories without conflict:

• Full Kits (<kitname>): Saves all 36 Storage Slots + 1 Offhand Slot + 4 Armor Slots. Supports full equipping or independent extraction/updating of Inventory + Offhand Only (+inv) or Armor Only (+armor).
• Inventory Kits (i_<kitname>): Saves 36 Storage Slots + 1 Offhand Slot (leaves the player's worn armor untouched). Always referenced as i_<name> in commands and tab-completion.
• Armor Kits (a_<kitname>): Saves the 4 Armor Slots (Helmet, Chestplate, Leggings, Boots) and auto-equips them directly onto the player without touching their inventory or offhand. Always referenced as a_<name>.

2. Pixel-Aligned 3-Column Native Dialog UI & 2D Item Sprite Grids

• Unified 3-Column Dashboard (/qk): Displays Full Kits, Inventory Kits (i_), and Armor Kits (a_) side-by-side in a framed, pixel-aligned 3-column table (│ Full │ Inv │ Armor │) where full kit names are always visible.
  • Click Kit Name: Immediately equips the kit on yourself.
  • Hover Kit Name or [✎]: Displays a graphical 2D Item Sprite Tooltip showing the kit's Armor sprites, Offhand sprite, 3x9 Main Inventory rows, and 1x9 Hotbar row left-to-right.
  • Click [✎]: Opens the in-menu Kit Editor.
  • Click [✖]: Opens a Delete Confirmation Dialog.
• Role-Aware Public Selector (/qk for Non-OPs): Non-OP players see a clean 3-column selector showing only kits marked Public, where clicking a kit claims it and hovering previews its 2D item grid.

3. In-Menu 2D Sprite Inventory Editor & 54-Slot Drag-and-Drop Grid

• Visual 2D Sprite Layout inside the Dialog: The [✎] Kit Editor renders the 4 Armor Slots on the left, the 9x4 Left-to-Right Inventory Grid in the center, and the Offhand Slot on the right using actual 2D item textures (minecraft:items, minecraft:blocks, minecraft:gui).
• 1-Click Hand Assignment & Overwriting: Hover any slot in the Dialog to inspect its full Minecraft item tooltip, click any slot to replace it with the item in your main hand, or use Save My Inv: [All] [Inv] [Armor] to overwrite the kit (or just one section of a Full Kit) from your current gear.
• Interactive 54-Slot Chest Grid ([Slot Grid]): Launch a live 54-slot chest editor at any time to physically drag, drop, and rearrange items across the 36 storage, 4 armor, and 1 offhand slots.

4. In-Menu Armor Trim Studio ([Trim Studio])

• Live 2D Trimmed Armor Preview: Customize armor trims directly inside the Dialog menu without spawning world entities.
• All 18 Patterns & 11 Materials: Apply any of the 18 Trim Patterns (Silence, Bolt, Flow, Spire, Ward, Eye, Rib, Vex, Tide, Snout, Sentry, Dune, Coast, Wild, Wayfinder, Shaper, Raiser, Host) and 11 Trim Materials (Amethyst, Gold, Diamond, Netherite, Emerald, Redstone, Lapis, Quartz, Copper, Iron, Resin) to a single armor piece or All 4 Pieces at Once, and watch the 2D trimmed armor sprites update live on the left.

5. Potion Effects Engine with Native Level & Duration Sliders

• 26 Selectable Effects (/qk potions <kit>): Attach custom potion effects (Speed, Strength, Fire Resistance, Regeneration, Resistance, Jump Boost, Invisibility, Absorption, Wind Charged, Weaving, Oozing, etc.) that automatically apply when the kit is equipped.
• Native Number-Range Sliders: Clicking any effect opens two DialogInput.numberRange sliders with live numeric indicators:
  • Effect Level Slider: 1 to 10 (step 1).
  • Effect Duration Slider: 30 sec to 960 sec / 16 mins (in 30 sec intervals).

6. Smart Equipping, Open-Slot Verification & Per-Life Claim Limits

• Type-Specific Clear & Replace vs. Safe Merge:
  • When Replace (☑) is enabled (default), equipping clears only the slots belonging to that kit type (e.g., an a_ Armor Kit only clears the 4 armor slots; an i_ Inventory Kit only clears storage + offhand).
  • When Replace (☐) is unchecked, QKits verifies that the player has enough empty slots to fit every item before equipping—if not, it cancels the equip and tells the player how many slots to free up so items never drop on the ground.
• Per-Life / Lobby-Visit Claim Limits & Cooldowns: Configure public kits to Once Per Life / Lobby Visit (default), 0s, 10s, 30s, 1m, or 5m. When set to Once Per Life / Lobby Visit, non-OPs can claim the kit once per round, and their claim lock automatically resets when they die in a world or visit the QWorlds Void Lobby (e.g., after a round or when hit with the Lobby Kick Stick).
• QWorlds Void Lobby Protection Lock: Automatically blocks non-OP players from claiming kits while standing inside qwlobby_hub so lobby relics are never overwritten.

7. Lossless Paper 1.21.11 Binary NBT Serialization

• Encodes items using Paper's native ItemStack.serializeAsBytes() / ItemStack.deserializeBytes() in Base64 inside an asynchronously saved kits.yml file.
• Preserves 100% of item data: MiniMessage hex gradients, custom small-caps fonts, enchantments, custom durability, unbreakable flags, armor trims, attribute modifiers, potion contents, and filled Shulker Boxes or Bundles.

---

Command & Permission Reference

Player Commands

• /qk (or /kit, /kits) — Opens the Public Kit Selector Dialog (or the full Admin Dashboard for OPs).
• /qk claim <kit | i_kit | a_kit> — Claims a public kit (tab-completion automatically filters to public kits).
• /qk search <query> — Filters the kit dashboard by name.

Admin & Operator Commands (qkits.admin or OP)

• /qk save <full|inv|armor> <name> — Saves your current loadout as a Full (<name>), Inventory (i_<name>), or Armor (a_<name>) kit.
• /qk give <kit | i_kit | a_kit> [player|@team|@box|@a|@p|@r|@s|r] [all|inv|armor] — Gives a kit (or just the inv or armor half of a Full Kit) to any player, QTeams @team, QWorlds @box, fractional selector (@red[50%], @box[1/2]), or random player (r).
• /qk extract <full_kit> <inv|armor> [target] — Extracts only the Inventory+Offhand or Armor from a Full Kit.
• /qk update <kit | i_kit | a_kit> [all|inv|armor] — Overwrites a saved kit (or a specific section of a Full Kit) from your current inventory.
• /qk edit <kit | i_kit | a_kit> — Opens the Kit Editor Dialog for that kit.
• /qk potions <kit | i_kit | a_kit> — Opens the Potion Effects & Sliders Dialog.
• /qk delete <kit | i_kit | a_kit> — Opens the Delete Confirmation Dialog.
• /qk perm <kit | i_kit | a_kit> <op|everyone|toggle> — Sets whether non-OP players can claim the kit.
• /qk clearmode <kit | i_kit | a_kit> <on|off|toggle> — Toggles whether equipping clears target slots first.
• /qk cooldown <kit | i_kit | a_kit> <once|0|10|30|60|300> — Sets the claim limit/cooldown for non-OP players.
• /qk icon <kit | i_kit | a_kit> <hand|auto|material> — Customizes the kit's display icon while keeping its name intact.
• /qk reload — Reloads kits.yml from disk.

---

Server Requirements & Soft Dependencies

• Server Software: Paper or Purpur 1.21.11.
• Java Runtime: Java 21.
• Soft Dependencies:
  • QTeams (2.0.0+) — Enables @team kit distribution and cross-plugin navigation.
  • QWorlds (3.0.0+) — Enables @box kit distribution, fractional selectors, and Void Lobby claim protection.