Add a Hero

A hero (mercenary) is spread over many files. The server and the client each need their own part, and both must use the same hero number. This guide follows one new hero from start to finish. It uses hero number N in the examples.

File names come from the code that loads them (ioSetItemInfoManager.cpp, ioItemInfoManager.cpp, ioItemMaker.cpp, ioItemPriceManager). Anything not checked is marked not confirmed yet.

Caution

Making a working hero also needs 3D data: a model, animations, effects and icons. This guide covers the config side. The art files are not covered. LosaDev Tools can open models and packs.

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.

The numbers

Everything is derived from the hero number N. The shipped data follows this pattern (for example hero 231 and hero 938 in sp2_item.ini):

Item	Code
Set code of the hero	700000 + N
Weapon	N
Armor (suit)	100000 + N
Helmet	200000 + N
Cloak	300000 + N
Premium weapon, armor, helmet, cloak	10000 + N, 110000 + N, 210000 + N, 310000 + N
Costume armor, helmet, cloak (shop code)	100000 + N, 200000 + N, 300000 + N (see Costumes)

The client works out the hero number from the set code: GetSetInfoByClass subtracts SET_ITEM_CODE (700000). Use the next free number. Check these limits first:

• item_group_cnt = 1001 in the client sp2_item.ini, sp2_skill.ini and sp2_extraitem.ini. Hero numbers up to 1000 fit without changing it.
• MAX_CLASS in the server sp2_item_price.ini.
• max_set_item in sp2_setitem_info.ini.
• item_count in the server sp2_item.ini.
• The client sp2_growth_info.ini has growth_group_cnt = 601. What this means for hero numbers above 600: not confirmed yet. The newest hero in the 2021 client (938) has no _growth.ini file.

Step 1: client hero folder

1. Create config\mercenary\NNN\ (three digits, for example config\mercenary\940\). Copy a similar hero as a start.

2. The folder holds these files (hero 938 has the first five):

   File	Holds
   NNN_item.ini	The four base gear pieces (item_cnt = 4)
   NNN_extraitem.ini	The four premium gear pieces
   NNN_skill.ini	skill_cnt and one [skillN] per skill with name
   NNN_attack.ini	Attack data
   NNN_buff.ini	Buffs of this hero
   NNN_growth.ini, NNN_powerup_item.ini, NNN_powerup_extraitem.ini	Only some heroes have them

3. In NNN_item.ini, each gear piece is a block:

   [item1]
   name          = Sample Sword
   code          = 940
   enable_class  = 940
   set_item_code = 700940
   item_type     = WEAPON
   sub_type      = SABER
   item_large_icon0 = ItemIconPack101#n940_weapon
   equip_mesh0   = sample_sword
   delay_animation = knight_delay.ani

   The next three blocks use item_type ARMOR, HELMET and CLOAK with codes 100940, 200940, 300940. NNN_extraitem.ini has the same four with 10940, 110940, 210940, 310940 and a grade_type.

4. Register the folder in three client files:

   ; sp2_item.ini
   item_group940 = mercenary/940/940_item.ini
   ; sp2_extraitem.ini
   item_group940 = mercenary/940/940_extraitem.ini
   ; sp2_skill.ini
   skill_group940 = mercenary/940/940_skill.ini

   The line item_groupN must use the same N as the folder.

Step 2: class data (client and server)

sp2_setitem_info.ini exists in both places. Add the same block to both:

[set_item940]
name           = Sample Hero
set_code       = 700940
voice_type     = 1
need_right_code   = 20
need_level_type1  = 1
need_level1       = 55
shop_order        = 5055
shop_mark_type    = 0
char_attack_type  = 1
item_manual       = 940
img_name          = ShopChr001#001
set_focus_line_color_r = 80
set_focus_line_color_g = 180
set_focus_line_color_b = 255
package_man_face       = 60
package_man_hair       = 34
package_man_hair_color = 29
package_man_skin_color = 2
package_man_underwear  = 7
package_woman_face       = 77
package_woman_hair       = 25
package_woman_hair_color = 28
package_woman_skin_color = 2
package_woman_underwear  = 8

Then raise max_set_item in [common]. The block name must be set_item<position>, counted from 1 up to max_set_item. The position does not need to match N. The hero number comes from set_code.

Key	Used by	Meaning
name	both	Unique name. A duplicate name or set_code is rejected and logged (“Already Exist”)
set_code	both	700000 + N
need_right_code, need_level_typeN, need_levelN	both	Permission and level to use the hero. The loop stops at the first missing key
shop_order, shop_mark_type, recommended_shop_order	client	Shop position and badge
char_attack_type	client	Attack type group
item_manual	client	Number of the text block in the item manual file
img_name	client	Shop picture, imageset#image from xml\uiimageset.xml
package_man_*, package_woman_*	client	Look of the hero when bought as a package
is_dummy, char_sex_type, limit_date, setitem_skill_name	client	Optional
sub_icon	client, 2019 and 2021 only	Small icon
mortain_sellvalue, preset_gender and preset deco keys	server	Read by the server loader. Meaning of the preset keys: not confirmed yet

Step 3: server item list

The server does not read the hero folders. It reads one flat list, sp2_item.ini, in ls_gamesvr\config\:

[common_info]
item_count = 3593

[item3589]
name = Weapon
code = 940
set_item_code = 700940

[item3590]
name = Armor
code = 100940
set_item_code = 700940

[item3591]
name = Helmet
code = 200940
set_item_code = 700940

[item3592]
name = Accessory
code = 300940
set_item_code = 700940

[item3593]
name = Premium Weapon
code = 10940
set_item_code = 700940
enable_class = 940
default_reinforce_min = 1
default_reinforce_max = 10

1. Add the blocks at the end and raise item_count by the number you added. Blocks past item_count are not read.
2. Keys read by ioItemInfoManager::AddItemInfo: code, name, set_item_code, group, enable_class, default_reinforce_min, default_reinforce_max, grade_type, item_create_limit_count, max_level.
3. In the shipped list, the last hero (231) has the base weapon, armor, helmet and cloak, and only the premium weapon (10231). Whether the server needs entries for the premium armor, helmet and cloak (110231 and so on): not confirmed yet.

Step 4: price and shop entry

1. In the server sp2_item_price.ini, add or edit [CLASS_940] and make sure MAX_CLASS is at least 940:

   [CLASS_940]
   ACTIVE     = 1
   CASH       = 2500
   BONUS_PESO = 0

2. The shop position is shop_order in sp2_setitem_info.ini (step 2). ACTIVE = 0 keeps the hero out of the shop while you test.

3. For the details of prices, sales and hiding, read Shop items.

4. Make the hero playable for the test account: Gacha boxes (reward type 1: hero number and hours) is the easiest way to hand out the hero without the shop.

Step 5: gear in the shop and gacha

Premium gear is bought or won through gear boxes. In sp2_extraitem_info.ini (server and client) add the new gear codes as item<N>_code and item<N>_rate inside a [random_machineN] block, and raise item_cnt. See Add an item and Gacha boxes.

Step 6: art, text and other client files

What	Where
Model, mesh, texture	resource\mesh, resource\texture, resource\model (referenced by equip_mesh0, field_mesh0 in the item file)
Animations	resource\animation (delay_animation, run_animation, shop_motion)
Gear icons	item_large_icon0 = ItemIconPack101#n940_weapon, defined in xml\uiimageset.xml
Shop picture	img_name in sp2_setitem_info.ini
Hero sounds	sp2_soldier_sound.ini (ioRsoldierInfoManager.cpp). Exact keys: not confirmed yet
Default look in selection	sp2_soldier_default_deco.ini (only for a fixed set of heroes in the 2021 client)
Hero text	Names are plain text in the INI files. UI text is in the locale text table. Non-Korean clients print %1 %2 where Korea uses %s %d

Skill names such as 938MS_SD in NNN_skill.ini point to skill data. Where each skill is defined: not confirmed yet.

Step 7: test

1. Restart the game server. Copy the client files into a test client and start it.
2. Check the log for Already Exist or Add Failed lines from the set item and item loaders.
3. Open the shop, find the hero, check name, picture and price.
4. Get the hero, equip the four gear pieces, enter a match.

Symptom	Likely cause
Hero not in the shop	ACTIVE = 0, set_item missing in the client, or max_set_item too low
Hero shown without gear	item_groupN missing in the client sp2_item.ini, or codes not in the server sp2_item.ini
Wrong price	The client has no price file. Fix the server sp2_item_price.ini
Client crash on start	A model, animation or icon name that does not exist

Differences between versions

	2014	2019	2021
Hero count in the source	178	213	232
Hero client config	inside rs.iop	inside rs.iop	plain config\mercenary\
sub_icon in sp2_setitem_info.ini	not read	read	read
Server sp2_item.ini	present	not confirmed yet (only the testbed has it)	present

Not confirmed yet: the exact content of the packed 2014 and 2019 client files, because the packs were not opened for this guide.