Adding weapons

This guide assumes that you started out with HL2:MP and VC++ Express Edition (available for free at microsoft.com).

Weapon models

Weapons consist of two models, each with their own prefix. A model named v_yourweaponnamehere.mdl is a viewmodel, the model seen from the first person perspective. It normally consists of not only the weapon model but also the player's hands.

The other is the w_yourweaponnamehere.mdl — this is known as the worldmodel. These models are used for weapons laying on the ground and also for weapons that you can see in other characters' or players' hands.

For adding weapons to Source mods, you can make your own models or, for example, use the Counter-Strike:Source ones.

Once you have the models, they go into the following directory: /name_of_your_mod/models/weapons

Weapon model textures

The textures/skins for the weapons also need to be placed in the correct directory: /name_of_your_mod/materials/models/weapons

Weapon script file: weapon_yourweaponname.txt

Each weapon has its own script file, editable in any .txt program. The weapon script file has many different purposes, which include model file names, bucket info, clip size, ammo type, weight, sounds, icons and crosshairs. In adding weapons, for pistols you can start with the default pistol.txt, and for sub-machineguns and assault rifle you can use smg1.txt as a template.

For this tutorial, we are going to add an wikipedia:Avtomat Kalashnikov 1947, also known as AK 47, in the game. The script file for it will be called weapon_ak47.txt.

 WeaponData {
     // Weapon data is loaded by both the Game and Client DLLs.
     "printname" "#HL2_ak47"
     "viewmodel" "models/weapons/v_rif_ak47.mdl" // "models/weapons/v_ryourweapons.mdl"
     "playermodel" "models/weapons/w_rif_ak47.mdl"
     "anim_prefix" "ar2"
     "bucket" "2"
     "bucket_position" "1"
     "clip_size" "30"
     "default_clip" "90"
     "clip2_size" "-1"
     "default_clip2" "-1"
     "primary_ammo" "AK47"
     "secondary_ammo" "None" 
     "weight" "5"
     "item_flags" "0"
     "BuiltRightHanded" "0" // These make sure you can have right-
     "AllowFlipping" "1"    // handed weapons
     "damage" "35"

     // Sounds for the weapon. There is a max of 16 sounds per category (i.e. max 16 "single_shot" sounds)
     SoundData {
         "special1" "Weapon_CombineGuard.Special1"
         "empty" "Weapon_IRifle.Empty" 
         // "double_shot" "Weapon_IRifle.Single"
         "reload" "Weapon_AR2.Reload"
         "single_shot" "Weapon_ak47.Single"
        
         // NPC SECTION
         "single_shot_npc" "Weapon_AR2.NPC_Single"
         "reload_npc" "Weapon_AR2.NPC_Reload"
         "double_shot_npc" "Weapon_AR2.NPC_Double"
     }
    
     // Weapon Sprite data is loaded by the Client DLL.
     TextureData {
         "weapon" {
             "font" "WeaponIcons"
             "character" "l"
         }

         "weapon_s" {    
             "font" "WeaponIconsSelected"
             "character" "l"
         }

         "ammo" {
             "font" "WeaponIcons"
             "character" "u"
         }
        
         "ammo2" {
             "font" "WeaponIcons"
             "character" "z"
         }

         "crosshair" {
             "font" "Crosshairs"
             "character" "Q"
         }

         "autoaim" {
             "file" "sprites/crosshairs"
             "x" "0"
             "y" "48"
             "width" "24"
             "height" "24"
         }
     }
 }

Place the file in the following directory: /name_of_your_mod/scripts/

Essential commands

"printname"

Todo: explain this

"primary_ammo"

Identifier for the type of ammo this weapon uses.

When creating your own weapon, replace v_ak47.mdl and w_ak47.mdl with your model names.

"special1" "Weapon_CombineGuard.Special1" 
"empty" "Weapon_IRifle.Empty" 
//"double_shot" "Weapon_IRifle.Single" 
"reload" "Weapon_AR2.Reload"                 
"single_shot" "Weapon_ak47.Single"

Change the above entries to correspond your own weapon name if you have custom sounds.

For example, "reload" "Weapon_AR2.Reload" becomes "reload" "Weapon_AK47.Reload".

New sounds need to be defined in :\Program Files\Valve\Steam\steamapps\SourceMods\yourmodname\scripts

In this tutorial, we will just use the AR2 sounds:

 "Weapon_ak47.Single" {
     "channel" "CHAN_WEAPON"
     "volume" "0.8"
     "soundlevel" "SNDLVL_GUNFIRE"
     "pitch" "85,95"

     "rndwave" {
         "wave"    "weapons/ak47/ak47-1.wav" 
     }
 }

where weapons/ak47/ak47-1.wav is a .wav file (hence "wave") and will have to be located in :\Program Files\Valve\Steam\steamapps\SourceMods\name_of_your_mod\sound\weapons\ak47.

Making your weapon show in Hammer - (Not Tested)

To get your weapon to show in Hammer you need to add the entry to your .fgd file, which should be saved in \sourcesdk\bin\.

Open it up in notepad or similar, and find the references to other (HL2) weapons. Add yours next to them, for example:

@PointClass base(Weapon) studio("models/weapons/w_ak47.mdl") = weapon_ak47 : "AK47" []

Create C++ files

Navigate to File -> New -> File, click Visual C++ on the left and select .cpp. Pick the first template from [1]. Follow the instructions there... Be careful not to copy the second template. Save as weapon_yourweapon.cpp and add it to the solution explorer.

Save the code files where ever you want, :/modname/src is recommended. When you expand under Server -> Source Files -> HL2MP -> Weapons, right-click on Weapons then Add -> Existing Item and find your .cpp file. Do the same for Client -> Sources Files -> HL2MP -> Weapons.

Open :\yourmod\src\cl_dll\hl2_hud\c_weapon__stubs_hl2.cpp. Add your weapon under #ifndef HL2MP (line 27). Just copy and paste one of the lines renaming the relevant information.

For example:

STUB_WEAPON_CLASS( weapon_ar2, WeaponAR2, C_HLMachineGun );

Add the following underneath:

STUB_WEAPON_CLASS( weapon_m249, WeaponM4A1, C_HLMachineGun );

Open :\yourmod\src\game_shared\hl2mp\hl2mp_gamerules.cpp. Find CAmmoDef *GetAmmoDef() (line 910). Copy and paste the line closest to your weapon type, for example:

def.AddAmmoType("MP5NAVY",DMG_BULLET,TRACER_LINE_AND_WHIZ,0,0,225,BULLET_IMPULSE(200,1225),0 );

Replace MP5NAVY with the ammo name defined in your weapon script file.

Setup default weapons

You can make it so that you start with the weapon by editing :\yourmod\src\dlls\hl2mp_dll\hl2mp_player.cpp. Change void CHL2MP_Player::GiveDefaultItems( void ) (line 198).