CustomStartItem.xml

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#

<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
`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`

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 class codes and DefaultClassInfo.txt base stats
`ItemType` / `ItemIndex`	Item.xml
`Socket1-5`	SocketItemType.xml and SocketItemOption.xml. 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