Metin2 Model Files: .gr2 Format, .msm State Machines, and npclist.txt Binding

Sat Oct 17, 2026 5:40 am

Metin2 Model Files: .gr2 Format, .msm State Machines, and npclist.txt Binding

Adding a new monster, NPC, or mount to Metin2 is one of the most common modding tasks, but it trips up almost everyone the first time. The problem is not any single file. It is the relationship between three files that all need to agree: the .gr2 model, the .msm state machine, and the npclist.txt index. Get one wrong and the model is invisible, crashes the client, or shows up as a different monster entirely.[1][2]

Understanding the .gr2 Format

The Metin2 client uses the Granny3D runtime (granny2.dll) to render all character and object models. Every mesh, skeleton, and animation is stored in .gr2 files. A single .gr2 file can hold just a mesh, or it can carry a skeleton and motion data too.[1]

The common approach in Metin2 is to split things up: one file holds the mesh plus skeleton, while separate files carry each animation (walk, attack, death). For a model to work in-game, these three components (mesh, skeleton, motion) must be compatible with each other.[1]

Each monster or NPC lives in its own folder inside the pack archives, usually under

Code: Select all

monster2/

for monsters or

Code: Select all

npc/

for NPCs. A typical folder contains:

Mesh .gr2: The model with its skeleton, usually named
Code: Select all
```
model.gr2
```
Motion .gr2 files: One per animation (idle, run, attack, damage, death)
Texture files: Usually .dds in DXT compression, must match the mesh material names
.msm file: The Monster State Module, a text file defining which motion plays in which state

You can inspect all of these files with Granny Viewer, which lets you verify the mesh, skeleton, and textures load correctly without entering the game.[1]

The .msm State Machine

The .msm file is the answer to "which animation does the client play right now?" It is a text-based state machine that maps game states to motion files. A basic .msm looks like this:[1]

Code: Select all

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

Each state group points to the motion file to play and its weight. A missing group, for example not defining

Code: Select all

DEAD

, causes the monster to freeze on death or throw an error. The most practical approach is to take the .msm of a similar existing monster as a template and swap the file names for your own motions.[1]

Skeleton Compatibility

The easiest way to add a model is to rig it onto the standard Metin2 skeleton. If you keep the bone names identical to an existing monster, you can reuse all of that monster's ready-made animations. You do not need to create a single motion file.[1]

If you use a completely new skeleton, you have to produce your own motion files for every state (idle, attack, death). This is significantly more work and requires access to the Granny exporter plugin for 3ds Max.[1]

Watch the scale during export. Metin2 characters use a specific unit scale, and a model that is too big or too small looks wrong in-game and gets a wrong hitbox.[1]

Binding with npclist.txt

The client identifies a monster by its vnum (proto number). It learns which folder the model lives in from

Code: Select all

npclist.txt

, a file in the client root. Each line is tab-separated:[1]

Code: Select all

20101	monster2/new_monster	New Monster

The columns are, in order: vnum, path to the model folder, and display name. The vnum must be exactly the same as the vnum of the

Code: Select all

mob_proto

record on the server side.[1]

The server defines the monster with its stats (HP, attack, type, AI) in

Code: Select all

mob_proto

and does not care about the model. The client looks up that vnum in

Code: Select all

npclist.txt

, finds the folder, and loads the model. If the two sides use different vnums, the monster appears with the wrong model or does not show at all. Since NPC dialogues and quests also reference this vnum, choose the number carefully from the start.[1]

The Mob Proto Format

The

Code: Select all

mob_proto

table on the server side uses the MMPT format, which is then crypted as a Crypted Object. The Crypted Object format has a 20-byte header followed by the crypted or compressed data. The header contains a FourCC code, sizes for crypted, compressed, and real data, and a verification code.[2]

The XTEA encryption keys for Mob Proto are known and documented. The key (16 bytes) for Mob Proto is:

Code: Select all

46 74 49 00 0B 4A 00 00 B7 6E 08 00 9D 18 68 00

.[2]

Common Crashes and How to Fix Them

The most maddening error when adding a Metin2 model is a .gr2 file that crashes the client on startup. The causes, in order of frequency:[1]

Granny version mismatch: Different client versions use different Granny runtimes (for example 2.4 versus 2.9). A .gr2 written for one version cannot be read by another. The fix is to convert the model to your client's Granny version or re-export it with that version.[1]
Missing texture: If the mesh looks for a .dds that does not exist, you see a white or transparent model or an error. Check the material names and texture paths.[1]
Wrong path in npclist.txt: The folder name must match letter for letter. Case mismatches or tab/space confusion make the model "not found".[1]
Wrong placement in the pack: The files must sit at the path that fits the client's archive (pack) structure. If they are in the wrong location, the game cannot see them.[1]

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

Model Folder Structure Summary

Here is the complete checklist for adding a new monster or NPC:

1. Create the mesh .gr2 file with skeleton (or rig onto an existing Metin2 skeleton)
2. Create or reuse motion .gr2 files for each state
3. Prepare texture files in .dds format matching the mesh material names
[*>4. Create the .msm file mapping states to motion files
5. Place all files in the correct folder inside the pack archive (
Code: Select all
```
monster2/
```
or
Code: Select all
```
npc/
```
)
6. Add a line to
Code: Select all
```
npclist.txt
```
with the correct vnum, folder path, and display name
7. Add a matching
Code: Select all
```
mob_proto
```
record on the server with the same vnum
8. Verify Granny version compatibility with your client's granny2.dll

Steps 1 through 4 are client-side only and enough to make the model appear. Steps 7 and 8 are server-side and required for the monster to actually exist in-game with stats, AI, and drops.[1]

Sources

[1] Aslain.dev: Adding a Metin2 Model (.gr2 Files and Index Binding)
[2] Metin2Dev: File Formats Documentation

Information