# EventItemBag

The EventItemBag system allows you to define reusable loot tables for monsters, events, and special items. When triggered, bags randomly select items from their pool based on configured rates and rules.

## File Locations

**Bag Registry:** `GameServer/Data/EventItemBagManager.xml` **Bag Definitions:** `GameServer/Data/EventItemBag/###␣-␣Name.xml`

The registry maps bag indices to trigger conditions (item type, monster class, or special value), while individual bag XML files define the actual loot tables.

## Dependencies

| Depends On                                                                        | Purpose                                                              |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [ItemOptionRate](https://axiomemu.gitbook.io/docs/gameserver/item/itemoptionrate) | Option rate indices used by extended bag Item entries (Option0-6)    |
| [ItemStack](https://axiomemu.gitbook.io/docs/gameserver/item/itemstack)           | Required for the `Count` attribute to take effect on stackable items |
| [SetItemType](https://axiomemu.gitbook.io/docs/gameserver/item/setitemtype)       | Used when `SetItemDropRate` triggers a random set item drop          |

## File Naming Convention

Bag files must follow this exact pattern:

```
###␣-␣Name.xml
```

* `###` = Three-digit bag index (000-999) matching EventItemBagManager.xml
* `␣` = Single space
* `-` = Hyphen
* `␣` = Single space
* `Name.xml` = Descriptive name with .xml extension

**Examples:**

* `000 - Box of Luck.xml`
* `012 - Blood Castle 1.xml`
* `051 - Game Master Box.xml`

## EventItemBagManager.xml Structure

Maps bag indices to trigger conditions.

| Attribute      | Type       | Description                                                                       |
| -------------- | ---------- | --------------------------------------------------------------------------------- |
| `Index`        | int        | Bag index (must match filename ###)                                               |
| `ItemIndex`    | int or `*` | Item type that triggers this bag (e.g., 7179 = Box of Luck). Use `*` for wildcard |
| `ItemLevel`    | int or `*` | Item level required to trigger. Use `*` for any level                             |
| `MonsterClass` | int or `*` | Monster class that drops this bag. Use `*` for any monster                        |
| `SpecialValue` | int or `*` | Event-specific trigger ID. Use `*` for any value                                  |

{% hint style="info" %}
At least one of ItemIndex+ItemLevel, MonsterClass, or SpecialValue must be specified. The system checks these in order when determining which bag to use.
{% endhint %}

### Trigger Examples

```xml
<!-- Box of Luck item (item 7179 level 0) -->
<Bag Index="0" ItemIndex="7179" ItemLevel="0" MonsterClass="*" SpecialValue="*"/>

<!-- Red Dragon monster (class 42) -->
<Bag Index="2" ItemIndex="*" ItemLevel="*" MonsterClass="42" SpecialValue="*"/>

<!-- Blood Castle 1 event (special value 0) -->
<Bag Index="12" ItemIndex="*" ItemLevel="*" MonsterClass="*" SpecialValue="0"/>
```

## Bag Configuration Formats

Bags support two formats: **Simple** and **Extended**.

### Simple Format

Randomly selects one item from a flat list. All items have equal probability.

```xml
<ItemBag>
    <BagConfig Name="Box of Luck"
               DropZen="1000"
               ItemDropRate="100"
               ItemDropCount="1"
               SetItemDropRate="0"
               ItemDropType="0"
               Fireworks="0"/>
    <Drop Cat="13" ItemIndex="0" MinLevel="0" MaxLevel="0"
          Skill="0" Luck="0" Option="0" Exc="0" Set="0" Socket="0"/>
    <Drop Cat="13" ItemIndex="1" MinLevel="0" MaxLevel="0"
          Skill="0" Luck="0" Option="0" Exc="0" Set="0" Socket="0"/>
</ItemBag>
```

### Extended Format

Weighted drops with sections, class requirements, and advanced options.

```xml
<ItemBag>
    <BagConfig Name="Starter Ring 80"
               DropZen="1000"
               ItemDropRate="100"
               ItemDropCount="1"
               SetItemDropRate="0"
               ItemDropType="0"
               Fireworks="0"/>

    <ExtendedBag>
        <BagInfo Index="1" DropRate="10000">
            <DropInfo Section="5" SectionRate="10000" Money="0"
                      OptionValue="0" RequireClass="1 0 0 0 0 0 0"/>
            <DropInfo Section="6" SectionRate="5000" Money="0"
                      OptionValue="0" RequireClass="0 1 0 0 0 0 0"/>
        </BagInfo>

        <ItemSection Id="5">
            <Item Index="6277" Level="3" Grade="0"
                  Option0="*" Option1="*" Option2="*" Option3="*"
                  Option4="*" Option5="*" Option6="*" Duration="1209600"/>
        </ItemSection>

        <ItemSection Id="6">
            <Item Index="6278" Level="3" Grade="0"
                  Option0="*" Option1="*" Option2="*" Option3="*"
                  Option4="*" Option5="*" Option6="*" Duration="1209600"/>
        </ItemSection>
    </ExtendedBag>
</ItemBag>
```

{% hint style="info" %}
If both `<Drop>` entries and `<ExtendedBag>` exist in the same file, the Extended format takes priority and Simple drops are ignored.
{% endhint %}

## BagConfig Attributes

Common configuration for both formats.

| Attribute         | Type   | Default | Description                                                                                                                                                          |
| ----------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`            | string | -       | Bag name (for reference only)                                                                                                                                        |
| `DropZen`         | int    | 0       | Zen amount to drop if item roll fails                                                                                                                                |
| `ItemDropRate`    | int    | 100     | Rate out of 100 for item drop chance. If check fails (random >= rate), drops DropZen instead. 100 = always try item, 0 = always drop zen                             |
| `ItemDropCount`   | int    | 1       | **Simple format only**: Number of drop attempts. Each attempt rolls ItemDropRate for item vs zen. **Extended format ignores this** and uses BagInfo DropRate instead |
| `SetItemDropRate` | int    | 0       | Rate out of 10000 for random set item instead of bag item (e.g., 100 = 1%)                                                                                           |
| `ItemDropType`    | int    | 0       | 0 = Fixed options, 1 = Randomize Skill/Luck and scale Option+3 inversely                                                                                             |
| `Fireworks`       | int    | 0       | **Simple format**: 1 = Send fireworks effect after all drops complete, 0 = No effect. **Extended format**: Ignored, use OptionValue & 1 in DropInfo instead          |

{% hint style="warning" %}
**Simple format**: `ItemDropCount` creates multiple drop attempts. Each attempt rolls `ItemDropRate` independently - you could get a mix of items and zen. Example: Count=5, Rate=50 might drop 3 items and 2 zen piles.

**Extended format**: `ItemDropCount` is IGNORED. Use multiple BagInfo entries if you want multiple drops.
{% endhint %}

## Simple Format: Drop Entries

Flat list of items with equal probability.

| Attribute   | Type       | Description                                                                                                                                                                                                                         |
| ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cat`       | int        | Item category (0-15)                                                                                                                                                                                                                |
| `ItemIndex` | int        | Item index within category                                                                                                                                                                                                          |
| `MinLevel`  | int        | Minimum item level (0-15)                                                                                                                                                                                                           |
| `MaxLevel`  | int        | Maximum item level (0-15). If same as MinLevel, fixed level. If higher, random level in range                                                                                                                                       |
| `Skill`     | int or `*` | 0 = No skill, 1 = Force skill, `*` = Use ItemOptionRate default rate logic                                                                                                                                                          |
| `Luck`      | int or `*` | 0 = No luck, 1 = Force luck, `*` = Use ItemOptionRate default rate logic                                                                                                                                                            |
| `Option`    | int or `*` | Fixed Option+X level (0-7 or 0-28). 0 = No option, `*` = Use ItemOptionRate default rate logic                                                                                                                                      |
| `Exc`       | int or `*` | Number of excellent options to force generate (0-6), `*` = Use ItemOptionRate default rate logic                                                                                                                                    |
| `Set`       | int or `*` | 0 = No set, 1 = Force set generation, `*` = Use ItemOptionRate default rate logic                                                                                                                                                   |
| `Socket`    | int or `*` | 0 = Use ItemOptionRate index 0 for socket generation, 1-5 = Force N sockets (0xFE placeholders), `*` = Use ItemOptionRate default rate logic                                                                                        |
| `Count`     | int        | Stack size to assign when the item drops. 0 or omitted = default behavior (stack of 1). Only applies to items registered as stackable in ItemStack.xml. See [ItemStack](https://axiomemu.gitbook.io/docs/gameserver/item/itemstack) |

### ItemDropType Behavior

When `ItemDropType="1"`:

* **Skill**: Randomized (50% chance)
* **Luck**: Randomized (50% chance)
* **Option**: Scaled inversely by MaxItemOption. Higher option values become less likely
* **Exc**: If any excellent option is set, forces Skill=1

{% hint style="info" %}
Use `ItemDropType="1"` for natural monster drops with variable quality. Use `ItemDropType="0"` for fixed event rewards.
{% endhint %}

## Extended Format: BagInfo

Defines weighted drop pools with class requirements.

| Attribute  | Type | Description                                                                 |
| ---------- | ---- | --------------------------------------------------------------------------- |
| `Index`    | int  | BagInfo index (must be unique within file, arbitrary number)                |
| `DropRate` | int  | Rate out of 10000 for this bag to activate (e.g., 10000 = 100%, 5000 = 50%) |

{% hint style="warning" %}
**IMPORTANT**: Each BagInfo is processed independently. If you define multiple BagInfo entries, EACH one rolls its DropRate and can drop items. This allows a single bag to drop multiple items. Most bags should only have ONE BagInfo with DropRate=10000 for guaranteed single drop.
{% endhint %}

## Extended Format: DropInfo

Defines sections within a BagInfo. One section is randomly selected based on weights and class requirements.

| Attribute      | Type   | Description                                                                                                                                                                                                           |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Section`      | int    | ItemSection Id to use if selected                                                                                                                                                                                     |
| `SectionRate`  | int    | Weight for weighted random selection. Higher = more likely                                                                                                                                                            |
| `Money`        | int    | Zen amount to drop if section is selected but has no valid items                                                                                                                                                      |
| `OptionValue`  | int    | Bitflags: Bit 0 (`+1`) = Send fireworks for this drop, Bit 1 (`+2`) = Check party member classes instead of just bag opener. Can combine (e.g., `3` = fireworks + party check)                                        |
| `RequireClass` | string | Space-separated minimum ChangeUp requirement per class: `DW DK FE MG DL SU RF`. Value is minimum (ChangeUp+1). 0=block, 1=allow base class, 2=require 1st ChangeUp+, 3=require 2nd ChangeUp+, 4=require 3rd ChangeUp+ |

### Class Requirement Format

```
"1 0 0 0 0 0 0"
```

Position mapping:

1. Dark Wizard (0=blocked, 1=base class, 2=1st ChangeUp+, 3=2nd ChangeUp+, 4=3rd ChangeUp+)
2. Dark Knight
3. Fairy Elf
4. Magic Gladiator
5. Dark Lord
6. Summoner
7. Ragefighter

**Example:** `"1 0 0 0 0 0 0"` = Only Dark Wizards, base class and above (any ChangeUp) **Example:** `"2 2 0 0 0 0 0"` = Only DW/DK with at least 1st class quest completed **Example:** `"3 3 3 0 0 0 0"` = Only DW/DK/FE with at least 2nd class quest completed

{% hint style="info" %}
If multiple DropInfo entries match the player's class, they compete via SectionRate weights. If none match, NO drop occurs (the DropInfo is skipped entirely). The `Money` attribute is only used if a DropInfo IS selected but its ItemSection is empty or invalid.
{% endhint %}

## Extended Format: ItemSection

Defines item pools referenced by DropInfo sections.

**ItemSection attributes:**

* `Id` = Section identifier (referenced by DropInfo)

**Item attributes:**

| Attribute  | Type       | Description                                                                                                                                                                                                                         |
| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Index`    | int        | Item index (full index, e.g., 6277 = 12\*512 + 277)                                                                                                                                                                                 |
| `Level`    | int        | Base item level (0-15)                                                                                                                                                                                                              |
| `Grade`    | int        | Excellent option bitmask to use if Option4 rate generates 0 excellent options (fallback value when no excellent options roll)                                                                                                       |
| `Option0`  | int or `*` | Level generation rate index. `*` = Use default. See ItemOptionRate GetItemOption0                                                                                                                                                   |
| `Option1`  | int or `*` | Skill option rate index. `*` = Use default. See ItemOptionRate GetItemOption1                                                                                                                                                       |
| `Option2`  | int or `*` | Luck option rate index. `*` = Use default. See ItemOptionRate GetItemOption2                                                                                                                                                        |
| `Option3`  | int or `*` | Option+X rate index. `*` = Use default. See ItemOptionRate GetItemOption3                                                                                                                                                           |
| `Option4`  | int or `*` | Excellent option rate index. `*` = Use default. See ItemOptionRate GetItemOption4                                                                                                                                                   |
| `Option5`  | int or `*` | Set option rate index. `*` = Use default. See ItemOptionRate GetItemOption5                                                                                                                                                         |
| `Option6`  | int or `*` | Socket option rate index. `*` = Use default. See ItemOptionRate GetItemOption6                                                                                                                                                      |
| `Duration` | int        | Time-limited item duration in seconds. 0 = Permanent. 1209600 = 14 days                                                                                                                                                             |
| `Count`    | int        | Stack size to assign when the item drops. 0 or omitted = default behavior (stack of 1). Only applies to items registered as stackable in ItemStack.xml. See [ItemStack](https://axiomemu.gitbook.io/docs/gameserver/item/itemstack) |

{% hint style="info" %}
Option0-6 reference **ItemOptionRate.xml** indices, not direct values. Use `*` to apply default rate logic, or specify an index for custom rates.
{% endhint %}

### Option Index System

All Option0-6 attributes reference rate tables in **ItemOptionRate.xml**:

* **Option0**: Level adjustment (can increase/decrease base level)
* **Option1**: Skill (0% or 100% chance depending on rate)
* **Option2**: Luck (0% or 100% chance depending on rate)
* **Option3**: Add option level (0-7 or 0-28, rate-based)
* **Option4**: Excellent options (generates 0-6 exc options by rate)
* **Option5**: Set bonus (generates set attribute by rate)
* **Option6**: Socket slots (generates 0-5 sockets by rate)

See [ItemOptionRate](https://axiomemu.gitbook.io/docs/gameserver/item/itemoptionrate) for rate index definitions.

## Stack Count (Count Attribute)

Both simple bag `<Drop>` rows and extended bag `<Item>` rows accept a `Count` attribute that controls the stack size of the dropped item.

### Rules

* If `Count` is omitted or `0`, the item drops with the default durability/stack value of 1 (unchanged behavior).
* If `Count` is greater than 0 **and** the item is registered as stackable in [ItemStack.xml](https://axiomemu.gitbook.io/docs/gameserver/item/itemstack), the item's stack count is set to that value.
* If the item is **not** registered as stackable in ItemStack.xml, `Count` is ignored and the item drops with a stack of 1. Setting `Count` on a non-stackable item has no effect.
* The stack count is stored in the same byte field as durability. For items where `Count > 1`, the durability field carries the count value to the client.
* Maximum value is 255 (stored as a single byte).

{% hint style="info" %}
Items that stack (jewels, potions, etc.) are defined in `GameServer/Data/Item/ItemStack.xml`. You can only use `Count` to control how many of a stackable item drop at once. Using `Count` on equipment or other non-stackable items does nothing.
{% endhint %}

{% hint style="warning" %}
Do not set `Count` higher than the item's `MaxStack` value defined in ItemStack.xml. The game does not enforce a cap at drop time, but the client may display or handle values above MaxStack incorrectly.
{% endhint %}

### Examples

Simple bag dropping 10 Jewels of Bless at once:

```xml
<Drop Cat="14" ItemIndex="13" MinLevel="0" MaxLevel="0"
      Skill="0" Luck="0" Option="0" Exc="0" Set="0" Socket="0" Count="10"/>
```

Extended bag dropping 5 Jewels of Soul at once:

```xml
<Item Index="7182" Level="0" Grade="0"
      Option0="*" Option1="*" Option2="*" Option3="*"
      Option4="*" Option5="*" Option6="*" Duration="0" Count="5"/>
```

## Important Behavior

### GetItem vs DropItem (Extended Format)

**GetItem** (used when bag opens into inventory):

* Processes BagInfo entries until ONE succeeds
* Returns the first item that passes all checks
* Ignores remaining BagInfo entries after first success
* Result: Maximum 1 item per bag open

**DropItem** (used when bag drops items on ground):

* Processes ALL BagInfo entries
* Each BagInfo that passes DropRate check drops an item
* Result: Can drop multiple items if multiple BagInfo entries succeed

{% hint style="info" %}
This difference allows tiered loot: when opened in inventory you get ONE item, but when dropped on ground (e.g., event reward) you can configure multiple guaranteed drops using multiple BagInfo entries with DropRate=10000.
{% endhint %}

### Selection Algorithm

**Simple Format:**

1. Repeat `ItemDropCount` times:
   * Roll random 0-99, if >= `ItemDropRate`, drop `DropZen` zen and continue to next iteration
   * Roll random 0-9999, if < `SetItemDropRate`, drop random set item and continue
   * Otherwise, pick random item from Drop list (equal probability) and drop it
2. If `Fireworks=1`, send fireworks effect after all drops

**Extended Format:**

1. For EACH BagInfo (can process multiple BagInfo per bag open):
   * Roll random 0-9999, if >= `DropRate`, skip this BagInfo entirely
   * Build list of DropInfo entries matching player class/ChangeUp requirements
   * If no DropInfo matches class, skip this BagInfo (no drop)
   * Select one DropInfo by weighted random (`SectionRate`)
   * Find ItemSection with matching Section Id
   * If section doesn't exist or is empty, drop `Money` zen
   * Otherwise, pick random item from section (equal probability)
   * Generate item options using Option0-6 rate indices via ItemOptionRate
   * If `OptionValue & 1`, send fireworks effect for this drop
2. Process continues for all BagInfo entries (can drop multiple items if multiple BagInfo pass their DropRate)

### Class Requirement Checking

* **OptionValue & 2 = 0**: Check only the player opening the bag
* **OptionValue & 2 = 2**: Check all party members. If any party member matches, that DropInfo is eligible

This allows party-wide class rewards where any qualifying member triggers the drop.

### Nested Bags

To reference another bag from a drop, add a `<Drop>` entry pointing to an item that has its own bag definition:

```xml
<!-- Parent bag references child bag item -->
<Drop Cat="14" ItemIndex="13" MinLevel="0" MaxLevel="0"
      Skill="0" Luck="0" Option="0" Exc="0" Set="0" Socket="0"/>
```

If item 14/13 has a bag definition in EventItemBagManager.xml, opening it triggers that bag's logic.

{% hint style="info" %}
This creates tiered rewards: outer box drops inner box, which drops final items. Useful for progressive reward systems.
{% endhint %}

## Examples

{% tabs %}
{% tab title="Simple Bag" %}
Fixed rewards with equal probability.

```xml
<ItemBag>
    <BagConfig Name="Blood Castle 1"
               DropZen="1000"
               ItemDropRate="100"
               ItemDropCount="1"
               SetItemDropRate="0"
               ItemDropType="0"
               Fireworks="0"/>
    <Drop Cat="12" ItemIndex="15" MinLevel="0" MaxLevel="0"
          Skill="0" Luck="0" Option="0" Exc="0" Set="0" Socket="0"/>
</ItemBag>
```

**Result:** Always drops Jewel of Bless. No randomness.
{% endtab %}

{% tab title="Variable Quality" %}
Random item quality using `ItemDropType="1"`.

```xml
<ItemBag>
    <BagConfig Name="Box of Luck"
               DropZen="1000"
               ItemDropRate="100"
               ItemDropCount="1"
               SetItemDropRate="0"
               ItemDropType="1"
               Fireworks="0"/>
    <Drop Cat="0" ItemIndex="6" MinLevel="4" MaxLevel="4"
          Skill="1" Luck="1" Option="1" Exc="1" Set="0" Socket="0"/>
    <Drop Cat="13" ItemIndex="8" MinLevel="0" MaxLevel="0"
          Skill="0" Luck="0" Option="2" Exc="0" Set="0" Socket="0"/>
</ItemBag>
```

**Result:** Randomly picks one item. Skill/Luck are randomized, Option is inversely scaled (higher values rarer), Exc forces Skill=1.
{% endtab %}

{% tab title="Class-Specific Rewards" %}
Different items based on character class.

```xml
<ItemBag>
    <BagConfig Name="Starter Ring 80"
               DropZen="1000"
               ItemDropRate="100"
               ItemDropCount="1"
               SetItemDropRate="0"
               ItemDropType="0"
               Fireworks="0"/>

    <ExtendedBag>
        <BagInfo Index="1" DropRate="10000">
            <DropInfo Section="5" SectionRate="10000" Money="0"
                      OptionValue="0" RequireClass="1 0 0 0 0 0 0"/>
            <DropInfo Section="6" SectionRate="10000" Money="0"
                      OptionValue="0" RequireClass="0 1 0 0 0 0 0"/>
        </BagInfo>

        <ItemSection Id="5">
            <Item Index="6277" Level="3" Grade="0"
                  Option0="*" Option1="*" Option2="*" Option3="*"
                  Option4="*" Option5="*" Option6="*" Duration="1209600"/>
        </ItemSection>

        <ItemSection Id="6">
            <Item Index="6278" Level="3" Grade="0"
                  Option0="*" Option1="*" Option2="*" Option3="*"
                  Option4="*" Option5="*" Option6="*" Duration="1209600"/>
        </ItemSection>
    </ExtendedBag>
</ItemBag>
```

**Result:** Dark Wizards get item 6277, Dark Knights get 6278. Other classes get nothing (Money=0).
{% endtab %}

{% tab title="Weighted Sections" %}
Different probabilities for reward tiers using SectionRate weights.

```xml
<ItemBag>
    <BagConfig Name="Lottery Box"
               DropZen="0"
               ItemDropRate="100"
               ItemDropCount="1"
               SetItemDropRate="0"
               ItemDropType="0"
               Fireworks="0"/>

    <ExtendedBag>
        <BagInfo Index="1" DropRate="10000">
            <DropInfo Section="1" SectionRate="7000" Money="0"
                      OptionValue="0" RequireClass="1 1 1 1 1 1 1"/>
            <DropInfo Section="2" SectionRate="2500" Money="0"
                      OptionValue="1" RequireClass="1 1 1 1 1 1 1"/>
            <DropInfo Section="3" SectionRate="500" Money="0"
                      OptionValue="1" RequireClass="1 1 1 1 1 1 1"/>
        </BagInfo>

        <ItemSection Id="1">
            <Item Index="7680" Level="0" Grade="0"
                  Option0="*" Option1="*" Option2="*" Option3="*"
                  Option4="*" Option5="*" Option6="*" Duration="0"/>
        </ItemSection>

        <ItemSection Id="2">
            <Item Index="7682" Level="0" Grade="0"
                  Option0="*" Option1="*" Option2="*" Option3="*"
                  Option4="*" Option5="*" Option6="*" Duration="0"/>
        </ItemSection>

        <ItemSection Id="3">
            <Item Index="7684" Level="0" Grade="0"
                  Option0="*" Option1="*" Option2="*" Option3="*"
                  Option4="*" Option5="*" Option6="*" Duration="0"/>
        </ItemSection>
    </ExtendedBag>
</ItemBag>
```

**Result:** ONE item per open. 70% chance of common reward (section 1), 25% rare with fireworks (section 2), 5% epic with fireworks (section 3). The SectionRate values create weighted random selection: 7000/(7000+2500+500) = 70% for section 1.
{% endtab %}

{% tab title="Stacked Item Drop" %}
Dropping a bundle of stackable items using the `Count` attribute.

Simple bag example - drops 10 Jewels of Bless per open:

```xml
<ItemBag>
    <BagConfig Name="Jewel Bundle"
               DropZen="0"
               ItemDropRate="100"
               ItemDropCount="1"
               SetItemDropRate="0"
               ItemDropType="0"
               Fireworks="0"/>
    <Drop Cat="14" ItemIndex="13" MinLevel="0" MaxLevel="0"
          Skill="0" Luck="0" Option="0" Exc="0" Set="0" Socket="0" Count="10"/>
</ItemBag>
```

Extended bag example - drops 5 Jewels of Soul from an event reward:

```xml
<ItemBag>
    <BagConfig Name="Event Jewel Reward"
               DropZen="0"
               ItemDropRate="100"
               ItemDropCount="1"
               SetItemDropRate="0"
               ItemDropType="0"
               Fireworks="1"/>

    <ExtendedBag>
        <BagInfo Index="1" DropRate="10000">
            <DropInfo Section="1" SectionRate="10000" Money="0"
                      OptionValue="0" RequireClass="1 1 1 1 1 1 1"/>
        </BagInfo>

        <ItemSection Id="1">
            <Item Index="7182" Level="0" Grade="0"
                  Option0="*" Option1="*" Option2="*" Option3="*"
                  Option4="*" Option5="*" Option6="*" Duration="0" Count="5"/>
        </ItemSection>
    </ExtendedBag>
</ItemBag>
```

**Result:** Drops a single item slot containing 5 Jewels of Soul. The item must be registered as stackable in ItemStack.xml (Cat 14 / Index 14 = Jewel of Soul). Without a matching ItemStack entry, Count is ignored and 1 jewel drops instead.
{% endtab %}
{% endtabs %}

## Common Issues

{% hint style="warning" %}
**Bag doesn't trigger:** Check EventItemBagManager.xml. Verify Index matches filename, and at least one trigger condition (ItemIndex+Level, MonsterClass, or SpecialValue) is set correctly.
{% endhint %}

{% hint style="warning" %}
**Class-specific section not working:** RequireClass values are minimum (ChangeUp+1) requirements. Use `1` for base class (ChangeUp 0), `2` for 1st ChangeUp or higher, `3` for 2nd ChangeUp or higher, `4` for 3rd ChangeUp. Using `0` blocks that class entirely.
{% endhint %}

{% hint style="warning" %}
**Items have wrong options:** Option0-6 are indices into ItemOptionRate.xml, not direct values. Using `0` means "use rate index 0", not "no option". Use `*` for default behavior.
{% endhint %}

{% hint style="warning" %}
**Extended bag ignored:** If both `<Drop>` and `<ExtendedBag>` exist, only ExtendedBag is used. Remove `<Drop>` entries or move them to a separate bag file.
{% endhint %}

{% hint style="warning" %}
**Count attribute not working:** `Count` only applies to items registered in ItemStack.xml. If the item has no entry in ItemStack.xml, or if its entry covers non-stackable categories (0-11), `Count` is silently ignored and the item drops as a single unit. Verify the item appears in `GameServer/Data/Item/ItemStack.xml` with a `MaxStack` greater than 1.
{% endhint %}

{% hint style="danger" %}
**Filename mismatch:** Bag files must exactly match `###␣-␣Name.xml` pattern with correct index. File `001-Box.xml` or `1 - Box.xml` will NOT load. Must be `001 - Box.xml`.
{% endhint %}
