Add an Item

This guide adds an item to the game. It covers the two item families you will use most:

• Gear: weapon, armor, helmet, cloak. These belong to a hero.
• Etc items: packages, tickets, boxes, buffs and everything else players keep in the inventory.

For costumes see Costumes. For selling the item see Shop items. For random boxes see Gacha boxes.

File names come from the code that loads them (ioItemInfoManager.cpp, ioEtcItemManager.cpp, ioEtcItem.cpp, ioExtraItemInfoManager.cpp). Anything not checked is marked not confirmed yet.

Note

Server files are CP949. The 2021 client has plain config\ files. The 2014 and 2019 clients keep theirs inside rs.iop. See Extract and replace a file and Edit an INI table.

Rule 1: the item needs an entry on both sides

Family	Server	Client
Gear	sp2_item.ini (flat list), sp2_extraitem_info.ini (boxes)	mercenary\NNN\NNN_item.ini or NNN_extraitem.ini, sp2_extraitem_info.ini
Etc item	sp2_etcitem_info.ini	sp2_etcitem_info.ini

If one side is missing, the item shows wrong or cannot be used. Check the pair after every change.

Part A: add an etc item

1. Open sp2_etcitem_info.ini on the server. Go to the end. Add a block. The number is the next free one:

   [etcitem5608]
   name      = Test Ticket
   type      = <an unused type from a range the code knows>
   can_sell  = 0
   sell_peso = 0
   active1   = 1
   value1    = 1
   peso1     = 0
   cash1     = 990
   bonus_peso1 = 0

2. Raise max in [common] so that it covers the new block. The client loop is etcitem1 to etcitem<max>. A block past max is never read.

3. Check the type. It has the form AABBBBBB. The comment at the top of the file says: AA = 1 count-use, 2 time-use, 3 instant use; BBBBBB is the permission code or the item kind. The type must be one the code knows. ioEtcItemManager::CreateEtcItem creates an object per known type or range. An unknown type is skipped and the client log shows UNKOWN ETCITEM TYPE. So an etc item with a new behaviour needs code, not only config.

4. A type already used by another block is rejected (Already Exist). Search the file first.

5. Copy the block to the client file. The client reads more keys than the server. Add the look:

   [etcitem5608]
   name      = Test Ticket
   type      = <the same type as on the server>
   can_sell  = 0
   sell_peso = 0
   buy_popup_type = 1
   extend_use     = 1
   inventory_manual     = 17
   inventory_sub_manual = 0
   inventory_order      = 2000
   shop_name1      = Test Ticket
   value1          = 1
   peso1           = 0
   cash1           = 990
   bonus_peso1     = 0
   show_peso1      = 0
   main_manual1    = 20
   sub_manual1     = 20
   shop_order1     = 210
   shop_mark_type1 = 3
   shop_tab_type1  = 4
   active1         = 1
   icon_name       = UIIconPack10#goods_pack2

   Key	Meaning
   inventory_manual, inventory_sub_manual	Text block numbers for the inventory tooltip
   main_manual1, sub_manual1	Text block numbers for the shop description
   shop_order1	Sort position. The file says 100 sale or event, 300 new, 500 hot, 1000 normal
   shop_mark_type1	Badge: 1 sale, 2 new, 3 hot, 4 event
   shop_tab_type1	Tab: 1 hero, 2 gear, 3 costume, 4 special
   icon_name	imageset#image, see Icons below
   extend_use, present_use, can_sell, block_buying	Use, gift, sell and buy switches

6. Match the prices: peso1, cash1, bonus_peso1 on both sides. The server price is the one the server charges.

Also read value1, value2 and so on: they are the offers (for example 1 piece, 5 pieces). The loop stops at the first value<n> that is missing.

Part B: add a gear piece

A hero owns its gear. The shipped pattern for hero N is in Add a hero. To add one extra piece for an existing hero:

1. Client, in the hero folder, edit config\mercenary\NNN\NNN_extraitem.ini (premium gear) or NNN_item.ini (base gear). Raise item_cnt and add a block:

   [item5]
   name          = Sample Sword Plus
   code          = 20940
   enable_class  = 940
   set_item_code = 700940
   grade_type    = 6
   item_type     = WEAPON
   sub_type      = SABER
   item_large_icon0 = ItemIconPack101#n940_weapon
   equip_mesh0   = sample_sword

   code must be unique over all heroes. The loader reads code and set_item_code for each block, and enable_class and grade_type where present.

2. Server, add a block at the end of sp2_item.ini and raise item_count:

   [item3594]
   name = Sample Sword Plus
   code = 20940
   set_item_code = 700940
   enable_class = 940
   default_reinforce_min = 1
   default_reinforce_max = 10

3. To let players get it, put the code in a gear box: add itemN_code and itemN_rate in a [random_machineN] block of sp2_extraitem_info.ini, and raise that block’s item_cnt. The chance is itemN_rate divided by the sum of all rates in the block. Do this on both sides (the client copy shows the list). The server also reads period_time_cnt and tradetype_cnt data in the same block.

4. Or give it directly as a gift: type 5 in a gashapon, Value1 is the code, Value2 is enhance x 10000 + hours (see Gacha boxes).

The index comment at the top of the server sp2_extraitem_info.ini lists reserved ranges, for example 1 to 239 for supply boxes and event shops, 1001 to 2000 for timed goods. This is for machine codes, not for gear codes.

Icons

Icons are not file names. They are ImagesetName#ImageName. Example: ItemIconPack101#n938_weapon.

1. Open xml\uiimageset.xml in the client (2021 client, plain file). Find <Imageset Name="ItemIconPack101" File="item_icon_pack101.dds">.
2. The File is in resource\texture\. The <Image Name="n938_weapon" X=".." Y=".." Width=".." Height=".." /> lines cut the pictures out of the sheet.
3. To add an icon, paint it into a free place of the .dds sheet (or a new sheet). Then add one Image line with the position. Use a new unique Name.
4. Put the new name in item_large_icon0 (gear) or icon_name (etc item).
5. In 2014 and 2019, uiimageset.xml and the .dds files are inside the client packs. Use LosaDev Tools to extract and replace them. Keep any other entries of the file as they are. Add only yours.

Text

• Names are plain text inside the INI file (name =, shop_name1 =). They are not in the locale text table.

• Tooltip text lives in manual files. A manual block has lines such as 1SpaceLine, 1Color1, 1Text1:

  File	Used by
  sp2_etc_manual.ini	main_manual1, sub_manual1 (shop)
  sp2_etc_inven_manual.ini, sp2_etc_inven_sub_manual.ini	inventory_manual, inventory_sub_manual
  sp2_extra_inven_manual.ini	gear box and gear tooltips
  sp2_item_manual.ini	hero gear manual (item_manual of a set item)

  Each file starts with [Info] and MaxManual. Your block number [ManualN] must not be larger than MaxManual. The top of sp2_etc_manual.ini lists reserved ranges, for example 1 to 2000 for normal items.

• Window text (messages, buttons) is in the locale text table, text_id.txt for Indonesia (text.txt for Korea). It is inside the client packs. Non-Korean clients use %1 %2 placeholders where Korea uses %s %d.

Test

1. Restart the game server and the client.
2. Give the item to a test account (gift or box).
3. Check the inventory name, icon and tooltip, then use or equip it.
4. Look in the server log for Already Exist, Add Failed and UNKOWN ETCITEM TYPE.

Differences between versions

	2014	2019	2021
Etc item shop_tab_type, medalitem_max_check keys in the client	yes	yes	yes
Gear box grade_type	not confirmed yet	not confirmed yet	yes (seen in the data)
Client config	inside rs.iop	inside rs.iop	plain config\
Server sp2_item.ini in the repo	yes	testbed only	yes

Not confirmed yet: which etc item types need extra server code beyond the config (for example the list of types the server ioEtcItem.cpp handles), and the exact effect of limit_class_num and limit_active_filter on package items.