# MuHelperPickup

Defines item lists for the five MuHelper pickup categories. The server transmits these category definitions to clients on connect, and the client uses them to control automatic item pickup behavior.

## File Location

`GameServer/Data/Plugins/MuHelperPickup.xml`

## System Architecture

{% hint style="info" %}
**Client-Server Responsibility Split**

**GameServer (this plugin)**:

* Loads item category definitions from XML
* Sends category data to client via packet 0xBF 0x52 on connect
* Provides API for server-side category checks (if needed)
* Does NOT implement actual pickup logic

**Client**:

* Receives category definitions from server
* Makes all pickup decisions based on these lists
* Applies MuHelper checkbox settings
* Actually performs the item pickup

This is a **data transmission system** - the server defines what items belong in each category, but the client decides when to pick them up.
{% endhint %}

## How MuHelper Pickup Works

MuHelper has five pickup categories. Based on the standard MU Online client behavior, these categories function as follows:

| Category      | Typical Client Behavior                                                                                     |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| **Zen**       | Controlled by "Pick up Zen" checkbox                                                                        |
| **Jewel**     | Controlled by "Pick up Jewels" checkbox - picks up items in this list                                       |
| **Excellent** | Controlled by "Pick up Excellent" checkbox - typically auto-detects Excellent items + includes listed items |
| **Ancient**   | Controlled by "Pick up Ancient/Set" checkbox - typically auto-detects Set items + includes listed items     |
| **Extra**     | Typically always active (no checkbox) - server-controlled auto-pickup                                       |

{% hint style="warning" %}
**Client Implementation Dependent**: The actual behavior depends on your client implementation. Custom clients may handle these categories differently. This documentation describes typical MU Online Season 6 client behavior.
{% endhint %}

### Category Behavior Details (Client-Dependent)

{% hint style="info" %}
The following describes **typical** client behavior. Your specific client implementation may vary.
{% endhint %}

**Jewel Category**

* Typically controlled by "Pick up Jewels" checkbox in MuHelper UI
* Picks up items explicitly listed in this category
* Use for jewels and valuable crafting materials

**Excellent Category**

* Typically controlled by "Pick up Excellent" checkbox
* Standard clients **auto-detect** items with Excellent attribute (Option1)
* Items listed here can be **force-included** even without Excellent attribute
* Use to include special items that should be treated as excellent

**Ancient Category**

* Typically controlled by "Pick up Ancient/Set" checkbox
* Standard clients **auto-detect** items with Set attribute (ExtOption)
* Items listed here can be **force-included** even without Set attribute
* Use to include special items that should be treated as ancient

**Extra Category**

* Typically **always active** (no checkbox) when MuHelper is running
* Server-controlled auto-pickup category
* Use for valuable event items, boxes, or server-specific drops
* In standard clients, players cannot disable this category

{% hint style="info" %}
The Extra category is particularly useful for ensuring valuable items are never missed, regardless of player checkbox settings. However, verify that your client implementation supports this behavior.
{% endhint %}

## Item Identification

### Item Format

Each item is defined by three attributes:

| Attribute | Type   | Required | Description                                                |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| `Section` | int    | Yes      | Item category (0-15). See section table below.             |
| `Index`   | int    | Yes      | Item index within section (0-511)                          |
| `Level`   | int    | No       | Item level (0-15). Omit to match **any level**.            |
| `Name`    | string | No       | Human-readable name (documentation only, not used by game) |

### Item Sections

| Section | Item Type      | Examples                            |
| ------- | -------------- | ----------------------------------- |
| 0       | Swords         | Blade, Legendary Staff              |
| 1       | Axes           | Hand Axe, Battle Axe                |
| 2       | Maces/Scepters | Mace, Scepter                       |
| 3       | Spears         | Spear, Dragon Lance                 |
| 4       | Bows/Crossbows | Short Bow, Crossbow                 |
| 5       | Staffs         | Skull Staff, Serpent Staff          |
| 6       | Shields        | Small Shield, Dragon Shield         |
| 7       | Helms          | Bronze Helm, Dragon Helm            |
| 8       | Armors         | Bronze Armor, Dragon Armor          |
| 9       | Pants          | Bronze Pants, Dragon Pants          |
| 10      | Gloves         | Bronze Gloves, Dragon Gloves        |
| 11      | Boots          | Bronze Boots, Dragon Boots          |
| 12      | Wings/Orbs     | Wings of Elf, Orb of Twisting Slash |
| 13      | Pets/Rings     | Guardian Angel, Ring of Ice         |
| 14      | Consumables    | Potions, Jewels, Boxes, Scrolls     |
| 15      | Scrolls        | Scroll of Archangel, Blood Bone     |

## Level-Based Item Variants

Some items share the same Section/Index but have different variants based on Level. This is common for event boxes and special items.

### Important Example: Section 14, Index 11

Section 14, Index 11 has **many different items** depending on level:

| Level | Item Name            |
| ----- | -------------------- |
| 0     | Box of Luck          |
| 1     | Star of Sacred Birth |
| 2     | Firecracker          |
| 6     | Gold Medal           |
| 7     | Box of Heaven        |
| 8     | Box of Kundun+1      |
| 9     | Box of Kundun+2      |
| 10    | Box of Kundun+3      |
| 11    | Box of Kundun+4      |
| 12    | Box of Kundun+5      |

### Level Matching Rules

**Specify Level** - Matches only that specific item variant:

```xml
<Item Section="14" Index="11" Level="0" Name="Box of Luck"/>
```

This picks up **only** Box of Luck, not other variants.

**Omit Level** - Matches **all variants** of that Section/Index:

```xml
<Item Section="14" Index="11" Name="All Box variants"/>
```

This picks up **all items** at Section 14, Index 11 regardless of level.

{% hint style="warning" %}
When defining items that have level variants, always specify the Level attribute unless you want to pick up ALL variants. Omitting Level will match any level of that item.
{% endhint %}

## Configuration Sections

### Category Element

Defines a pickup category containing a list of items.

| Attribute | Type   | Required | Valid Values                                                              | Description                                                                 |
| --------- | ------ | -------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `Name`    | string | Yes      | <p>Zen<br>Jewel (or Jewels)<br>Excellent<br>Ancient (or Set)<br>Extra</p> | Category name (case-insensitive). Aliases in parentheses are also accepted. |

### Item Element

Defines an item to include in the parent category.

| Attribute | Type   | Required | Valid Values | Description                                    |
| --------- | ------ | -------- | ------------ | ---------------------------------------------- |
| `Section` | int    | Yes      | 0-15         | Item section/category                          |
| `Index`   | int    | Yes      | 0-511        | Item index within section                      |
| `Level`   | int    | No       | 0-15         | Item level. If omitted, matches **any level**. |
| `Name`    | string | No       | Any text     | Human-readable name for documentation          |

## Item Encoding Format

The plugin encodes items as 32-bit DWORD values for efficient transmission to clients:

**Encoding Formula**: `(ItemCode << 8) | Level`

Where:

* `ItemCode = (Section * 512) + Index`
* `Level = 0-15` for specific item level
* `Level = 255 (0xFF)` means "any level" (when Level attribute is omitted in XML)

**Example Encoding**:

* `Section=14, Index=11, Level=0` (Box of Luck) → ItemCode=7179 → Encoded as `(7179 << 8) | 0 = 1837824`
* `Section=14, Index=11, Level omitted` (Any box variant) → ItemCode=7179 → Encoded as `(7179 << 8) | 255 = 1838079`

The server sends these encoded values to the client when players connect.

## Important Behavior

### Automatic Transmission on Connect

When a player connects, the server automatically sends all **non-empty** category definitions to the client using packet `0xBF 0x52` (subcode). The client stores these definitions and applies them based on its pickup logic.

### Category Packet Structure

Each category is sent as a separate packet:

**Packet Format**: `C2 [size] [size] BF 52 [categoryId] [itemCount] [items...]`

Packet breakdown:

* `C2` - Variable-length packet header
* `[size] [size]` - Packet size (WORD)
* `BF 52` - Opcode and subcode for MuHelper category data
* `[categoryId]` - BYTE (0-4) identifying the category
* `[itemCount]` - WORD count of items in this category
* `[items...]` - Array of DWORD encoded items (itemCode << 8 | level)

### Level Matching Algorithm

The server provides `IsItemInCategory()` API with two-pass matching:

1. **Exact match**: Check if item's Section, Index, **and Level** exactly match an entry
2. **Any-level match**: Check if item's Section and Index match an entry with Level=255

**Server API**:

```cpp
bool IsItemInCategory(int section, int index, int level, eMuHelperPickupCategory category);
```

This API is available for server-side features to check if an item is in a category, though the primary pickup logic is client-side.

### Empty Categories

If a category is empty (no items defined), **no packet is sent** to the client for that category. For Excellent and Ancient categories, this is acceptable since standard clients auto-detect items with Excellent/Set attributes anyway. The category list defines **additional** items to include.

### Server-Side API

While pickup logic is client-side, the plugin provides a server-side API for checking if an item belongs to a category:

```cpp
bool CMuHelperPickup::IsItemInCategory(int section, int index, int level, eMuHelperPickupCategory category);
```

**Category IDs**:

* `MUHELPER_PICKUP_ZEN = 0`
* `MUHELPER_PICKUP_JEWEL = 1`
* `MUHELPER_PICKUP_EXCELLENT = 2`
* `MUHELPER_PICKUP_ANCIENT = 3`
* `MUHELPER_PICKUP_EXTRA = 4`

This API can be used by other server-side features (custom events, reward systems, etc.) to check if items are in pickup categories.

## Examples

{% tabs %}
{% tab title="Basic Jewel Setup" %}
Standard jewel pickup configuration:

```xml
<Category Name="Jewel">
    <Item Section="14" Index="13" Name="Jewel of Bless"/>
    <Item Section="14" Index="14" Name="Jewel of Soul"/>
    <Item Section="14" Index="16" Name="Jewel of Life"/>
    <Item Section="14" Index="22" Name="Jewel of Creation"/>
    <Item Section="14" Index="41" Name="Gemstone"/>
    <Item Section="14" Index="42" Name="Jewel of Harmony"/>
    <Item Section="14" Index="43" Name="Lower Refining Stone"/>
    <Item Section="14" Index="44" Name="Higher Refining Stone"/>
    <Item Section="12" Index="15" Name="Jewel of Chaos"/>
</Category>
```

In standard clients, players enable "Pick up Jewels" checkbox to auto-pickup these items.
{% endtab %}

{% tab title="Event Boxes (Auto-Pickup)" %}
Configure valuable event boxes for the Extra category:

```xml
<Category Name="Extra">
    <!-- Pick up ONLY specific box variants -->
    <Item Section="14" Index="11" Level="0" Name="Box of Luck"/>
    <Item Section="14" Index="11" Level="7" Name="Box of Heaven"/>
    <Item Section="14" Index="11" Level="8" Name="Box of Kundun+1"/>
    <Item Section="14" Index="11" Level="9" Name="Box of Kundun+2"/>

    <!-- Pick up ALL variants of Old Scroll -->
    <Item Section="14" Index="17" Name="Old Scroll"/>
</Category>
```

In standard clients, Extra category items are always picked up automatically (no checkbox required).
{% endtab %}

{% tab title="Force-Include Special Items" %}
Include additional items in Excellent or Ancient categories:

```xml
<Category Name="Excellent">
    <!-- Include rare quest items in excellent category -->
    <Item Section="14" Index="50" Name="Special Quest Token"/>
</Category>

<Category Name="Ancient">
    <!-- Include custom server items in ancient category -->
    <Item Section="13" Index="100" Name="Custom Ring of Power"/>
</Category>
```

In standard clients, players with "Pick up Excellent" or "Pick up Ancient/Set" enabled will auto-pickup these items even though they don't have Excellent/Set attributes.
{% endtab %}

{% tab title="Level-Specific Variants" %}
Pick up only specific variants of multi-level items:

```xml
<Category Name="Extra">
    <!-- Pick up ONLY Gold Medal, not other variants -->
    <Item Section="14" Index="11" Level="6" Name="Gold Medal"/>

    <!-- Pick up ALL levels of Kundun boxes (8-12) -->
    <Item Section="14" Index="11" Level="8" Name="Box of Kundun+1"/>
    <Item Section="14" Index="11" Level="9" Name="Box of Kundun+2"/>
    <Item Section="14" Index="11" Level="10" Name="Box of Kundun+3"/>
    <Item Section="14" Index="11" Level="11" Name="Box of Kundun+4"/>
    <Item Section="14" Index="11" Level="12" Name="Box of Kundun+5"/>
</Category>
```

{% endtab %}

{% tab title="Custom Server Items" %}
Add server-specific valuable items to the Extra category:

```xml
<Category Name="Extra">
    <!-- Custom event currency -->
    <Item Section="14" Index="200" Name="Event Token"/>
    <Item Section="14" Index="201" Name="Raid Coin"/>

    <!-- Custom crafting materials -->
    <Item Section="14" Index="150" Name="Dragon Scale"/>
    <Item Section="14" Index="151" Name="Phoenix Feather"/>

    <!-- Custom boxes -->
    <Item Section="14" Index="175" Name="Premium Loot Box"/>
</Category>
```

In standard clients, Extra category helps ensure players never miss valuable custom items.
{% endtab %}
{% endtabs %}

## Common Issues

{% hint style="warning" %}
**Issue**: Items with level variants picking up wrong items

**Cause**: Level attribute omitted, causing all variants to be picked up

**Solution**: Always specify Level attribute for items that have level variants, unless you want to pick up all variants.
{% endhint %}

{% hint style="warning" %}
**Issue**: Players not picking up items as expected

**Cause**: Multiple possible causes:

* MuHelper may not be active on the client
* Client doesn't support packet 0xBF 0x52
* Custom client handles categories differently than standard MU Online
* Client checkbox settings override server configuration

**Solution**: Verify MuHelper is running. Test with standard Season 6 client first to confirm server configuration is correct. Check client logs for packet 0xBF 0x52 reception.
{% endhint %}

{% hint style="warning" %}
**Issue**: Category changes not applying to connected players

**Cause**: Category data is sent only on player connect

**Solution**: Players must reconnect after configuration changes. Alternatively, you can call the `BroadcastCategoryData()` function to resend to all connected players (requires server-side implementation).
{% endhint %}

{% hint style="info" %}
**Tip**: In standard clients, the Extra category is useful for items you want to ensure are never missed (event items, rare drops, valuable crafting materials). However, always verify that your specific client implementation supports this behavior.
{% endhint %}

## Configuration Template

```xml
<?xml version="1.0" encoding="utf-8"?>
<MuHelperPickup>

    <!-- JEWEL CATEGORY -->
    <!-- Standard clients: Controlled by "Pick up Jewels" checkbox -->
    <Category Name="Jewel">
        <Item Section="14" Index="13" Name="Jewel of Bless"/>
        <Item Section="14" Index="14" Name="Jewel of Soul"/>
        <Item Section="14" Index="16" Name="Jewel of Life"/>
        <Item Section="14" Index="22" Name="Jewel of Creation"/>
        <Item Section="12" Index="15" Name="Jewel of Chaos"/>
        <!-- Add more jewels here -->
    </Category>

    <!-- EXCELLENT CATEGORY -->
    <!-- Standard clients: Controlled by "Pick up Excellent" checkbox -->
    <!-- Standard clients auto-detect items with Excellent attribute -->
    <!-- Add items here to include them in excellent pickup -->
    <Category Name="Excellent">
        <!-- Example: <Item Section="0" Index="25" Name="Special Sword"/> -->
    </Category>

    <!-- ANCIENT CATEGORY -->
    <!-- Standard clients: Controlled by "Pick up Ancient/Set" checkbox -->
    <!-- Standard clients auto-detect items with Set attribute -->
    <!-- Add items here to include them in ancient pickup -->
    <Category Name="Ancient">
        <!-- Example: <Item Section="7" Index="30" Name="Special Helm"/> -->
    </Category>

    <!-- EXTRA CATEGORY -->
    <!-- Standard clients: Always active when MuHelper is running (no checkbox) -->
    <!-- Server-controlled auto-pickup for valuable items -->
    <Category Name="Extra">
        <Item Section="14" Index="11" Level="0" Name="Box of Luck"/>
        <Item Section="14" Index="11" Level="7" Name="Box of Heaven"/>
        <Item Section="14" Index="17" Name="Old Scroll"/>
        <!-- Add valuable event items and server-specific drops here -->
    </Category>

</MuHelperPickup>
```

## Related Configuration

* [Item Configuration](https://axiomemu.gitbook.io/docs/gameserver/item/item) - Item definitions and attributes
* [ItemDrop Configuration](https://axiomemu.gitbook.io/docs/gameserver/item/itemdrop) - Monster drop tables
