Adding weapons

From Valve Developer Community
Revision as of 09:43, 4 February 2010 by MLSTRM (talk | contribs) (fixed hammer implementation)

Jump to: navigation, search

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

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-handed weapons
     AllowFlipping 1
     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/

This section configures the main aspects of the weapon.
The name that the game prints for the weapon.
The model that the player sees when holding the weapon.
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.
This seems to be extremely outdated. As of the Orange Box source code, the way this is used, is it looks up animation activities based on this "prefix". However, the activities that are looked up only seem to be attack activities. It changes it based on whether or not the player is crouching:

If they are: "crouch_aim_" (animprefix) otherwise: "ref_aim_" (animprefix)

However, if it fails to find an animation with the animprefix, it defaults to the activity name bound to the action. Thus, rendering the use of animprefix all but obsolete, considering that the crouch, and ref prefixes of animations are not currently in use.

Which bucket to place the weapon in for the HL2 style weapon selection.
Determines where in the bucket the weapon is placed. Lower numbers put the weapon higher, higher numbers put the weapon lower.
The amount of ammunition in each clip or magazine.
The total amount of ammunition this weapon has when placed
The ammount of ammunition that can be stored in the secondary clip. If there is no secondary ammunition put "-1"
The total ammount of secondary ammunition this weapon has when placed. If there is no secondary ammunition put "-1"
Identifier for the type of ammo this weapon uses.
Identifier for the secondary type of ammo this weapon uses. If it does not use any seconary ammo, put "None".
The weight of the weapon, used for calculating physics when the weapon is on the ground.
To do: Find out and insert what this does and how to use it
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:

	channel CHAN_WEAPON
	volume 0.8
	soundlevel SNDLVL_GUNFIRE
	pitch 85,95

		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

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

Note however that there is no base class for weapon so copy an existing one and modify the parameters

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

It is necessary to create some c++ files because without them the source engine does not know how to handle the weapon. The c++ code determines how fast the player can fire, how accurate the weapon is and many other aspects of the weapon. Without the c++ code the weapons would cease to function.

Navigate to File -> New -> File, click Visual C++ on the left and select .cpp. Pick the first template from [1](Broken Link). 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:


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

Note:To use your new weapon through the console (~), enable cheats in the game by typing "sv_cheats 1" and then use the command "give weapon_m249" to grab it (replace weapon_m249 with your weapon's name)