Add a Costume

A costume is a cosmetic skin for a hero’s armor, helmet or cloak. It changes the look but not the stats. This guide shows the files you need and how they link together.

File names come from the code that loads them: CostumeManager.cpp, CostumeShopGoodsManager.cpp (server, ls_gamesvr\NodeInfo\) and ioCostumeShopInfoManager.cpp (client, LSClient\). 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.

How the pieces link

Piece	File	Side	Key that links
Costume definition (look)	config\costume\costume_armor.ini, costume_helmet.ini, costume_cloak.ini	client	costum_code
List of all costumes	sp2_costumemanager.ini	server	costumeN > item_code
Shop goods and prices	sp2_costume_shop_goods.ini	server	machine_code, item_code
Shop entry (name, icon, price list)	sp2_costume_shop_info.ini	client	costume_shop_code
Tooltip text	sp2_costume_shop_manual.ini, sp2_costume_inven_manual.ini	client	manual
Where costumes are visible	sp2_costume.ini	client	costume_group1..3, enable_modeN

The costume code is the same number as an existing gear code. The comment at the top of costume_armor.ini says the Korean costumes reuse the gear code, and the icon is read from that gear automatically. The shop code of an armor costume for hero N is 100000 + N, helmet 200000 + N, cloak 300000 + N. The costume itself (costum_code) can be a premium gear code such as 110009.

Step 1: define the costume in the client

Open the right file for the part (costume_armor.ini for armor). Each file starts with [common_info] and costume_cnt. Raise costume_cnt, then add a block at the end:

[costume588]
name        = Test Armor
costum_code = 110940
manual      = 1
item_equip_effect =
skill_color_red   = 178.5f
skill_color_green = 102.0f
skill_color_blue  = 51.0f
skill_color_alpha = 255.0f
body_mesh   = ice_body_01
hand_mesh   =

• Armor uses body_mesh and hand_mesh. A helmet uses helmet_mesh and the face and hair keys (face_change_hm, hair_change_hm, invisible_face). A cloak has its own file, costume_cloak.ini. Copy a block of the same part and change only what you need.
• costum_code must be unique over all three files.
• The mesh names are files in resource\mesh. The textures are in resource\texture. A wrong name can crash the client.
• Block names follow [costumeN] in order, from 1 to costume_cnt.
• The three files are registered in sp2_costume.ini as costume_group_cnt = 3 and costume_group1 to costume_group3. For a new part file, add a group.

Step 2: tell the server the costume exists

In the server sp2_costumemanager.ini, raise costume_cnt in [common] and add a block:

[costume1765]
item_code = 110940

The server only needs the code. IsExistCostumeItem checks whether a code is in this list (CostumeManager.cpp). Add every costume code here. The same section holds mortmain_item_sell and time_item_sell, the peso a player gets when selling a permanent or timed costume.

Step 3: put it in the shop

Server, sp2_costume_shop_goods.ini. Raise machine_count in [common_info], add a block:

[costume_machine562]
machine_code = 100940
item_code    = 110940
active       = 1

need_peso1 = 6800
period1    = 24
need_peso2 = 28000
period2    = 240
need_peso3 = 48000
period3    = 720

• need_pesoN is the price for periodN (hours). The loop stops at the first periodN below 0. 240 hours is 10 days, 720 is 30 days.
• active = 0 hides the machine (IsRightGoods returns false). The active key is read in 2019 and 2021 only. In 2014 the server ignores it.
• The server has lookups for these values (GetNeedPeso, GetPeriod). Where the buy handler calls them: not confirmed yet.

Client, sp2_costume_shop_info.ini. Raise costume_cnt in [common_info], add a block:

[costume_machine562]
name  = Test Armor
order = 199997
mark  = 0
manual = 1
icon  = ItemIconPack201#n001_armor
group = 2
active = 1

costume_shop_code = 100940

need_peso1 = 6800
period1    = 24
need_peso2 = 28000
period2    = 240
need_peso3 = 48000
period3    = 720

item_cnt   = 1
item1_code = 110940

set_preview = 1

Key	Meaning
costume_shop_code	Must equal the server machine_code. A block with 0 is skipped
name, icon	Shop name and icon. If icon is empty, the icon of the first item is used
order	Sort number. The code builds order from three parts: rare flag, hero code and part (weapon 4, armor 3, helmet 2, cloak 1)
mark	Badge number
group	Shop group (armor files use 2 in the data seen)
item_cnt, itemN_code	Costume codes in the package. Also itemN_mark and itemN_limit_date
set_preview	Shows the preview button
default_type	Takes defaults from a [defaultN] block (the file has three)
grade_type, need_level, subscription_type, limit_date, recommended_order	Optional

The numbers of prices, periods and the cash price should match the server. The client file has the prices only to display them. The server decides what it charges.

Step 4: tooltip text

manual points to a [ManualN] block in sp2_costume_shop_manual.ini (shop) and sp2_costume_inven_manual.ini (inventory). Each manual file starts with [Info] and MaxManual. A block looks like this:

[Manual1]
1SpaceLine = 0
1Color1    = 0xFF5B3714
1Text1     = Test armor skin

Names are plain text in the INI. Window text is in the locale text table (text_id.txt for Indonesia). It is in the client packs. Non-Korean clients use %1 %2 placeholders where Korea uses %s %d.

Step 5: give it without the shop

• Gift type 12 gives a costume. Value1 is the costume code. Value2 is the period (0 means permanent). See ioUserPresent.cpp, SetPresentCostume.
• Gift type 15 is a costume box. It exists in the 2019 and 2021 source only.
• Use these types in a gashapon: Gacha boxes.
• Where a costume can be seen is set in sp2_costume.ini (enable_mode_cnt, enable_mode1..). The mode numbers are in the comment at the top of that file.

Step 6: test

1. Restart the game server and the client.
2. Open the costume shop. Check the entry, the price list and the preview.
3. Buy it with a test account. Check the inventory and wear it in the lobby.
4. Look in the logs for a client crash right after the preview (usually a wrong mesh name).

Symptom	Likely cause
Not in the shop	costume_shop_code is 0 or costume_cnt is too low in the client, or active = 0
Cannot buy	machine_code not in the server sp2_costume_shop_goods.ini, or machine_count too low
Gift or purchase fails	Code missing in the server sp2_costumemanager.ini (checked by IsExistCostumeItem; the callers are not confirmed yet)
Invisible costume	Wrong body_mesh, helmet_mesh or texture name

Differences between versions

	2014	2019	2021
Server active in sp2_costume_shop_goods.ini	no	yes	yes
Client grade_type, subscription_type, need_level	yes	yes	yes
Gift type 15 (costume box)	no	yes	yes
Client config	inside rs.iop	inside rs.iop	plain config\
Server config in the repo	ls_gamesvr\config\	testbed only	ls_gamesvr\config\

Not confirmed yet: how the shop treats costumes of heroes the player does not own, how group values map to shop tabs, and the packed 2014 and 2019 client files (the packs were not opened).