Kit Setup

How to create, update, and manage kits that players use during matches.

Creating a Kit

1. Equip your full layout: place the items in your inventory and hotbar, wear your armor, and assign offhand items.
2. Run the command: /kit create KitName to save your current inventory configuration.
3. (Optional) Hold the item you want to represent the kit in selection GUIs and run: /kit seticon KitName

Updating an Existing Kit

To overwrite a kit's item slots, arrange the new layout in your inventory and execute:

/kit setinv KitName

To modify only the GUI icon representation:

# Hold the new icon item in your main hand, then:
/kit seticon KitName

Build Mode (Kit and Arena Must Match)

Build mode marks whether a kit is used for block-building matches. Set it with:

/kit build <name> <true|false>

This must match the linked arena's build mode (/arena build). If they differ, matchmaking ignores the arena and players may see No arenas available for this kit.

Build-Compatible Kits (Block Whitelist)

For build kits, you can optionally restrict which block types players may place and break:

/kit build Bridge true
# Hold the whitelist block (e.g. sandstone, glass) and run:
/kit allowblock Bridge
# Repeat for each block type you wish to whitelist

/kit allowblock also enables build mode automatically. If the whitelist is empty, any block can be placed in a build-enabled arena. If blocks are whitelisted, only those types are allowed during combat.

Kit Auto-Ignition (TNT & Creepers)

Enable automatic ignition for kit matches using:

/kit autoignite <name> [true|false]

When auto-ignite is enabled for a kit:

• TNT Blocks: Placing a TNT block instantly primes it into a live TNTPrimed entity (80 ticks fuse countdown, primed sound, and damage attributed directly to the placing player).
• Creeper Spawn Eggs: Spawning a Creeper instantly ignites it into its white-flashing explosion countdown, and awards kill credit to the spawner if the blast eliminates an opponent.

No Fall Damage & Crafting Settings

• /kit nofalldamage <name> [true|false]: Toggles whether players take fall damage during matches using this kit.
• /kit crafttable <name>: Toggles crafting table usability during matches with this kit.

Kit Editor GUI (For Players)

Players can customize and rearrange item placements within their personal copy of a kit layout. This does not alter the base kit template generated by the administrator. Open the layout editor using:

/kiteditor          # Opens the kit selector GUI
/kiteditor NoDebuff # Directly launches the editor workspace for NoDebuff

This editor provides a drag-and-drop workspace where players can save custom layouts for matchmaking queues.

VIP Preferences inside the Kit Editor

• Armor Trimmer: Customizes patterns on armor pieces (Requires shyamduels.practice.armortrimmer.use).
• Shield Customizer: Applies layers and banner pattern options to shields (Requires shyamduels.practice.shieldcustomizer.use).
• Shulker Box Editor: Edits the items inside shulker boxes (Requires shyamduels.practice.shulkereditor.use).
• Virtual Enchanting: Applies enchants to gear (Requires shyamduels.practice.enchanttable.use).

All virtual practice features can be inherited by granting the parent permission node shyamduels.vip.

Custom Kits Builder

The Custom Kits builder system enables players to assemble personalized kits from category selections. It matches players using base configs defined in the configuration files.

• Players build customized configurations via /kitcreator.
• Players choose or modify their custom profiles using /customkits.
• Admins configure GUI categories and items via /shyamduels customkits edit-category.

Exhaustive Kit Setup Command Reference

Below is a complete reference guide of commands for registering, editing, and deleting kit configurations (requires shyamduels.admin):

Kit Categories System

An enterprise-grade hierarchical categorization and auto-pagination system designed to declutter large kit rosters, streamline matchmaking navigation, and provide a polished user experience across all kit-related menus.

1. Architectural Overview & Design Philosophy

Modern competitive PvP servers often feature dozens of distinct game modes and loadouts (such as NoDebuff, Debuff, Gapple, Combo, Sumo, BuildUHC, Boxing, FinalUHC, BedFight, Bridge, and Bow). Presenting 30+ kits in a single unorganized menu overwhelms players and impairs navigation speed.

The Kit Category System introduces a structured Two-Tier Hierarchy:

• Tier 1 (Root Menu): Displays top-level Category Items (e.g. PotPvP, Sword PvP, UHC & Rod, Modern Combat) alongside any remaining Uncategorized Kits.
• Tier 2 (Category Sub-Menu): Clicking a category item opens a dedicated sub-menu rendering only the kits assigned to that specific category, equipped with live queue statistics, sub-menu pagination, and a context-aware ◀ BACK navigation button.

2. Comprehensive GUI Integrations

The Category System is deeply integrated across all player-facing and administrative interfaces in ShyamDuels:

Which Sub-GUI Opens & Where to Edit Its Layout

When a player clicks a category item, a dedicated sub-menu opens displaying the kits linked to that category. You can customize the sub-menu layout either globally via the menu YAML files or per-category directly inside each category's own YAML file:

How to Toggle Between Global and Per-Category Layout

You can easily switch any category between the Global Default Layout (configured in menus/queue-kit.yml and menus/duel.yml) and a Per-Category Custom Layout in two ways:

Method 1: The sub-menu.enabled Toggle (Recommended)

Inside plugins/ShyamDuels/categories/<category_id>.yml, use the enabled boolean:

A. To use the Global Default Layout:

yaml# Global Mode: Inherits global theme from menus/queue-kit.yml
sub-menu:
  enabled: false

B. To use a Custom Per-Category Layout:

yaml# Per-Category Mode: Activates unique design overrides for this category
sub-menu:
  enabled: true
  title: "<gradient:#FF1D54:#FF7B00>PotPvP Queue</gradient> &8| &7<mode>"
  size: 54
  border: RED_STAINED_GLASS_PANE
  kit-slots: [10, 11, 12, 13, 14, 15, 16]

Method 2: Omit or Include the sub-menu: Section

• Global Mode: Simply do not include the sub-menu: section in the category's YAML file. It will automatically inherit all global styles.
• Custom Mode: Add the sub-menu: section whenever you want custom borders, sizes, or slots for that category.

3. Auto-Pagination Engine

Both root menus and category sub-menus are powered by an intelligent, mathematical pagination engine (GuiPagination):

• Dynamic Page Calculation: Computes totalPages = ceil(itemCount / contentSlotsPerPage) on the fly based on the target menu's configured slot array.
• Safe Page Clamping: Automatically bounds the requested page between 0 and totalPages - 1, preventing out-of-bounds GUI exceptions.
• Adaptive Navigation Bar:
  • When total pages > 1, renders Previous Page (◀), Page Information indicator (Page X of Y), and Next Page (▶) controls in their configured slots.
  • When inside a category sub-menu, automatically injects a ◀ BACK button allowing players to instantly return to the root category selection.

4. Hierarchical Depth & Sub-Category Support

A frequent question among server administrators is whether categories can contain sub-categories:

• The 2-Level Standard: In competitive Minecraft PvP, player UX research overwhelmingly indicates that a 2-Tier Hierarchy (Root Categories → Kits) provides the highest retention and lowest bounce rate. Players can navigate to any kit within exactly two clicks (Click Category → Click Kit to Queue).
• Sub-Category Compatibility: The underlying KitCategory architecture supports arbitrary hierarchical grouping. If your network requires multi-level nested folders (e.g. Competitive → PotPvP → NoDebuff), each category ID acts as a distinct routing node.

5. Step-by-Step: Creating & Designing Category UI

Follow these steps to create, style, and populate your kit categories with custom icons, colors, and live counter lores:

1. Create the Category:
   Execute the creation command specifying a unique identifier key and initial display name:

   /kit category create potpvp &#FF5555&lPotPvP &7Kits

2. Set the Category GUI Icon:
   Hold any item in your main hand (including Nexo 3D custom items, items with CustomModelData, or custom heads) and execute:

   /kit category seticon potpvp

3. Style the Display Name (Gradients & Hex Colors):
   You can update the category title at any time using MiniMessage tags or Hex codes:

   /kit category setname potpvp <gradient:#FF1D54:#FF7B00><b>PotPvP Modes</b></gradient>

4. Link Kits to the Category:
   Add existing registered kits into this category:

   /kit category addkit potpvp NoDebuff
   /kit category addkit potpvp Debuff
   /kit category addkit potpvp Gapple

5. Customize Lore & UI Appearance in categories.yml:
   Open plugins/ShyamDuels/categories.yml to fine-tune lore lines, add live counter placeholders, and specify fixed GUI slots:

   yamlcategories:
     potpvp:
       display-name: "<gradient:#FF1D54:#FF7B00><b>PotPvP Modes</b></gradient>"
       icon:
         material: SPLASH_POTION
         custom-model-data: 1001
         # nexo: "potpvp_icon"
       slot: 11 # Specific slot in GUI (or -1 for automatic placement)
       lore:
         - "&7Competitive potion combat modes."
         - ""
         - "&fKits Included: &e<kits_count>"
         - "&fQueued: &a<queued> &7| &fPlaying: &b<playing>"
         - ""
         - "&eClick to browse kits!"
       kits:
         - "nodebuff"
         - "debuff"
         - "gapple"

6. Reload and Verify:
   Apply configuration changes instantly in-game without rebooting:

   /kit category reload

   Open /queue or /duel <player> to test your new category layout.

5. How Kit and Category Ordering Works (Replacing data/order.yml)

You can easily control how normal kits, categories, and glass panes look in every GUI using clean YAML files:

yamlkits:
  - "NoDebuff" # 1st kit
  - "Debuff"   # 2nd kit
  - "Gapple"   # 3rd kit

yamlkit-slots: [10, 12, 14, 16]
# Slots 11, 13, 15 will have glass panes!

6. In-Game Admin Command Reference

All category administration is managed under the base command /kit category (or aliases /kits category, /shyamkits category). All arguments feature intelligent context-aware tab completion:

7. Per-Category Configuration File Structure (categories/<id>.yml)

Each category is saved in its own file under plugins/ShyamDuels/categories/<id>.yml. Below is an easy example configuration:

yaml# ==============================================================================
# Category Configuration: potpvp.yml
# Path: plugins/ShyamDuels/categories/potpvp.yml
# ==============================================================================

id: "potpvp"
display-name: "<gradient:#FF1D54:#FF7B00><b>PotPvP Modes</b></gradient>"
slot: 11 # Slot in main menu (-1 for auto placement)

# Optional Permission: Players need this permission to open this category (leave blank for everyone)
permission: "shyamduels.category.potpvp"

# Category Icon (supports Nexo 3D items, CustomModelData, or regular items):
icon:
  material: SPLASH_POTION
  custom-model-data: 1001
  # nexo: "potpvp_icon"
  # item-model: "minecraft:custom_potion"

# Lore shown on the category item in the menu:
lore:
  - "&7Competitive potion fighting modes."
  - ""
  - "&fKits: &e<kits_count>"
  - "&fQueued: &a<queued> &7| &fPlaying: &b<playing>"
  - ""
  - "&eClick to view kits!"

# List of kits inside this category:
kits:
  - "NoDebuff"
  - "Debuff"
  - "Gapple"

# Optional Custom Sub-Menu Design (leave out to use default menus/queue-kit.yml):
sub-menu:
  enabled: true
  title: "<gradient:#FF1D54:#FF7B00>PotPvP Queue</gradient> &8| &7<mode>"
  size: 54
  border: RED_STAINED_GLASS_PANE
  kit-slots:
    - 10
    - 11
    - 12
    - 13
    - 14
    - 15
    - 16

8. Supported Placeholders in Category Lore

The following dynamic placeholders are evaluated at runtime when category items are rendered in menus: