iPlugin | Item Grouping

Overview

The item grouping system allows you to organize related items together for easier management and browsing. Through grouping, you can create a hierarchical item directory, making it simpler for players to find the items they need.

Basic Concepts

What is Item Grouping

Item grouping refers to classifying and organizing items based on type, purpose, or other criteria. Each group can contain multiple items and can also include sub-groups, forming a tree-like structure.

Functions of Grouping

Item Organization: Manage a large number of items by categorizing them into groups
Easy Browsing: Players can quickly find items through the group menu
Hierarchical Management: Support multi-level grouping to create complex item directories

Creating Item Groups

Method 1: Folder-Based Grouping

The simplest way to group items is by using a folder structure:

swords.yml [Sword Items]

bows.yml [Bow Items]

helmets.yml [Helmets]

chestplates.yml [Chestplates]

potions.yml [Potions]

food.yml [Food]

The system automatically creates groups based on the folder structure, with folder names serving as group names.

Method 2: Configuration File-Based Grouping

Define custom groups using the __group__ node in YAML files:

# weapons.yml
__group__:
  name: 'Weapon & Armor'
  priority: 1
  display:
    icon: diamond_sword
    name: '&cWeapon & Armor'
    lore:
      - '&7Various powerful weapons'
 
# Items in the group
magic_sword:
  icon: diamond_sword
  name:
    item_name: '&6Magic Sword'
 
fire_bow:
  icon: bow
  name:
    item_name: '&cFlame Bow'

Group Configuration Options

Basic Configuration

Configuration Item	Description	Example
`name`	Display name of the group	`'Weapon & Armor'`
`priority`	Sorting priority (smaller numbers appear first)	`1`
`display`	Display icon of the group in the menu	See example below

Display Configuration

__group__:
  name: 'Legendary Equipment'
  priority: 1
  display:
    icon: diamond_chestplate
    name: '&6Legendary Equipment'
    lore:
      - '&7Rare legendary-grade equipment'
      - '&7Click to view all items'

Group Hierarchical Structure

Multi-Level Grouping

You can create nested multi-level group structures:

melee.yml [Melee Weapons]

ranged.yml [Ranged Weapons]

light.yml [Light Armor]

heavy.yml [Heavy Armor]

potions.yml [Potions]

scrolls.yml [Scrolls]

The system automatically handles parent-child relationships and generates a complete path structure.

The system automatically creates a browsable menu interface for groups:

Group Icon: Displays a representative icon for the group
Item Count: Shows the number of items contained in the group
Hierarchical Navigation: Supports switching between different levels

Players can open the group menu using the following commands:

# Open the root group menu
/zaphkiel list
 
# Open a specific group menu
/zaphkiel list weapons

Group Display Icons

Auto-Generated Icons

If no custom icon is configured, the system automatically generates a group icon:

With Items: Randomly selects one item from the group as the icon
Without Items: Uses the default minecart with chest icon
Display Info: Automatically adds the group name and item count

Custom Icons

You can customize the icon in the group configuration:

__group__:
  name: 'Magical Items'
  display:
    icon: enchanted_book
    name: '&dMagical Items'
    lore:
      - '&7Mysterious items filled with magic'
      - '&7Contains <item_count> items'

Practical Group Examples

Group by Type

# weapons.yml
__group__:
  name: 'Weapons'
  priority: 1
 
# Melee weapons
iron_sword:
  icon: iron_sword
  name:
    item_name: '&7Iron Sword'
 
diamond_sword:
  icon: diamond_sword
  name:
    item_name: '&bDiamond Sword'

Group by Tier

# legendary_items.yml
__group__:
  name: 'Legendary Items'
  priority: 1
 
legendary_sword:
  icon: diamond_sword
  name:
    item_name: '&6Legendary Sword'
  data:
    tier: 'legendary'
 
legendary_bow:
  icon: bow
  name:
    item_name: '&6Legendary Bow'
  data:
    tier: 'legendary'

Group by Function

# utility_items.yml
__group__:
  name: 'Utility Items'
  priority: 3
 
teleport_scroll:
  icon: paper
  name:
    item_name: '&bTeleport Scroll'
 
healing_potion:
  icon: potion
  name:
    item_name: '&cHealing Potion'

Usage Tips

1. Logical Group Structure

Create a clear hierarchical group structure:

Melee Weapons

Ranged Weapons

Light Armor

Heavy Armor

2. Priority Settings

Control the display order of groups in the menu using priority:

# Important groups with smaller priority numbers
__group__:
  priority: 1  # Appears first
 
# Secondary groups with larger priority numbers
__group__:
  priority: 10  # Appears later

3. Descriptive Naming

Use clear group names and descriptions:

__group__:
  name: 'Beginner Equipment'
  display:
    name: '&aBeginner Equipment'
    lore:
      - '&7Basic equipment suitable for new players'
      - '&7Inexpensive and easy to obtain'

Item Grouping