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 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/

"WeaponData"

This section configures the main aspects of the weapon.

"printname"

The name that the game prints for the weapon.

"viewmodel"

The model that the player sees when holding the weapon.

"playermodel"

The model that is seen when looking at another player or NPC holding the weapon. This model is also used when the weapon is on the ground ready to be picked up.

"animprefix"

Todo:  Find out and insert what this does; anim when selected?

"bucket"

Which bucket to place the weapon in for the HL2 style weapon selection.

"bucket_position"

Determines where in the bucket the weapon is placed. Lower numbers put the weapon higher, higher numbers put the weapon lower.

"clip"

The amount of ammunition in each clip or magasine.

"defaultclip"

The total amount of ammunition this weapon has when placed

"clip2_size"

The ammount of ammunition that can be stored in the secondary clip. If there is no secondary ammunition put "-1"

"default_clip2"

The total ammount of secondary ammunition this weapon has when placed. If there is no secondary ammunition put "-1"

"primary_ammo"

Identifier for the type of ammo this weapon uses.

"secondary_ammo"

Identifier for the secondary type of ammo this weapon uses. If it does not use any seconary ammo, put "None".

"weight"

The weight of the weapon, used for calculating physics when the weapon is on the ground.

"itemflags"

Todo: Find out and insert what this does and how to use it

"damage"

The ammount of damage this weapon does, per shot.

Essential commands

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 (about line #3560). Add yours next to them, for example:

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

Create C++ files

Todo:  explain why this is necessary

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).