This guide shows how to port weapon mods to other slots.
Any firearm onto any other firearm, and any melee onto any other melee is possible.
You could technically also port gasgans to propanetanks, or other such nonsense, but this guide is more about firearms and melees.

You should at least have basic knowledge on how qc files and animation setups work.
Porting a weapon to another slot is not a beginner project that you can finish in a few minutes.
You've been warned.

Also, there's multiple ways of getting the same result, for a bunch of steps in this guide.
But since this is my guide, i'm showing you my way. My Guide, my rules.

Limitations:

• Shotguns can only be ported to other shotguns. No matter the tier.
  
• Deagle and one handed pistol can only be ported between eachother.
  
• Dual wield pistols are unique. Nothing can be ported onto it.
  
• Melee weapons have attacks where the weapon travels from one side of the screen to the other, but not every melee weapon has the same directions.
  Which means it will look weird when you swing to the left, but the CI falls over to the right.

While it is technically possible to "port" any weapon to any slot, you would need to edit all animations in blender to make them work as intended. Which is outside the scope of this guide.

All we're doing is taking one gun and moving it to another slot, by altering the animation speeds.

I had to completely reupload about 70% of all images, three times.
If you see a suspicious lack of images in this guide, let me know!
I should have about 120 images on here.

"New" mods that were built according to my weapon making guide have all anims blended.
But they should have a backup of working anims, if the modder followed the steps properly.
Decompiling these blended animations results in broken, and therefore unusable animations.

Fixing those is apparently possible but I do not know how to do that.
This guide will not mention how to repair those animations. If I find out how, I'll update the guide.

All mods made before September 24, 2020 will most likely be easy to port.
All mods after, might be harder to port because there's a chance the anims may be unrecoverable.

More about that later though.
I just wanted to give you a heads up. If your mod is new, you could be unable to port it.

Required tools

Optional Tools

First, download a mod you want to port.

I'm going to use this Ak47 mod and i'll be porting it to the hunting rifle.

The developer attempted to corrupt the files to stop people from editing his mod.
I'm here to show you how to undo his attempts at protecting his mod. Lmao.

Download this mod using crowbar.
Copy the mod's url into crowbar's Download tab and download it anywhere you want to.


Drag the vpk onto crowbar, or press the "Use in Unpack" button on the bottom right.
In the Unpack tab, just click the Unpack button.
You'll get a folder where all the mods files are present.


We'll need to get the original weapons, so that we can decompile them and use their qc files.
Head to "steamapps\common\Left 4 Dead 2\update"
Open the Pak01_dir.vpk.

The Viewmodels are in models/v_models/
The Worldmodels are in models/w_models/weapons

However, valve gave the viewmodels and worldmodels mismatched names.
This table here tells you which models belong together.
I will need the hunting rifle, so i'll use v_huntingrifle and w_sniper_mini14

You need to get the mdl,vtx,vvd and optionally phy file for the worldmodel.
The hunting rifle has an .ani file. you can ignore it. It's just for animations which we won't use

Just drag and drop em right out.

Decompile both the original weapon models and the one of your mod.
Just drag and drop the extracted mdl file onto crowbar to get to the decompile tab.

If you swap the "MDL Input" to "Folder" you'll decompile all mdl files in that folder.
You could move all model files into the same folder and compiling all models at once.

Set the "Output to" to a folder you want. the Qc and smd files will be put there.

The Animations shown in the blue box are only required for the custom weapons viewmodel.



If your decompile works flawlessly, skip to "Checking Animations"

If you get the error below, look at the next "Removing Protection" section.
ERROR: Model version 956301362 not currently supported.


If you get any other errors, Read them.
They pretty much tell you right away, in literal plain english, what is wrong.
I no longer want to help people trying to find out what " WARNING: VVD file not found." means.

Some people think that it is a cool idea to edit the model to stop you from decompiling it.
Fortunately, getting around it is faster than it took the guy to "protect" it. Lmao.

This is because the modder took his time to edit this part of the model with a hex editor.


You can easily unto the edits in the hex editor yourself.
Except that crowbar literally has a button do just force the model version for you!
Make it override the model version to 49. Which is what L4D2 uses.
Then try decompiling it again.


For textures:
The same person that tried his best editing the model file also laid their fingers onto the textures.


So we'll just undo what he did.
Either use a dedicated hex editor like HxD or something like Notepad++ with it's HEX plugin.
I use Hxd because the next step would require copypaste which Hxd supports.

Load the VTF file.
The top of a normal VTF (version 7.2) should look like this.

But the one he gave us was this


Do you notice how on the first line, the P on the original turned to a Q, and how the second line turned a " to a space?
Just swap it back to a P and a ", then save it.


Now.
This is just for 7.2. because different vtf versions have different headers.
If you installed the "VTF Shell Extensions", you can see what vtf version the vtf should have:


If you know what version it should be, you can use HxD to replace the header entirely.
For that, just open the corrupted VTF in Hxd, highlight the first two lines as such:


And then replace it with the correct string for whatever version you need:
7.0
7.1
7.2
7.3
7.4

Intermission over. back to working on the models.

As I mentioned in "Broken Animations Warning", some mods might use blended animations.
If the mod you're trying to port has blended animations, you will not be able to port the anims.
However, the non_layers should be intact, if the modder was considerate/smart enough.

Now we're about to find out if you are lucky, or if you got shafted.

Open the QC file of your gun that you want to port.
Scroll down until the animation block starts.
If the first things you see are "Corrective Animations" you'll know those listed anims are broken.
However, as long as only the _layer sequence has corrective anims, you might be lucky, because we might be able to use the non_layer version of the animation instead.


In the screenshot above, there are corrective_animation lines for the "look" and some _layers.
The look pose is always broken. Don't worry about those.
If you only have corrective anims for layers, the non_layers could be used instead.
If you also have corrective animations for non_layers, all the anims might be broken.
We'll load the animations into blender to find out if we can use them.

Warning: Even if the non_layer sequence is in tact, it is possible that it is not the same movement as the _layer sequence. You will need to pay attention to how the gun moves.

Open blender and install the smd plugin.
The page of the plugin has install instructions. Don't even dare to ask me about it.

Load the model smd first.


Select the armature. Either in the outliner, or by clicking on one of the balls around the gun.
Then use the "import SMD" function again.


Now we'll open the "animations" folder and load the hopefully not broken animation.
In my case, melee_layer was blended, but melee was not.
So I will import the melee sequence, while "append to target" is picked.
You can import whatever non _layer animation you want to check.
You might need to click on the cog icon in the top right to get that option menu


If you can see spheres that resemble the general shape of hands and fingers, you're good.
This anim can be used for the _layer sequence.


If all spheres are in the same spot and the weapon is sitting in the center, the anims are unusable.


If you are lucky, you can now port the gun knowing the anims work.
If the anims are broken and there's no intact anims or source files, your journey ends here.

There is, theoretically, a way to repair the broken anims, but i do not know how to do that (yet), and even then, you'd never get the anims 100% like they used to be.

Now we can finally start porting the mods data.

Decompiling the models gave you QC files for both the original weapon model and the mod.
We will edit the original qc file, which we got from decompiling the vanilla l4d2 weapon.

This is because the animation order, lenghts, names and other data like $bbox are different.
This data must never change. Else the wrong anims play online, or other funky stuff happens.

We're not going to just replace the entire attachment, animation or sequence block. Nope.
I know a whole bunch of people will not care, but we're going to do it properly or not at all.

Open both view QC files in Notepad++.
You can make Notepad++ load one of the qc files into "other view", to see both at once.


First, we'll copy all the data that we need to port over as-is.
Replace the bodygroups and cdmaterials of the vanilla weapon with the ones of the mod.

Some weapons have skins now. They're only seen in special locations.

If you're porting to a gun that uses texturegroups, you will either have to make skins for the texturegroup slots, or remove the entire texturegroup section if you don't want to make skins.

If the mod you're porting has texturegroups, but the gun you're porting to does not have them, you can also delete them. Because the game won't ever load these skins unless a mapper specifically made a map to load random skins (Or if you install a mod that randomly picks skins).

Now we'll port over the attachments.
Copy each $attachment line of your mod into the vanilla qc file.
You can't copy all at once, because the attachment order of the vanilla gun must be kept as is.
If your mod has an attachment that the vanilla gun doesn't have, add it below the others.

Your mod may use "Attach_shell_eject". The TLS update swapped it to "Muzzlesmoke".
You can replace the "Muzzlesmoke" attachment with your mods "Attach_shell_eject".



Now for the definebones.
Check if your mod has custom bones in the definebones.
They should be listed below "ValveBiped.Bip01_L_thumbroot".
If you have any, copy them underneath whatever the last $definebone line of the vanilla gun is.

You can do the same for $bonemerge. But you might not have the custom bones in that list.

If the mod you're porting has jigglebones, copy those over too.
If the vanilla gun has jigglebones, delete those. You will not use them anyways.

The hunting rifle is the only firearm that uses this line.
Having this line should make the compiler store animation data inside an .ani file.
Just keep this line in the vanilla qc if you have it.

It may, or may not, make an .ani file for you later. For me, it didn't make one.
If it does make one, you'll ship it with the vpk. Don't worry if you don't get one.

Things are about to get a little confusing in a moment.
There's a lot of stuff you need to know before working with animations and sequences.

The animations you're porting won't look exactly the same ingame.
At least the speeds will be changed by altering the fps later in the $sequences.
The animations aren't made for the timing we need, so we have to change their speed.
You may get odd fps like "37.254", which can cause the animation to be a millisecond off.

Animations can be built using three things:

Delete the weightlists of the vanilla qc file.
If the mod you are porting has $weightlists, you will need to copy them into the vanilla qc.
Even if you end up not needing them.



Delete all $Animation lines of the vanilla gun's qc file.
Since we're going to add animations from another mod, we'll need to redo all $animation lines.


We need to add new $animation lines now.
These $animation lines will define which smd to use, set the FPS, and more.
We'll need an $animation for every $sequence we have.

It's possible that the mod you're porting has two different run anims for forward and backwards.
Check the QC of the mod you're porting.
If its idle sequence lists three different animation names, then you have a second walk anim.
If, however, it just lists a_run, a_idle and a_run again, then you only have one set of run anims.
Should you have two distinctive run anims, just add another $animation line for that run.

Alternate firing, reload and melee animations, as well as "Fidget" animations are also possible.
There's the "Fidged & Extra Anims" section that has more details on specifically that.

For now, copy this block above your first $sequence:

For melee weapons you have "swing" sequences instead of firing and reload.
Also the "push away" is called "secondary_swing" instead of "melee".
You'll need one $animation for each of those swing sequences. If you don't know how many, you'll need, you will find out later. So just jump back and forth through the qc to add more $animations if you have to.

While we're talking about animations before we actually work with them:
Some weapons have a different amount of animations for the same task.
For example, the SG552 has three firing animations, the tonfa has two melee push, the guitar has five basic swings, while the frying pan has only two, ect.

If you are porting to a weapon with more anims, you'll need to reuse the ones you have until all the "slots" are filled with the anims you have. Even if you need to use one anim three times.
Which means the SG552's "shoot1", "shoot2", and "shoot3" will all use your "a_fire" $animation.

If you're porting from a weapon with more attack/melee/swing anims, you have two choices:

1. Only use as many anims as the weapon you are porting to has, so you will lose anims.
   
2. Add the extra animations the same way that "alternate reload" and stuff is added.
   More info on how to do that in "Fidged & Extra Anims"

Now we need to assign the animation smd files to these $animation lines.
Your mod will probably already use a_idle and a_run. you can copy its fps settings over as is.
Animation length doesn't matter for: Idle, Run, Helping_Hand_loop & Item_Extend_Loop.


Check the mod you want to port and copy over the pieces of text that mention the anim smd file.
Of course you need to pick the animation smd files that are not broken.

If you're porting to the hunting rifle, check this out. Else, skip ahead.

The hunting rifle has unused $sequences. Both non_layer and _layer.
You're not allowed to delete them, but you can render them inert.
To do that, copy the block of text below replacing the respective lines in your QC.

And these below the reload $sequences

Swap the "dud" for whatever smd your $BodyGroup line at the top of the qc uses.
If you have multiple bodygroups, just use any of the smd files.

The first $sequence is probably the lookpose for you, so we'll start with that.

The lookpose $sequence changes the pose when aiming up/down and are not required.
Lookpose animations were blended and therefore always broken when decompiled.
For now, we will just make them useless, so that we can at least compile the model.

I'll explain how to make new lookposes later.
I'm showing how to "remove" the lookpose first because most people i've helped porting models delete it anyways. It makes more sense to make "fixing lookposes" an extra optional step later.

Find the lookpose sequence by using the search function and looking for blend "ver_aims".
Whatever sequence it is should list three animations.
Usually its $Sequence "look_poses", but the hunting rifle uses "a_sniper_arms_vaims".


If you are considering to use lookpose later, swap all used animations with your model smd file.


If you know you don't want lookposes, swap all of it with the model's smd file instead.


The lookpose must not be deleted. You're only allowed to render it inert.

Go to the idle sequence and comment out the "addlayer" line, by ading // to the start.
This will remove the link between the inert lookpose and the idle animation.
If you have any other $sequence lines with the addlayer, remove those aswell.


Next, the idle sequences.

Most weapons use "Idle_raw" and "idle". Some use "idle" and "idle_layer". Some only have one.
"Idle" morphs between "Standing still" and "walking" depending on how fast you move.

Set the walk and run order up just like the mod you're porting.
Also check the numbers after "Blend move_x" sometimes its -1 1, other times its 1 -1.
Copy whatever the mod you're porting does.

The next sequences appear twice. Once without a _layer suffix, and once with.
Some anims like the military sniper melee_layer does not have a non_layer counterpart.

For some reason, the "non _layer" $sequence acts as a timer.
The "_layer" $sequences are what you actually see in the game.

Example:
You reload the gun. The game triggers the "reload" and "reload_layer" sequences to play at once.
You can see "reload_layer" moving the gun, while the "reload" runs in the background.
When the "reload" sequence ends, your input is unlocked and you can fire again.

No matter if "reload_layer" is still playing or not. If "reload" ends, you can dispense bullets again.
If "reload" ends before "reload_layer" you can cancel the visible animation and shoot again.
If "reloay_layer" stops moving before "reload" is done, you have to wait until you can shoot.

Usually, both the non_layer and _layer sequences have the same amout of frames.
But for us, this won't be the case. We will need to make a fake non_layer as a timer.
Afterwards, we will need to change the speed of the animations we want to port so that they play for the correct amount of time.

For now we will only set up the non_layers.
Fortunately, that is easily done by using $sequence command called "Numframes".
Numframes allows us to make up any lenght of animation without actually having a smd for it.

Open the Animation Lookup guide in a new tab.
No need to read any of the text stuff there, because I'm explaining the important bits right here.
https://psteamcommunity.yuanyoumao.com/sharedfiles/filedetails/?id=1483047118

Find the gun you want to replace.

Look at one of the non_layer $sequences listed.
"sniper_shoot1" has 30 frames at 30 fps.

Look for that $sequence in your qc.
Make it use the model's smd then add "Numframes 31" to make it end on frame 30. (yes*)
Followed by adding "fps 30" to make it play at 30 frames per second.
This will make sure our "timer" is exactly as long as it needs to be.

The non_layer sequences only need an smd, numframes, fps, and the activity name.

*Animation smd's begin on frame 0, while Numframes begin on frame 1. So, if you use "Numframes 30", you'll only get frames 1-30, with frame 0 missing. Therefore, the actual end frame would be 29. That's why you need to always add one more "numframe".

You need to add this setup to every non_layer $sequence that has a _layer counterpart.
Make sure that you're using the correct numframes and fps.

Some $sequences do not share the same name, like "sniper_draw" and "sniper_deploy_layer".
But the ones that belong together are always back-to-back, so it's easy to figure out.

Now that we set up the non_layer and idle $sequences, we can do the _layer $sequences.
Do that by assigning all $animation names to their appropriate $sequence


You can make the layout look any way you want, as long as you use { } for when its multiple lines.
I just like making it look like this, with the non_layer and the _layer being aligned like that.

Time to take care of the events that the _Layer $sequences use.
Events trigger a particle or sound to play, at whatever frame you tell it to.
Delete the events of the vanilla qc and use the ones of the mod you're porting instead.



Do this for all _layer sequences you have.
If you see a non_layer with events, you can delete them. Events do nothing on non_layers.

While you're handling the _layer sequences, you should also check the Fadein and Fadeout.
These settings define how many seconds this specific animation fades in or out for.
If not set, both Fadein and Fadeout default to 0.2.

There's a third option called "Snap", which forces the animation to stard without fading in.
Snap is required for Draw/Deploy to make it look good. It might also be good for Melee.
Check if your deploy has fadein. If it does, replace it with just "snap" without a number.

Not using Snap for deploy causes the gun to appear in the idle pose before moving offscreen, just to enter your screen again. But with snap, it starts offscreen as it should.

When you copy-pasted all the events, you also copied the soundnames, which are now wrong.
The events I copied used AK47 sounds, but it should be using Hunting Rifle sounds now.


You could use the "search and replace" tool to look for the sound name prefix and swap it.
Make sure you actually use "NAME. not just the gun name.


Warning: some weapons use different names for some sounds.
The AK47 uses "SlideBack" and "SlideForward".
The hunting rifle uses "BoltBack" and "BoltForward".

The "Viewmodel animation lookup guide" has a list of all weapon sound events at the bottom.
You can look at that for finding out what sound events you can use if you are not sure.

Here's some info you should know before porting anims.

Some people use the ability to interrupt anims by making them longer on purpose.
You'll have to pay attention to the animations you're porting, to avoid porting them wrong.
Traditionally, nothing can be skipped. But some weapons were specifically designed for this.

Example:
Lt.Rocky has made a weapon mod that replaced the M60 with a minigun.
The "fire" sequence is 30 frames at 30 fps, which is default. (1 second)
The fire_layer sequence is 176 frames at 40 fps. (4.4 seconds)
He animated the barrels to spin out for 3.4 seconds after the firing anim "would" be over.
This allows you to shoot the gun while the barrel is still winding down.

Another example:
Some people make reload anims where the animation can be interrupted after inserting the magazine, just like some video games to it nowadays.

So for those types of animations you have to pay attention to when you want it to actually stop.
Which can be done by loading the animation in blender, checking which frame your "end frame" should be, and then just using it for the calculations instead of the actual end frame.

Now is the part where we change the speed of all the animations to make them work properly.

We'll need to do three things per animation to make sure they'll work as intended.
I'll explain in detail how to do it in a minute. Just a quick overview of what we're doing.

1. Check how many frames the animation of your mod has.
   Or if you want an interruptable animation, find what you want its end frame to be.
   
2. Check the original $sequence's Framecount and FPS.
   
3. Calculate what FPS you need to play your animation at, to make it fit the timeframe.

First, check how many frames the animation has that you're porting to.
This is done by using my Animation lookup guide.

Let's take the melee animation as an example. 35 is its endframe, at 40 fps.
We're always going by the non_layer sequence, because sometimes it's the timer.

Open the animation of your mod in notepad++, search for "Time" and use "Backward direction".
Or just scroll to the every bottom and then up until you see the first "Time" from below"


This is the last frame of our mods melee animation.
Maybe write it down somewhere, just in case we might need it.

Also, here's a gutpunch and a suckerpunch for you melee porters out there.
Not only do you have to deal with directional attacks, but the timing can be off too! ∠( ᐛ 」∠)＿

Every melee weapon has different animation lengths, so make sure the animations you are porting replace an animation that has similar speeds.

Here's a visual explanation of what I mean.


The animation names mention travel of the melee weapon.
The bottom most anim of both are W_E. From West to East. Or left to right.

The Pitchfork's w_e anim is one second, while the machete has 0.714 seconds.
Based on travel of weapon alone, these two belong together. So the CI falls to the correct side.

But if you consider the animation time, the machete has a super short 0.575 second anim, while the shortest pitchfork anim is 0.75. To avoid drastic anim speed differences, match the longest anims together, then the second longest, up until the shortest anims are together.

Which means:
The Pitchfork's 0.79s s_w goes to the Machete's 0.714s w_e
The Pitchfork's 0.78s w_nw goes to the Machete's 0.575s e_w
The Pitchfork's 1s w_e goes to the Machete's 0.725s ne_sw

So now we got the numbers for the calculation
Algebra time!



24 is the FPS you need in the melee_layer $sequence to play at the proper speed.


Sometimes you'll get decimals, like "27.684235". The game accepts decimals, don't worry.

You can, if you want, round it down so its ever so slightly slower, or up to make it faster.
If you round down to a lower fps, you'll be able to skip the last few milliseconds.
If you round up to a higher fps, you may end up seeing a few milliseconds of no movement.

If you see that the animation stops too soon when testing the mod, lower the fps by decimals.
From 24 to 23.5 or so. It doesn't need to be exact because you'll have a fadeout anyways.

Except shotgun reload anims. (And the extending/retracting hand anims, for the same reason)
Those three reload, reload_loop and reload_end anims are "Sandwiched together".
The fps must be as precisely as possible to avoid glitches in online play.
I've made a mod where the reload_loop is a little too long, so the hand enters the screen with a new shell before it even left the screen from the previous looped anim.

But for now, just calculate the required FPS for all other _layer $sequences.
Check framecount (or desired end frame) of the anim you port, divide if by the endframe number of the original as seen in my lookup guide, and then multiply it by the fps of the original non_layer sequence.

You can either add the FPS to the $sequence as in the screenshot above, or into the $animation

It's possible that the weapon you're porting has fidget anims, or an extra set of melee/reload.
They're not required for the gun to work, but you can port them if you want.

Or, as mentioned way earlier, porting from a SG552 to any other rifle could mean you have three different firing anims. While Porting a guitar mod to the frying pan means you'd port five attack anims to a weapon that only supports two attack anims by default.

1. Copypaste its original $animation lines into your qc, or create new ones.
   
   
2. Copy its $sequence lines right to the bottom of your qc.
   
   
3. You'll need to edit the _layer to use the intact animation. Like we did with all other anims.
   
4. Make sure you actually have its weightlist, if it uses one.

This, ofc, assumes that the person who made the fidgets made them properly.

Adding extra anims is easy, but there's one extra step required for when you're porting a melee weapon with lots of anims to another with less anims. But that extra step is recalculating fps.

The normal "having another reload" is already based on it needing the same animation length.
Which means you just need to dupe the $animation, $sequence, and rename them.

But when you add extra anims because you don't have enough "slots" for the additional attack anims, you might need to recalculate the fps for every additional anim.
Because each animation of the melee you're porting to or from can have different framecounts.

For example, the pitchforks attack anims use 27, 25, and 32 frames.
Same with the SG552. "Shoot3_layer" has five more frames than Shoot1 and 2.

Either ways, start by doing the following:

1. Make a dupe of your $animation lines that you have alternate anims for and just give them different names, while also using the alternative animation filename.
   
   
2. Copy the original $sequence lines for that animation.
   For melee weapons, dupe an animation that has the closest animation lenght, as i had described in "Note 5".
   
3. Scroll to the bottom of the qc and paste the copied $sequence lines.
   
4. Change the sequence names and the used $animation name in the new _layer.
   
   
5. Check the original qc file, to see if that mod has a specific "weight" for those sequences.
   If the number after the activity is anything but one, then you should make your new extra sequences activity use the same number.
   
6. If you're porting a melee weapon's extra attack anim (Or the SG552's third firing anim) you'll need to recalculate the FPS of that sequence again.
   Don't forget to keep track of which animation to port to, based on lenght.

Remember when I said blended anims break on decompile?
The reason they're blended to begin with is because they look better to some.
It allows the idle, running and lookpose to be visible at all times. So that when you're shooting while running, the gun still bobs up and down because of the run animation.

If you want that blendy goodness, add "Subtract a_idle 0 Delta" to the _layer $sequences.
Except helping hand and item_extend, those look weird and buggy when blended.
But again, it will break anims for whoever decompiles it next.

Should you want to keep a backup of these animations inside your own mod, you can add another block of $animation lines with different names.
These won't be blended, and therefore won't break when your mod is decompiled.

You could also slap the animation smd files right into your vpk, but this inflates the addon size.
Some people also upload the source files to google drive and share a download link.

But in the end, it really doesn't matter to keep a backup of the anims.
I prefer to have a backup because I wanted to update a mod later to fix an animation, but i lost the source files so i had to decompile my own mod. All anims were broken and I couldn't do crap.

If you do not want to make new lookposes, skip this section.
This takes about five minutes, so let me just give you the cliff notes.
Else reading the steps takes longer than performing them.

Load the gun model into blender
Select the armature object, then import the idle animation onto the armature.


Delete all keyframes except the first one in the Dope Sheet (Or Action editor, same spot)


Move the first frame over from Frame0 to Frame1


Either enable auto keyframes, or after posing the gun manually save the keyframe using "i".


Enable the cursor as your pivot point.


Press Shift+C to center the cursor to the origin.


Enter side view of the mesh in pose mode.
Select the "ValveBiped.Bip01_Spine4" bone and the weapon bone.
I'm going to do a super duper simple lookpose based on movement data I always use.
On Frame 0, rotate the gun to point upwards by ~1.5° and move it towards the camera by 1.
On Frame 2, rotate the gun to point downwards by ~1.5° and move it away from the camera by 1.
You can use left and right arrow to jump between frames.

Frame 0 is what you get when you look down, while frame 2 is the pose for looking upwards.

Name this animation "lookpose"


Pick the folder containing your qc as export destination, and export the animation.

In the QC, add the following $animations above the lookpose sequence:
Link up the $animations and uncomment the "addlayer" in the idle $sequence.


Done. Moving on.

Ikrules (Inverse Kinetics Rules) allows bones to lock to other things.
In the case of weapons, it just makes the hands follow the gun bone properly, because for some reason, these hands lag behind and don't properly adhere to the gun sometimes.

The qc you've been editing all this time has a bunch of these weird looking Ikrules.


Those will most likely not work properly.
If you compile the mod and you can see the hand not properly adhering to the gun, while the rest of the weapon movement itself is correct, then those ikrules are bad.

You can fix them by using the following ikrules for a_idle, a_run and every _layer sequence where the hands fully adhere to the weapon.
Do not add ikrules to non_layer sequences, because the elbow location messes up by doing that.
If one of the hands lets go of the gun, like reload, helping hand and melee, you might want to release one of the hands, which would help avoiding weird looking issues
The "ValveBiped.weapon_bone" is the name of the weapon bone the gun uses.
Some people make entirely new bone sets, like the one I am porting. It uses "zhuti" instead.
If your mod uses different bone names, you should change the name of the bone in the ikrule.

With the viewmodel done, we can look after the worldmodel.

Worldmodels are luckily simpler to make, but you might need to redo it from scratch.
The location of weapon grip in relation to the weapon bone is not the same across weapons.

For example, here's the AK47 on the Military Sniper animations, which is heavily offset.


Weapons using the same player animation can have its worldmodel ported without model edits.
If the weapons you want to port between are in the same box below, you just need to edit the qc.
If they are not in the same box, you'll need to make a new worldmodel yourself.

Quick side point:
Before TLS we used to have only two rigged bones: Gun and Magazine.
Since TLS we got: Gun, Mag, Bullets inside the Mag, Bolt, Charger (handle).
If you're porting an old mod, you might want to redo the worldmodel to use these bones.
They just make the gun in other people's hands look more lively. But you do not need them.

For melee weapons its the same concept.
We got One-Handed (Frying Pan), Wide-Two-Handed (Axe), Narrow-Two-Handed (Bat)
And guitar has its own animation because it has to be a special snowflake.

If you're porting between the boxes below, you should at least check if the spot you hold on to is in generally the same location as the vanilla melee weapon.


Now. With this explanation out of the way, let's start.

If you're lucky enough to not need to edit the model itself, you can just copy the QC data.
We already did it for the viewmodel, So we'll just do that again for this qc.

Copy the $bodygroup's smd, $CDmaterials, and $Attachments from your mod's qc into vanilla.
If vanilla has a $lod and $collisionmesh, delete them.


We could get a new collisionmodel, but that would require blender because we don't know if the modder made a collisionmodel for their mod so we just won't care.

In the screenshot above, the "mod to port" on the left has three definebones.
Two of which are only for the attachment.
If you have bones for attachments, you probably should copy over their definebones.


However, you know what this also means?
There's no bone for the magazine. So that thing never moves during reload.

Anyways. You just needed to copy over some data, that's all.
Now we can compile the models.

Here's where we'll make a new worldmodel from scratch.

Import the vanilla worldmodel and the custom worldmodel, both as separate armatures.
You can import both smd's at once.

If you for have multiple smd's for the custom gun, import all smd files with "Append to target".
Then import the vanilla gun while "Make New Armature" is active.

You'll get at least two meshes with two separate armatures.


Delete the armature of the custom gun.
Move the custom gun until the grip and trigger are in about the same spot as the vanilla gun.
Sometimes you may need to rotate the front down, so that the players hand doesn't hold thin air.


Once the positioning is okay, apply all transforms of the custom gun mesh.
Select the custom gun mesh, click Ctrl+A and pick "All Transforms".
If the hotkey isn't working: Object - Apply - All Transforms


All of the transitional values in "Object" should be like this now.


Since you're porting a gun, most of the rigging is already there so you could skip rigging.
Unless the maker of the mod added custom bones, or didn't add any moving parts.

If you look at the vertex groups of the custom gun, you'll see all bones it has.
Even if they aren't rigged because they're for attachments.


You need at least "ValveBiped.weapon_bone".
Having "ValveBiped.weapon_bone_Clip" would be nice, so the magazine moves while reloading.
If you have them, you could skip rigging, but you won't have moving bolts and such.

This mod has literally no moving parts so i'll rig it.
If you also want to rig it manually, delete all groups at once.
If you do not want to rig it skip past this image and continue.


We need to reparent the mesh. No matter if we rig it or not.
Select the custom gun mesh first , hold CTRL and select the armature.
Move your cursor into 3D view and use Ctrl+P.
Pick "With Empty Groups"


Now you'll need to head over to the "Modifier" tab, which has the wrench icon.
You'll see two armature modifiers. One of them has no armature listed. Delete that one.


If you do not want to rig it manually, skip to step 10.14.

But first, a small explanation of how the rigging of the "new" moving parts work:
The animation of the gun was set up so that the bone of the bolt just moves a given amount.
By rigging it only 50% to one bone, it will move less than the animation would make it move.

As an example, the slides of the top pistol is rigged 100% to "ValveBiped.weapon_bolt"
Which means the slide moves exactly as far as the anim would tell it to.
Meanwhile the bottom one is rigged 80% to the bolt bone, and 20% to the weapon bone.
Which now means, the slide moves backwards less.


This is a genius design, because you can decide yourself how far the bolts should move.
You can also copy the original values if you aren't sure.

Here's what these bone do, by the way:

Bone

Effect

Bolt

Moves backwards when firing. Starts in open position at beginning of reload sequence.

Charger

Doesn't move when firing.
Starts in open position at beginning of reload sequence.
Only required when the bolt does not have a handle attached.

Clip

Just the magazine. Moves when reloading

Clip_Bullets

Bullets inside the magazine. Are hidden inside the magazine mesh when reload starts, and get moved to be visible when the new mag is inserted.

Manual rigging time!

We will start with the little moving bits.
To make it easier for us, we will first copy the weights of the original gun.
This will be a "baseline" so to speak. We can later increase or decrease the weights if we need to.

Move the vanilla gun object out of the way.
Select the vanilla gun first, then select the custom gun.
Press Tabulator, or click on "edit mode" with the mouse.
Important is just that this thing in the box displays the name of your custom gun mesh.


You could also merge the vanilla mesh to the custom gun mesh if you want, and then later delete all the mesh pieces of the vanilla gun inside the custom gun object. Which way you do it does literally not matter. You just need to have the custom weapon mesh active for rigging.

Pick "Vertex Select mode"


Press N in 3D view to get this menu on the right.
Pick the "Item" tab, and then select any vertex of the original weapon's bolt.
The part in the green box now tells you what this specific vertex is rigged to, and how strongly.


ValveBiped.weapon_bone has weights of 0.69
ValveBiped.weapon_bolt has weights of 0.31

For now, we'll copy the original weights. We can still adjust later if you want to.

Hover your mouse over one of the numbers in "Vertex Weights" and press Ctrl+C to copy it.
Hover your mouse over the "Weight" under "Vertex Groups" and press Ctrl+V.
No need to click and highlight. Literally just hover and copy/paste.


Select all of your custom weapon's bolt and rig it by pressing "Assign".
You can easily select all connected mesh by hovering over it in the viewport and pressing L.
Make sure you have the correct bone selected!


Now you rigged the bolt the same weights to the weapon bone.
Do the same step with the remaining weights for the bolt bone.

Tip for quicker rigging:
You rigged the bolt to one of those bones with whatever weight it had.
These weights always add up to 1.0. Which means if you rig the bolt with a weight of 0.69 to one bone, the only remaining weight it can have for the other bone is 0.31. Because 1.0 - 0.69 = 0.31
So instead of checking which weight the original bolt had, just do math. Change the weight value and rig the bolt to the other bone without ever dropping the selection.

After you rigged the bolt mesh to the bolt and weapon bones, rig the charger (if you have a separate charger), followed by the magazine and the bullets residing within it.

Once the moving bits have been rigged, we gotta rig the rest to the weapon bone.
This can easily be done by going up the vertex group list, selecting every single thing.
Then inverting the selection with Ctrl+i and rig everything remaining fully to the weapon bone.


In the GIF, I clicked on the bottom bone in the list. Then I clicked the "Select" button. Next, I moved my mouse to the box above and used the "Arrow up" key to select the next bone in the list. I did this instead of clicking on each bone because it's a little faster.

It's now time to export the model.
Open the 'Scene' tab and select an output folder for the model.
You'd want to use the same folder your QC file is in.
Afterward, click the 'Export' button above.

You should first check your model in Half-Life Model Viewer (HLMV) to make sure it works.
If you made the Worldmodel from scratch, you'll need to do the attachments in HLMV anyways.

HLMV will not load your model unless it has been compiled using a different $modelname line.
Alternatively, you could use crowbars "View as Replacement" button.
But that doesn't work the way I want it to work. So I just compile proper models. Don't @ me.

I also strongly recommend that you create a dedicated folder for your custom content.
Although this may seem like an extra step, it can save you a lot of time and effort in the long run by making it easier to manage and delete custom files when needed.
Lots of people refuse to do this, but trust me. It might just save your ass.

First, follow this guide to set up that "custom content folder". Then come back here.
You also want to set up Crowbar to work with these folders.
https://psteamcommunity.yuanyoumao.com/sharedfiles/filedetails/?id=1507939076

For now we'll do the worldmodel, because I want to check how the players hold it.
I also want to set up attachments, because I didn't make attachment bones for them.

Open the Worldmodel qc file and swap the modelname to !/temp.mdl.
Keep the original as a backup.
This allows HLMV to load "Models/!/Temp.mdl".


Why !/Temp.mdl, you ask?
If you always compile over the same mdl, you will never need to delete a ton of leftover WIP models, because each test compile replaces the same files over and over again.

Drag and drop your QC onto crowbar, make it compile to the "Game's models folder", which should be your custom content folder by now.


Click the compile button and read the compile log.
You shouldn't get any errors, but if you do, read them. They mostly tell you exactly what's wrong.

So please don't ask me what "could not load file" means, okay?
Here's a spreadsheet of a bunch of errors we know, with possible fixes.[docs.google.com]
Refer to it before asking.

Now, load up HLMV by running the l4d2 authoring tools and clicking this button here:

If you want to do a ton of modding, it would eventually be quicker to launch HLMV directly.
But running hlmv.exe won't work because of course it doesn't work. Why would it?

You will need to make a shortcut of hlmv.exe and change its "target" to include a "-game" string.
Like so:

"D:\Programme\Steam\steamapps\common\Left 4 Dead 2\bin\hlmv.exe" -game "D:\Programme\Steam\steamapps\common\Left 4 Dead 2\!mods"

The second string specifically mentions that custom content folder.


You could then pin that to the taskbar if you're a gigachad who takes modding way too seriously.

First to check if the players hold the gun properly.
Load a playermodel in Survivors/. i'll just grab survivor_manager.mdl

HLMV is very useful, but also very, very stupid.
It won't load models when the "loose folder" doesn't exist.
If that happens to you, you can use Crowbar to create the folders for you.

Open the "Set up games" tab and click the "Create folders" button.
I would first rename the addon folder though.
For some reason it also creates folders for all the custom model folders of all addons.


Reboot HLMV and try again.

Anyways, once the playermodel is loaded, load a weapon and find !/temp.mdl.


You can use the sequence tab to load the appropriate idle sequence that goes with your weapon.


HMLV Controls:

Click+Drag in the middle of the screen to rotate the model around its origin.
Click+Drag closer to the edge of the screen to rotate along your view.
Shift+Drag to pan.
Ctrl+Drag to change sun angle.

We just wanna make sure it's held properly.


You can test movable parts by loading the second sequence as reload or firing.
You can use the "Frame" scrubber on the bottom to check every single frame if you want.


This is fine.


If you made a new worldmodel in blender, you'll need to make new attachment links now.
If you don't need to make new attachments, skip this step.

Load the !/temp.mdl as your main model, just like you loaded the playermodel.
You could have made bones in blender, but we did not. We're just doing it like this now.
Because being miserable builds character.

Head to the attachments tab.


We got three possible attachments.
Not having a flashlight attachment will not show a flashlight and laser.
It will still give the accuracy boost, you just can't see the laser and flashlight.

Move and rotate the attachments how you want them.

Change the Translation values from 0 0 0 to 0 0 1, to see which direction the attachment moves.
Try to center the muzzleflash attachment on the end of the barrel.
After setting the location, you'll probably also need to define the rotation.

Upon correctly positioning the attachment, copy the "QC String" into your QC file.

Make sure that you do not alter the order of the original attachment.


Set up all attachments where you want them, oriented as I described them.

Once that is done, change the QC's $modelname back to the default.


Now that the worldmodel is tested, we need to test the viewmodel.
Edit the viewmodel's $modelname to use "!/temp.mdl" and compile the viewmodel for HLMV.

If you're still in HLMV from doing the worldmodel attachments, you can just hit F5 to reload.
Now, you need to load the player's viewmodel arms "as a weapon".
They can be found in "weapons/arms".


So far so good.
If you did not blend animations, you can test your anims by swapping the first sequence for any _layer sequence you want, and check the hand movement.


If you decided to blend the sequences, pick idle as the first sequence and the second as whatever _layer you want, like this.


For the viewmodel, you basically just want to check if all anims look good. That's about it.
You can also double-check the attachments and generate new ones if you don't like the original.

If you're happy with how the models look in HLMV, you can compile the models for the addon.
Should anything be wonky, you'll first need to fix it.

Go into your qc files and make sure they use the default $modelname line now.
Remember that folder you got when you unpacked the addon?
It still has the materials, models and maybe sounds folder in there.

We will re-use that folder for our own addon, but the "models" folder has to be deleted first.
If you for kept the "decompiled" folder from your decompile in there, put it somewhere save.
Unless you specifically want to keep the source files in there. Up to you.


Recompile the models again, but this time make "Output To" use that folder you just prepared.


Addoninfo.txt is a file that defines what kind of content your mod is.
You need an addoninfo.txt for the mod to show up in the ingame addon menu.
The mod still works properly without it, but it just won't show up in the addon menu.
If you upload the mod to the workshop, this is replaced with the workshop name and description.

In case you do not have one:
Create a text file called "addoninfo.txt" in the "root" of your addon.


Paste this text and adjust:

There's also an addonimage.jpg. It would show a thumbnail in the addon menu and that's it.
This file is really weird because it was implemented by people who didn't think this through.
I honestly wouldn't bother making one.

The addonimage.jpeg only works if it is square and when installed manually in the addons folder.
People who download your mod through the workshop will see the workshop thumbnail instead. However, the workshop thumbnail only shows if it is rectangular.
Yet at the same time, rectangular workshop thumbnails look ugly as hell on the workshop.

Just look at this. Valve built it so that the ugly rectangular workshop icons with the black bars work ingame, while the super nice square one on the right won't work, even though the image space inside the game was originally square and still is.




If you still want an addonimage, load any square image into vtfedit to compress it with the default dxt5 compression, but then export it as a jpeg named addonimage.jpeg.

Open the "Materials" folder. If there is a "Vgui" folder, you got hud images that you could port.
You could also delete them or make entirely new ones if you wanted though.

If you want to make brand new HUD Icon, follow the "HUD Icon" section in this guide:
You'll first need to download the prefab for the blend save file or make it up yourself.
https://psteamcommunity.yuanyoumao.com/sharedfiles/filedetails/?id=2712310851#5060847

To port the hud icon, just rename the vtf, vmt and the $basetexture line inside the vmt.
Or maybe edit the actual images yourself just to make sure they fit. You never know.
You can open VMT with notepad++, because its a normal text file.

Here's the names you can rename to.

Sounds are another thing you could port, if your mod has sounds in it.
Except that you will need to make new sounds yourself. You cannot just rename files.

So, here's a video guide on making sound mods if you want to handle sounds.
I'm not gonna make a guide specifically on "porting sounds" from one gun to another when it is for the most part the exact same steps. The only difference is the fact that the sounds you are porting have been taken from another mod. But the steps required are still the same.

Weapon sounds for L4D2 are in Sound\Weapons\weapon_name_here\Gunfire and Gunother.
First check the "Update" folder for your sounds, then DLC3, DLC2, DLC1 and lastly left4dead2.

The last thing we need to do now is pack the addon into a vpk.

Drag and drop that addon folder onto crowbar's pack tab.
Make sure you're packing to the proper game.
Then click the "Pack" button on the bottom left.


You now got a vpk of the same name as that folder.


Put that new vpk file into Left 4 Dead 2\left4dead2\addons to test the mod ingame.


Obviously your mod may not show up if you have another model mod active for the same gun.
If you have no mods active and it still shows the vanilla weapon, you didn't pack the mod properly, which shouldn't be possible if you had actually paid attention to the guide.

Yeah, that's it.
You're done now.

Should you need help with this process, join the "Dead 4 Mods" Discord Server[discord.gg].
There's a few members, including me, who can help you out.

Please for the love of Lucifer, do not join and immediately DM me.
I've got enough people who use me like google for the simplest questions and i'm sick of it.

I have my own Discord Server[discord.gg] if you'd like to hop in and chat.
I sometimes post WIP images of what i'm doing, but it's mostly memes.

I also got Paypal[paypal.me] for don't-ations.