SMOD includes a framework for creating up to 30 custom weapons, thanks to flexible scripts that can define everything from firing mode(s) and recoil to laser pointers and melee attacks. Default weapon script values are not explained here, so for more info on typical Half-Life2 weapon scripts and their values, see the VDC weapon script article. All the other values explained below aren't necessarily exclusive to just weapon_custom* scripts and can be applied to hard-coded weapons as well (with some exceptions like ShootPos).

About the organization of this article:

This article includes a full weapon_custom*.txt script template below, containing all the known SMOD weapon keyvalues. After that, there are sections of information on all of the values. They are placed in a descending order according to their placement within the script template.

An independent value is a simple keyvalue that works on its own or within a parent block. A parent keyvalue is the start of a keyvalue block and within this block you'll find more independent values specific to this block. There are also sub-parent keyvalues, which are lesser parent blocks within another block, which contain their own independent values. Most listed values are independent and each parent keyvalue is sectioned with a heading. The heading provides a guide as to the level of parent keyvalue block. More information on Source keyvalues.

The majority of terms should have links provided, but check the glossary for any terms you don't understand. Also note that keyvalues that rely on number values usually default to 0. If you want a droppable weapon, for instance, you don't have to set NoDrop to 0.

Root

This is a base to use for custom weapon scripts and contains all the values discussed on this page and the VDC weapon script page. This should save some trouble referring back to this page, not to mention some typing.

Line 1 sets if the weapon has a Counter-Strike style viewmodel. A value of 1 adds support for its muzzle flashes and shell casings.

Line 2 sets if the weapon has a Counter-Strike style worldmodel. A value of 1 will add support for its animations in some cases.

Line 3 this defines the muzzle type if the viewmodel is a Counter-Strike style model. The options are: MZRIFLE, MZSMG, CSRIFLE, CSSMG.

Line 4 defines the size of the muzzle flash sprite as a float value if it is a Counter-Strike style model.

Line 5 forces the muzzle flash to fire from the "muzzle" attachment. This is intended for CS:S models, as most HL2 weapons use the "1" attachment.

Line 6 offsets the muzzle along the x axis if it is a Counter-Strike style model.

Line 7 is the viewmodel lag/drift multiplier. Note that the recovery of the lag is slowed down with lower values.

Line 8 defines a speed multiplier for this weapon. In the example above, the weapon would slow the player to 60% of their normal speed while the weapon is held.

Line 9 is a boolean that defines if the weapon follows RO free-aim rules when smod_ro_aimmode is set to 1.

Line 10 is a boolean that defines if the weapon can be dropped.

Adjust (parent key)

1
2
3
4
5
6
7

"Adjust"
{
"Forward" "4"
"Up" "1"
"Right" "-20"
"Fov" "10"
}

Line 3 defines the viewmodel's forward (y-axis) adjustment in game units.

Line 4 defines the viewmodel upward (z-axis) adjustment in game units.

Line 5 defines the viewmodel's horizontal adjustment (x-axis) in game units.

Line 6 defines the player's FOV adjustment while aiming with this weapon.
This block works akin to the $origin command for QC files. Also note that while pitch, yaw, and roll can be set (as they are in IronSight below), they 're unlikely to work here without problems.

WeaponSpec (parent key)

WeaponSpec is the parent key block that defines the majority of SMOD's custom weapon value settings. There are many sub-parent keyvalues within this block. It is organized below from top to bottom by independent keyvalues, and sub-parent keyvalues.

Line 2 Sets the firing rate of the weapon. The formula is $1 / (RPM / 60)$ where $RPM$ is rounds/minute.
For example, if you wanted a firing rate of 800 rounds per minute:$1 / (800 / 60)$ ► $1 / (13.333333333333333333333333333333)$ ► $0.075$ would be your value.

Line 3 is a boolean that sets whether or not the weapon can fire underwater.

Line 4 is a boolean to define if the weapon is "akimbo" (dual wielded), for properly calculating separate tracelines and muzzle flashes.

Line 5 defines if the weapon has an attached grenade launcher to be used with the secondary attack.

Line 6 sets the firing mode(s) of the weapon. Note that Firemode has priority over WeaponType; a six-shooter with its type set to 0 but mode set to 4 will fire like an automatic. When WeaponType is overridden like this, it will decide the default firing mode; if the six shooter's mode was set to 5 instead, it would start in semi-auto but could switch to fully automatic.
This works like a flag - list below:
1: Semi-automatic/single shot only.
2: Burst only.
3: Semi-auto/burst.
4: Automatic only.
5: Semi-auto/auto.
6: Burst/auto.
7: Semi-auto/burst/auto.

Line 6 defines what frame of the attack animation the hitscan will deploy.

Line 7 is a float speed multiplier for the next attack. A higher value will result in a longer wait time/slower speed.

Line 8 sets how much damage the melee attack inflicts. Keep in mind that melee attacks ignore armor, unlike bullets which tend to do less damage with body shots, at the same time dealing bonus damage with head shots.

"Punch" recoil is the effect that weapons like Half-Life2 use to rock the player's view ("viewpunch") as the weapon continues firing, and after firing has ceased, the player's view will return to roughly where it was before. "Snap" recoil on the other hand, acts similarly but will not return once the player's stopped firing, making control a bit tougher and more important than with the punch type.

Line 3 defines the minimum and maximum pitch values for punch recoil. The view can be punched to anywhere within these two values, especially as fire continues.

Line 4 defines the minimum and maximum yaw that can be offset with punch recoil.

Line 5 is a boolean that defines if snap recoil has priority over punch recoil.

Line 6 defines the minimum and maximum pitch values for snap recoil. These override the PunchPitch values if EnableSnap is set to 1.

Line 7 defines the viewpunch yaw values for snap recoil. These override the PunchYaw values if EnableSnap is set to 1.

Line 8 sets the recoil multiplier while the player is crouched. A multiplier of 0.5 for instance would cut the recoil in half whenever the player is crouching.

Line 9 sets the amplitude multiplier for recoil. This controls how poor recoil gets as fire continues.

Line 10 defines the punch recoil limit.

Note that if EnableSnap is set to 1 but SnapPitch and SnapYaw are undefined, single shots will act with punch recoil, while burst or automatic fire will act as if snap recoil was enabled.

Line 3 defines the default spread of the weapon's firing cone, based on a 1 degree firing cone (3.0 = 3 degrees).

Line 4 defines the maximum spread that the weapon's firing cone can reach, based on a 1 degree firing cone (5.0 = 5 degrees).

Line 5 defines a multiplier for the weapon's spread while the player is on the move, based on Default's value. In this example, the default of 3.0 is multiplied by 1.0, leaving the player with no movement penalty.

Line 6 defines the spread of the weapon's spread while sprinting.

Line 7 defines a multiplier for the weapon's spread while the player is crouching, based on Default's value. In this example, 0.8 gives the player a 20% spread reduction while they have their head down.

Line 8 defines a multiplier for the weapon's spread during sustained fire, based on Default's value.

Line 4 defines how many levels of magnification the scope has. If, for example, the scope had a base of 8X and 3 levels, it would go from 2X to 4X and 8X.

Line 5 sets the base magnification of the scope's zoom.

Line 6 is a boolean that defines if the crosshair is turned off while the scope is used.

Line 7 sets a bonus accuracy multiplier used during scope use. Here, the value of 0.6 would give a 60% bonus.

Line 8 Sets the firing rate of the weapon while aiming with a scope. The formula is $1 / (RPM / 60)$ where $RPM$ is rounds/minute.
For example, if you wanted a firing rate of 800 rounds per minute:$1 / (800 / 60)$ ► $1 / (13.333333333333333333333333333333)$ ► $0.075$ would be your value.

Line 9 is a boolean that defines if the viewmodel of the weapon is drawn while zoomed in or not.

Line 10 defines the drift value of the scope. This is how much the player's view bobs around as they're zoomed in.

Line 11 is a boolean that defines if the weapon's scope can be activated through +use.

Line 12 is a boolean that defines if the weapon's scope can be activated through ironsight aiming.

Line 3 sets the hitscan ammunition type of the bullet. This also sets the bullet model that is used in bullet time.

Line 4 sets the damage value the bullet will inflict on impact.

Line 5 sets how many bullets/projectiles will be cycled per shot. As an example, a shotgun might fire 7 or more pellets each time it's fired.

Line 6 defines how many shots it takes before a tracer appears. A value of 3 would mean every 1 in 3 rounds will produce a tracer.

Line 7 sets the force of the bullet that it has upon impact.

Line 8 sets if and how much the bullet will penetrate.

Line 9 defines how far in game units the shot will travel before being removed. Line 10 defines how far in game units the shot will travel before its damage attenuates. This is used to model loss of kinetic energy after the bullet has traveled a good distance.

Line 3 sets the damage type of the projectile. This is based on trigger hurt's damage type values.

Line 4 sets how many times the projectile will bounce of objects and brushes.

Line 5 sets the size of the projectile.

Line 6 sets the radius of the light that surrounds the projectile.

Line 7 sets the light color of the projectile trail. This is defined in RBG format.

Line 8 sets the speed at which the projectile travels. This is defined by default Source velocity measurements, which is Units/Second.
Note: Source can usually handle projectiles with a speed of up to 700 mph (16202.66 units/s), but at speeds of 3000+ units/s (appx. 16/17mph) the projectiles seem to fall way off the intended trajectory.

Line 9 defines the sprite material that the projectile will have.

Line 10 defines the gravity value override of the projectile, which is measured in units/second2.
For example, Half-Life2 and it's Episodes have a default value of 600. The square root of 600 is 24.49, thus objects fall at a rate of approximately 24.5 units per second.

Line 11 sets the size of the trail that will follow the projectile.

Line 12 sets how long the trail will be present.

Line 13 sets how long the projectile will last. This is based on seconds.

Line 5 defines the values for bullet model spawn while aiming down ironsights.
all keyvalues have 3 values. The 1st value is forward positioning. The 2nd value is rightward positioning. And the 3rd value is upward position.

Line 3 specifies an animation set that NPCs will use with the weapon. Animation sets include pistol, smg1, shotgun, rpg, and ar2.

Line 4 is a boolean to enable or disable NPCs from firing this weapon upon death if ragdoll_holdweapon is enabled.

Line 5 is a boolean to define if the NPC will use the weapon's laser pointer if it has one.

Line 6 defines the maximum shot count for NPC bursts.

Line 7 defines the minimum shot count for NPC bursts.

Line 8 Sets the firing rate of the weapon for NPCs. The formula is $1 / (RPM / 60)$ where $RPM$ is rounds/minute.
For example, if you wanted a firing rate of 800 rounds per minute:$1 / (800 / 60)$ ► $1 / (13.333333333333333333333333333333)$ ► $0.075$ would be your value.