Adding a Metin2 Model: .gr2 Granny Files and Index Binding

Metin2 model ekleme — adding a model to Metin2 — is something everyone who wants to bring a new monster, NPC or mount into the game runs into sooner or later. At its core sits a single file format: .gr2, the model file of RAD Game Tools' Granny3D engine. If you don't prepare the model folder correctly and bind it to the right index, even the prettiest mesh stays invisible in-game or crashes the client instantly. This guide walks through the logic of integrating a new 3D model from scratch and binding it to a mob_proto vnum, step by step.

What is .gr2 and how Granny relates to Metin2

The Metin2 client uses the Granny3D runtime (granny2.dll) to render character and object models, which is why all mesh, skeleton and animation data is stored with the .gr2 extension. A single .gr2 file can hold just a mesh, or it can also carry a skeleton and motion data. The common approach in Metin2 is this: one file holds the mesh plus skeleton, while separate files carry each animation (walk, attack, death). For your model to behave properly in-game, this trio — mesh, skeleton, motion — must be compatible with each other.

What lives inside a model folder

In the client, every monster or NPC lives in its own folder; these folders usually sit inside the pack archives under monster2/ (monsters) or npc/. A typical folder contains:

• Mesh .gr2 — The model itself, together with its skeleton. Most folders give it a fixed name (for example model.gr2).
• Motion .gr2 files — Each one holds a single animation: idle, run, attack, taking damage, death.
• Texture files — Usually in .dds (DXT-compressed) format. They must match the material name of the mesh.
• .msm file — The "Monster State Module"; a text-based state machine defining which motion plays in which state.

You can open and inspect all of these with Granny Viewer, which lets you see whether the mesh, skeleton and textures load correctly without ever entering the game.

Preparing the model: skeleton, rig and export

The safest way to bring in a new model is to rig it onto the standard Metin2 skeleton. If you bind your model to an existing monster's skeleton hierarchy (keeping the bone names identical), you can reuse all of that monster's ready-made animations — you don't have to draw a single motion. If you use a completely new skeleton, you'll also have to produce your own motion files for every state (idle, attack, death).

The native export tool is the Granny exporter plugin installed on older versions of 3ds Max. The flow is usually: align the model and skeleton, prepare the textures as .dds, then export the mesh and each individual animation as .gr2. Watch the scale during export: Metin2 characters use a specific unit scale, and a model that is too big or too small will look absurd in-game or get a wrong hitbox.

.msm — binding the state machine

Even with the mesh and animations ready, the client reads the answer to "which file do I play while this monster waits?" from the .msm file. This text file maps game states to the corresponding motion .gr2 files. It roughly looks like this:

MotionMode  GENERAL
{
    Group  WAIT
    {
        MotionCount  1
        Motion0  "wait.gr2"  1.0
    }
    Group  ATTACK
    {
        MotionCount  1
        Motion0  "attack.gr2"  1.0
    }
}

The logic is clear: each state group points to the motion file to play and its weight. A missing group (for example not defining DEAD) causes the monster to freeze on death or throw an error. The most practical start is to take the .msm of a similar existing monster as a template and swap the file names for your own motions.

Index binding: npclist.txt and mob_proto

This is where the actual "binding" happens. The client identifies a monster by its vnum (proto number), but it learns which folder the model lives in from npclist.txt. This file in the client root maps the vnum to the folder path. Each line is tab-separated:

20101	monster2/new_monster	New Monster

The columns are, in order: vnum, the path to the model folder, and the display name. The vnum here must be exactly the same as the vnum of the mob_proto record on the server side. The server defines the monster with its stats (HP, attack, type, AI) in mob_proto and doesn't care about the model. The client, in turn, looks that vnum up in npclist.txt, finds the folder and loads the model. If the two sides use different vnums, the monster either appears with the wrong model or doesn't show at all. Since NPC dialogues and quests also reference this vnum, choose the number carefully from the start.

Granny version compatibility and common crashes

The most maddening error when adding a Metin2 model is a .gr2 file you found elsewhere crashing the client on startup. The cause is usually a Granny version mismatch: different client versions use different Granny runtimes (for example 2.4 versus 2.9), and a .gr2 written for one version cannot be read by another version's granny2.dll. The fix is to convert the model to your own client's Granny version, or re-export it with that version. Other common crash causes:

• Missing texture — If the mesh looks for a .dds that doesn't exist, you'll see a white/transparent model or an error. Check the material names and texture paths.
• Wrong path in npclist.txt — The folder name must match letter for letter; case mismatches or tab/space confusion make the model "not found".
• Wrong placement in the pack — Unless the files sit at the path that fits the client's archive (pack) structure, the game can't see them.

If you hit a crash, checking the client-side error logs and the syserr files speeds up the diagnosis.

Frequently Asked Questions

Is adding the model only to the client enough?

Adding the model and listing it in npclist.txt is enough for the visual to appear, but for the monster to actually exist in-game you also need a mob_proto record with the same vnum on the server. Without both, you end up with either an invisible monster or a vnum with no model.

Do I have to draw new animations?

No. If you rig your model onto a standard Metin2 skeleton, you can reuse all of that skeleton's ready-made motions and just map the file names in the .msm. New animation is only needed if you want original movements.

The client crashes on startup — what should I check first?

First check Granny version compatibility: is your .gr2 compatible with your client's granny2.dll version? Then check the texture paths and the folder name in the npclist.txt line. These three explain the vast majority of crashes.

Want to get your new model into the game cleanly? From Granny export to the .msm state machine and npclist.txt index binding, we can set up the whole integration together. Get in touch with me and let's talk about your project.