> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/plugins/muhelperpickup.md).

# 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

`Data/Plugins/World/MuHelperPickup.xml`

## System Architecture

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

**GameServer (this plugin)**:

* Loads item category definitions from XML
* Sends category data to the client on connect
* 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. The client stores these definitions and applies them based on its pickup logic.

### Level Matching Algorithm

Category membership is resolved with a two-pass match:

1. **Exact match**: item's Section, Index, **and Level** exactly match an entry
2. **Any-level match**: item's Section and Index match an entry whose Level is `255`

Exact matches win over any-level matches.

### 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.

### Failed-Pickup Blacklist

When MuHelper asks the server to pick up a ground item and the server rejects it (the item is out of range, already taken, no free inventory slot, or otherwise not grantable), the client marks that specific ground item as failed and skips it for 5 seconds before trying again. This stops MuHelper from spamming pickup requests at an item it cannot grab and getting stuck on it instead of moving to the next target. No configuration controls this; it applies to every pickup category. There is nothing to tune in this file.

### Category IDs

Categories the plugin ships with:

| ID  | Name      |
| --- | --------- |
| `0` | Zen       |
| `1` | Jewel     |
| `2` | Excellent |
| `3` | Ancient   |
| `4` | Extra     |

Other server features (custom events, reward systems) may reference these IDs when deciding what counts as a pickup category.

## 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
* Custom client handles categories differently than standard MU Online
* Client checkbox settings override server configuration

**Solution**: Verify MuHelper is running. Test with the standard Season 6 client first to confirm server configuration is correct.
{% 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.
{% 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](/docs/data/item/item.md) - item definitions and attributes referenced by `Section`/`Index`/`Level`
* [ItemDrop Configuration](/docs/data/item/itemdrop.md) - monster drop tables that produce the items this plugin filters
* [common.dat](/docs/gameserver/common-dat.md) - per-server identity; category data is sent once per connect on this server
* [command.dat](/docs/gameserver/command-dat.md) - unrelated to pickup but listed for cross-reference when tuning class loadouts