Metin2 Item Proto Editing: Adding New Items

If you run a Metin2 server, sooner or later you will want to add a new weapon, armor or costume, and at the heart of that sits the metin2 item proto data. The item proto is the table that stores every item's identity, type, damage, defense, wear requirements and bonuses. Adding an item properly means updating this data consistently on both the server and the client. In this guide we add a brand new item end to end: choosing a vnum, the server record, the client files, icon and model, then testing.

What the item proto is and where it lives

The item proto exists in two separate places, and the two must match exactly:

• Server side: The game core reads item definitions. Depending on your source version this data comes either from the item_proto table in the MySQL player database, or from an item_proto text/binary file. The core loads it into memory at startup.
• Client side: The client's pack folder contains an encrypted/packed item_proto file. The client reads the item's visual and gameplay data from there. Under locale you also have item_names.txt (display names), item_list.txt (icon and model paths) and itemdesc.txt (descriptions).

If an item is defined only on the server, the client cannot draw it (it appears missing or broken); if it exists only on the client, the server cannot spawn it. Both sides must carry the same vnum and compatible values.

Before you start: backups and choosing a vnum

First rule: make a backup. Keep a dump of the MySQL item_proto table and copies of every .txt/pack file you are about to touch. A single broken line can stop the core from loading items.

The next step is choosing a vnum (item number). Every item has a unique vnum. Pick an unused range to avoid collisions. Standard weapons usually sit in the 0–8000 band; for custom items a high, empty range (for example 30000+) reduces the risk of clashes. To find a free vnum in MySQL:

SELECT vnum FROM player.item_proto WHERE vnum BETWEEN 30000 AND 30100 ORDER BY vnum;

If no rows come back in that range, it is safe to use.

Server side: adding a new item to the item proto

Instead of defining a new item from scratch, the most reliable method is to copy an existing item of the same type as a template. If you are adding a sword, take the row of an existing sword, change the vnum and name, then edit only the fields that should differ (damage, wear level, bonuses). The reason: the meaning of the value0–value5 fields changes per item type, so starting from a correct example removes most mistakes.

Key columns:

• vnum: unique number. name/locale_name: in-server name.
• type and subtype: e.g. for a weapon ITEM_WEAPON + WEAPON_SWORD; for armor ITEM_ARMOR + ARMOR_BODY.
• antiflags: which classes/genders cannot use it (e.g. ANTI_WARRIOR).
• wearflags: where the item is worn (WEAR_WEAPON, WEAR_BODY, etc.).
• limittype0/limitvalue0: the wear requirement, most often LIMIT_LEVEL plus a level value.
• applytype0..2 / applyvalue0..2: the bonuses the item grants (e.g. APPLY_ATT_SPEED, APPLY_MAX_HP).
• value0..value5: type-specific values. A common mapping for weapons: value3 = minimum physical damage, value4 = maximum physical damage, value5 = magic/extra attack; for armor value1 carries the defense. Still, copy from a correct item of the same type and compare.
• price, refined_vnum (upgrade chain), socket0..2 (slots), addon_type.

In MySQL the quickest path is to duplicate an existing sword:

INSERT INTO player.item_proto
SELECT * FROM player.item_proto WHERE vnum = 19; -- an example sword
-- then edit the new row:
UPDATE player.item_proto
SET vnum = 30001, name = 'New Sword', value3 = 60, value4 = 90
WHERE vnum = 19; -- make sure you target the right row

In practice it is cleaner to export the existing row, edit it and insert it back as a new row with vnum = 30001. If your source reads from a text file, you open the item_proto txt with a converter, add the new tab-separated line, then repack. For the change to take effect, restart the core; the proto is loaded into memory at startup.

Client side: item proto, item_names and item_list

For the client files you use a proto conversion tool (community tools turn the packed item_proto into editable .txt, then pack it back). The flow:

• item_proto (client) → convert to tab-separated txt, add the new line with the same vnum and values as the server, repack and place it into pack.
• locale/<lang>/item_names.txt → line format vnum[TAB]Display Name. Add the new vnum and the name shown in-game. Keep this file in the correct encoding (usually matching the server language).
• locale/<lang>/item_list.txt → maps each vnum to an icon and model path: vnum[TAB]ITEM[TAB]icon/item/xxxx.tga[TAB]d:/ymir work/item/.../xxxx.gr2. Define your new item's icon and model paths here.
• locale/<lang>/itemdesc.txt → optional description text.

Adding the icon and model

For the item to appear in hand and inventory you need two assets: an icon (.tga, usually 32×32, shown in the inventory slot) and a 3D model (on the character's hand/body). Put the icon in the client's icon/item/ path and point to it in item_list.txt. If you have not created new artwork yet, you can reuse the icon and model paths of a similar item to start with — the item works, it just shows existing artwork. If you need a unique model, place the .gr2 file in the proper folder and reference the path in item_list.txt. A wrong icon path shows an empty/red box in the inventory; that is the most common sign you need to fix the path.

Testing, reloading and common mistakes

After restarting the server, log in with a GM account and spawn the item:

/item 30001
# or by name (if item_names is correct):
/item New_Sword

If the item drops into the inventory, shows the right name and icon, and on equip its damage/defense and bonuses match the table, you are done. Common mistakes:

• Server/client vnum mismatch: the most frequent issue. Both sides must hold the same vnum.
• Core won't boot: a broken line in the proto (missing column, wrong type name). Check the syserr logs.
• Item invisible/empty box: a wrong icon/model path in item_list.txt.
• Name blank or shown like a key: missing line in item_names.txt or broken encoding.

Frequently Asked Questions

Should I edit the item proto from MySQL or from a txt file?

It depends on your source. Modern sources usually read the MySQL player.item_proto table; in that case you edit the table directly and restart the core. Some versions read a txt/binary file. If you are unsure which you use, check the core's startup configuration and the syserr output. The client side is a packed file in every case.

Do I really have to restart the server for the change?

Because the item proto is loaded into memory at startup, a new item definition practically requires a core restart to appear. Some setups have partial reload commands, but the guaranteed, clean path is to restart the game core. For client changes, players need to receive the updated pack/locale files.

Why should I start a new item by copying an existing one?

Because the meaning of fields like value0–value5, wearflags and antiflags changes per item type. Taking a working item of the same type as a template gives you a valid structure to start from; you only change the fields that should differ, and you largely avoid silent errors.

Want to add custom items, sets or a whole new system to your own server? From item proto editing to quest and system development, I can help with Metin2 server work. Get in touch to tell me about your project.