Purpose of this guide is to be as detailed as it can be. It's written by an idiot for potential idiots. I wrote it the way I'd understand it, if I found it online. If I'm too vague anywhere, tell me. Also, excuse any spelling and grammatical error, English is not my first language.

First, a list of the programs and tools used:

• Notepad++
  
• Highlighting rules for Valve languages (script in .vmt, .smd or .qc files)
  
• 3DS Max
  
• Wall Worm Free
  
• Crowbar
  
• VTFEdit
  
• GCFScape

Just google it to find the download.

Little mistakes happen to everybody. Good that they're really easy to fix (most of the time).


Symptoms:
Your model will usually look black and pink checkered, like this:



Obvious Troubleshooting:

• Is your material in the right folder? It has to be in the "custom\"-folder like this: \insurgency\custom\<YOUR MOD NAME>\materials\models\weapons\
  
• Is the name of the VMT file correct?

Troubleshooting:

• Does your model refer to the right VMT file?

To check this, open Crowbar, enter the "View"-Tab and load your compiled MDL-file.
On the bottom of the info-field, it'll show you the names and positions of the VMT used by the models inside of the MDL-file, like this:
As you can see, the engine will attempt to open the file "usp_tactical.vmt". If there's something else, you haven't applied the right material to the model in your modeling program.

Solution:
It takes no time to fix that in 3DS Max. You don't have to assign a texture to the model that has that name. Instead, change the name of a material in the 3DS Max Material editor and apply it to the model. This will have the same effect.



Now export the reference model again and check it in the HLMV.


Symptoms:
Shading of the model doesn't look how it's supposed to be.

Obvious Troubleshooting:

• Is your VMT-material properly set up? Does it use basetexture, bumpmap and phongexponenttexuture?
  
• Are your VTF-files named properly, referred to properly and in their respective folder?

Troubleshooting:

• 
  
• Are your different texture maps in the respective alpha channels?
  
• Are your VTF-files set up correctly? This means no specific flags set like "Render Target" or s

Solution:

• Set up your VTF flags correctly:

Anisotropic is the minimum, Eight Bit Alpha is also needed when you use an alpha.
Make sure that you export your VTF-file as DX3 or even better, DX5, so it supports the alpha channel. DX1 does not support an alpha channel (actually it does but only monochrome).

Make sure that texture referencing is correct and that you use the right texture in the right alpha channel. Here's an overview:

• $basetexture = diffuse map (albedo map, if you prefer PBR)
  
• $bumpmap = normal map
  
• $phongexponenttexture = gloss map (microsurface map)
  
• $normalmapalphaenvmapmask = specular map (reflectivity map), stored in normal map alpha channel
  
• $rimlightmask = gloss map alpha channel

I might have swapped microsurface and reflectivity to their respective last gen texturing counterparts (accidentally).
For more info on VMT, check the link: VMT Guide on Facepunch[facepunch.com]

Symptom:
ADS ingame acts strange. Either the hands disappear, hands + weapon disappear completely or the hands are messed up and the weapon is gone.

Troubleshooting:
Aiming down sights and a few other things are handled by so called "delta"-animations. In this case they're used to re-position the gun.
These animations and their part in the QC-file will break when decompiling. In short, you have to create them yourself and edit the QC-file.

Solution:

• To fix your QC-file, search for lines like these:

Read the text in it. It explains what's happening. Now replace the "slide_base"-part with "idle". After that it should look like this:

Do that for all deltas. Note that if you have the grenade launcher delta, don't use "idle" but "gl_idle"

• Fixing the delta animations

For you who use blender, I refer to these guides:
Tiggs' INS tutorial
Blender to Insurgency tutorial

I use 3DS Max. Fixing it there requires merely a few steps:

1. Open your model reference in Max
   
2. Import the idle animation file for the respective delta. This is important.
   
3. Go into key frame mode, select everything, every bone and model
   
4. Move the whole selection so the iron sights of the gun are in the exact middle. See screenshot below:
   
   The black lines mark the middle of the screen
   
5. Set a key frame. Copy and paste it to make sure that the position of the weapon is in this position for frame 0 and 1 or so
   
6. Export the whole construct as a sequence file, export frame 0 and 1 or even only frame 0. It's all about the position

Recompile. It should be fixed now.

On a side note, I recommend getting the resource files from Tigg's video I referred to above. There's a reference file for the heights of the different sights in the game.

Problem:
After my model hack, the suppressor/laser/torch/whatnot isn't where it belongs to even though you have changed the position of the bone inside of 3DS Max. It will look similar to this:



Troubleshooting:
That happens because you use an existing animation and paste your model over it. In the animation, the bones are still in their original position.

Solution:
There are several solutions to this.

At this point I refer to the two tutorials again. They explain how to do this but in Blender. So if you use Blender, watch/read these. I use 3DS Max so the process is a different one.

Here's a totally dowdy solution that merely requires you to know how to use Notepad++. This solution should be used as the very last step, because every time you change an animation then you have to repeat it for that animation.
Honestly there are probably better solutions but I don't know them. Feel free to inform me.

1. Position the bones (in this example A_suppressor) where you want them to be in the model reference file and export it
   
2. Open the reference file in Notepad++ (the highlight language package is neat here) and search for the line where it mentions your bone first like
   
   65 "A_Suppressor" 63
   
   The first number is the number of the bone. The quotation stuff is the name of the bone. The last number is the number of the bone it's linked to.
   
   
3. Keep the first number in mind. Scroll down to the first frame and copy the values behind it like
   
   65 0.00450897 -3.31931 0.651911 0 0 3.14159
   
   These are the XYZ coordinates as well as the rotation. Copy them and paste them in an empty Notepad++ page
   
   
4. Open a random animation and repeat the process in there. The coordinates you find there will be in every other animation as well
   
5. Now open ALL animation files in Notepad++. Simply select all of them in your explorer and drag them into Notepad++.
   
6. Press CTRL+H to open the Replace-window.
   
   • Into the "Find what" field, enter the whole line you copied from the animation
     
   • Into the "Replace with" field enter the whole line you copied from your reference, the
   coordinates where you want the bone to be
   
7. Press "Replace All in All Opened Documents". This might take a short time. For the pistol animations, there were about 650 occurrences.
   
8. Repeat this step for every bone you want to change.
   
9. In Notepad++, press the "Save All" button. Done

As I wrote before there are probably more elegant solutions to this. 3DS Max supports animation layers, which maybe enables you to edit the first frame of every animation, but I have never used this. Perhaps it's also possible to create a copy of the bone at the right position and use $bonemerge in the QC-file to reposition the old bone. I don't know and that's why I'd be happy about some input there.

Problem:
After recompiling the model, none of the animations work anymore. The model just has the default position from the reference file and doesn't respond to any of the animations.

Troubleshooting:
This happens because the decompilers for .mdl-files are still not perfect and have problems decompiling for example the .qc-file. This kind of problem probably won't happen if you make animations from scratch with a custom rig, only if you do model hacks.

Solution:
Follow this guide step by step
Model hacking the easy way! by Mr. Brightside[mrbrightsideanimator.net]
It works.

You've reached the end. I hope I could help.
I'll update this guide whenever I solve another problem I'm stuck with or find a better solution to one of the problems already described here. Thanks for reading.