> 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/customstartitem.md).

# CustomStartItem

Grants items, buffs, and currency to characters the first time they log in after creation. Per-class sections let you give different starting gear to each character class.

## File Location

```
Data/Plugins/Characters/CustomStartItem.xml
```

Loaded once at GameServer startup. Supports hot reload via plugin admin command.

## Schema

```xml
<CustomStartItem>
    <Items>
        <Item Class="..." Slot="..." ItemType="..." ItemIndex="..." ItemLevel="..."
              ItemDurability="..." ItemOption1="..." ItemOption2="..." ItemOption3="..."
              ItemNewOption="..." AncOption="..." JOH="..." OpEx="..."
              Socket1="..." Socket2="..." Socket3="..." Socket4="..." Socket5="..."
              Duration="..." />
    </Items>
    <Buffs>
        <Buff Class="..." EffectID="..." Power1="..." Power2="..." Time="..." />
    </Buffs>
    <Coins>
        <Coin Class="..." Coin1="..." Coin2="..." Coin3="..." />
    </Coins>
</CustomStartItem>
```

## Class Codes

| Value | Class           |
| ----- | --------------- |
| `0`   | Dark Wizard     |
| `1`   | Dark Knight     |
| `2`   | Fairy Elf       |
| `3`   | Magic Gladiator |
| `4`   | Dark Lord       |
| `5`   | Summoner        |
| `6`   | Rage Fighter    |

## Item Attributes

Equipment slots for starter gear:

| Slot | Position                |
| ---- | ----------------------- |
| `0`  | Right Hand (Weapon)     |
| `1`  | Left Hand (Shield/Book) |
| `2`  | Helm                    |
| `3`  | Armor                   |
| `4`  | Pants                   |
| `5`  | Gloves                  |
| `6`  | Boots                   |
| `7`  | Wings                   |
| `8`  | Pendant                 |
| `9`  | Ring (Left)             |
| `10` | Ring (Right)            |
| `11` | Pet                     |

Item attributes mirror the standard item record:

| Attribute                | Effect                                                |
| ------------------------ | ----------------------------------------------------- |
| `ItemType` / `ItemIndex` | Item identity per [Item.xml](/docs/data/item/item.md) |
| `ItemLevel`              | +level, 0-15                                          |
| `ItemDurability`         | 0 = max                                               |
| `ItemOption1`            | `1` grants the item's skill option                    |
| `ItemOption2`            | `1` grants Luck                                       |
| `ItemOption3`            | Additional option level 0-7                           |
| `ItemNewOption`          | Excellent option bitmask                              |
| `AncOption`              | Ancient/set option                                    |
| `JOH`                    | Jewel of Harmony option                               |
| `OpEx`                   | Extended option                                       |
| `Socket1-5`              | Socket seed options. `255` = empty                    |
| `Duration`               | Expiration time in seconds. `0` = permanent           |

## Buffs

One `<Buff>` entry per effect to apply on first login. Multiple entries for the same class all apply.

| Attribute  | Effect                                                                                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Class`    | Class code (see table above)                                                                                                                           |
| `EffectID` | Buff effect index from the server's effect table. Invalid IDs are skipped silently                                                                     |
| `Power1`   | Primary magnitude passed to the effect                                                                                                                 |
| `Power2`   | Secondary magnitude passed to the effect                                                                                                               |
| `Time`     | Duration in minutes. Converted internally (minutes \* 60 ticks, or minutes \* 60 seconds for real-time effects). `0` expires the buff on the next tick |

## Coins

One `<Coin>` row per class grants all three currency balances. If multiple rows match a class, every row fires and the DataServer-side coin add stacks.

| Attribute | Effect                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `Class`   | Class code (see table above). A row whose `Class` matches no character class is silently never granted |
| `Coin1`   | Starting WCoin. Negative values are clamped to `0`                                                     |
| `Coin2`   | Starting WPCoin (WCoin Premium). Negative values clamped to `0`                                        |
| `Coin3`   | Starting Goblin Points. Negative values clamped to `0`                                                 |

## First-Login Behavior

Grants fire once, on the character's first login after creation. When the grant completes, GameServer sends a persistence packet to DataServer that marks the character as having received the start-item bundle; subsequent logins skip the grant. Re-running the grant for an existing character requires clearing that flag DataServer-side.

Item grants are routed through the standard item-create persistence path, so socket seeds, excellent bits, ancient flags, and duration timestamps are preserved on the created item. Items that cannot be equipped by the character's class land in the first free inventory slot instead of the configured wear slot.

## Cross-File Dependencies

| Attribute                | Related in                                                                                                                                                                                                                                            |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Class`                  | [Character.dat](/docs/gameserver/character-dat.md) class codes and [DefaultClassInfo.txt](/docs/data/defaultclassinfo.md) base stats                                                                                                                  |
| `ItemType` / `ItemIndex` | [Item.xml](/docs/data/item/item.md)                                                                                                                                                                                                                   |
| `Socket1-5`              | [SocketItemType.xml](/docs/data/item/socketitemtype.md) and [SocketItemOption.xml](/docs/data/item/socketitemoption.md). Sockets only populate if the target item is registered as socketable; extra slots beyond the item's socket count are ignored |
| `EffectID`               | Server effect table index. TODO: verify effect index listing location                                                                                                                                                                                 |

## Common Issues

* **Starter item not granted** - the DataServer start-item flag is already set (character has logged in before), or no `<Item Class="N" Slot="M">` row matches both the class and a wear slot
* **Item ends up in inventory instead of equipped** - the item cannot be equipped by the character's class; the plugin routes it to the first free inventory slot
* **Socket sets to empty despite definition** - target `ItemType`/`ItemIndex` is not registered as socketable in SocketItemType, or `Socket1-5` exceed the item's socket count; `255` is the "empty socket" sentinel
* **Duplicate grants on every login** - DataServer persistence failed or flag was cleared; check DataServer logs for the start-item save packet
* **Buff not applied** - `EffectID` is not a valid effect on this server; the buff entry is skipped
* **Buff shorter than expected** - `Time` is minutes, not seconds