Script Structure |
Root |
Independent values Adjust (parent key) IronSight (parent key) VMDOF/depth of field (parent key) WeaponSpec (parent key) |
Independent values Options (sub-parent key) Melee (sub-parent key) LaserPointer (sub-parent key) Activities (sub-parent key) Recoil (sub-parent key) Spread (sub-parent key) Scope (sub-parent key) Burst (sub-parent key) Bullet (sub-parent key) EnergyBullet (sub-parent key) BulletEntitySpawn (sub-parent key) HandGrenade (sub-parent key) Detonator (sub-parent key) ShootPos (sub-parent key) NPC (sub-parent key) |
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.
|
|
Independent values
|
|
- 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)
|
|
- 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.
IronSight (parent key)
|
|
- Line 3 defines the viewmodel adjustment rightwards (x-axis) while aiming in game units.
- Line 4 defines the viewmodel adjustment upwards (z-axis) while aiming in game units.
- Line 5 defines the viewmodel adjustment forwards (y-axis) while aiming in game units.
Note: These values work very similar to $origin. - Line 6 defines the player FOV adjustment for this weapon while aiming.
- Line 7 defines the viewmodel's pitch adjustment while aiming. Defined by degree values - similar to flight dynamics.
- Line 8 defines the viewmodel's yaw adjustment while aiming. Defined by degree values - similar to flight dynamics.
- Line 9 defines the viewmodel's roll adjustment while aiming. Defined by degree values - similar to flight dynamics.
- Line 10 defines the weapon's bullet spread / firing cone angle multiplier while aiming.
VMDOF/depth of field (parent key)
|
|
- Line 3 is a sub-parent keyvalue block that defines the default depth of field settings.
- Line 5 defines the start of the depth of field shader while the weapon isn't aimed.
- Line 6 defines the end of the depth of field shader while the weapon isn't aimed.
- Line 8 is a sub-parent keyvalue block that defines the depth of field adjustments while aiming with iron sights.
- Line 10 defines the start of the depth of field shader while aiming with iron sights.
- Line 11 defines the end of the depth of field shader while aiming with iron sights.
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.
Independent values (top)
|
|
- Line 1 defines the weapon type of the weapon.
0: Semi-auto/single shot.
1: Automatic.
2: Shotgun.
3: Automatic shotgun.
4: Melee.
5: Handheld explosive (e.g. grenades). - 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.
Options (sub-parent key) (top)
|
|
- Line 3 defines how loud NPCs percieve the weapon's shots. The higher the value, the farther out enemy NPCs will hear it and likely investigate.
- Line 4 is a boolean that decides if the weapon will use its reload sound from the SoundData section of the weapon script.
- Line 5 is a boolean that decides if the weapon will trigger a special sound event when the last round is fired.
- Line 6 is a boolean that can add support for a weapon's "dry firing" animation. The default activity name is ACT_VM_DRYFIRE.
- Line 7 sets whether or not the weapon will zoom out of its scope after being fired.
- Line 8 sets whether or not the weapon will move out of iron sight aim after being fired.
- Line 9 is a float multiplier to define how far the cone of the crosshair moves while moving.
- Line 10 is a float value to define the minimum size of the crosshair.
- Line 11 is a float value to define the timescale of the weapon model's animations.
- Line 12 is a boolean to define if the weapon uses a "en bloc" clip. This means the weapon will not reload until the clip is dry because it acts as a whole unit.
- Line 13 sets what hand model/skin to use if the weapon is an Insurgency or [*http://en.wikipedia.org/wiki/Day_of_Defeat:_Source Day of Defeat: Source style model. The possible values are defined within the weapon's MDL file.
- Line 14 sets the time before the weapon is actually fired.
- Line 15 defines whether or not the model uses special animation events used with gatling-gun type weapons, to delay firing and layer animations.
Melee (sub-parent key) (top)
|
|
- Line 3 is a sub-parent keyvalue block that defines the settings for a melee weapon's primary attack.
- Line 5 defines the range of the melee attack in game units.
- 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.
- Line 9 defines the damage type of the melee attack. See damage types.
- Line 11 is a sub-parent keyvalue block that defines the settings for a weapon's secondary melee attack.
All values (5-9) can be used within this block. - Line 19 sets the melee attack's force. This is defined as a float value.
- Line 20 defines the impact effect of the weapon's melee attack.
0: Default.
1: No decal.
2: No decal, no sound.
3: No effect. - Line 21 sets the melee attack's impact decal. The ID names are defined in scripts/decals_subrect.txt.
LaserPointer (sub-parent key) (top)
|
|
- Line 3 defines the weapon's accuracy multiplier while the laser pointer is active. This value is based on float percentages, so a value of 1 would give a 100% bonus whie 0.5 would give a 50% bonus.
- Line 4 is a boolean that defines if the weapon's laser pointer can be activated through +use.
- Line 5 is a boolean that defines if the weapon's laser pointer turns on while in iron sight aim.
- Line 6 is a boolean that defines if the laser pointer is turned off when the gun reloads.
- Line 7 defines the laser pointer's sprite material. This is a string value.
- Line 8 is a boolean that defines if the pointer draws a trail while being moved.
- Line 9 is a boolean that defines if a sound is played when the laser pointer is activated or deactivated.
- Line 10 defines the distance where the sprite is at its minimum size.
- Line 11 defines the distance where the sprite is at its maximum size.
- Line 12 is a boolean to define if the laser pointer sprite will have a fixed size, and will not change size dynamically based on where it's being pointed.
- Line 13 is a float value that defines the laser pointer sprite's size.
Activities (sub-parent key) (top)
|
|
- Lines 3-12 define what activity plays during what event according to its name.
Recoil (sub-parent key) (top)
|
|
"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.
Spread (sub-parent key) (top)
|
|
- 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.
Scope (sub-parent key) (top)
|
|
- Line 3 sets the overlay used by the weapon's 2D scope:
0: No overlay.
1: SVD.
2: SVD Nightvision.
3: Crossbow.
4: CS:S Scope.
5-9: SMOD will look for customscope1-5.vmt in SMOD's materials/vgui folder.
- 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.
Burst (sub-parent key) (top)
|
|
- Line 3 sets how many shots will be fired with each burst.
- Line 4 defines the delay (in seconds) between bursts.
- Line 5 defines an accuracy multiplier used while burst mode is used. For example, a value of 0.6 would yield a 60% bonus.
- Line 6 defines the recoil multiplier used while burst mode is used. For example, a value of 2.0 would increase recoil by 100% for each shot.
Bullet (sub-parent key) (top)
|
|
- 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.
EnergyBullet (sub-parent key) (top)
|
|
- 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.
BulletEntitySpawn (sub-parent key) (top)
Please take note that some values from the Bullet block can effect these values.
|
|
- Line 3 sets the class of the entity that spawns as a bullet.
- Line 4 sets the model of the entity that spawns as a bullet.
- Line 5 sets the type of Custom Explosive entity to use if the class is set as "Custom_Explosive".
- Line 6 sets the height (in game units) that the entity spawns from the player along the z-axis.
- Line 7 sets the height (in game units) that the entity spawns from an NPC along the z-axis.
- Line 8 defines the force at which the entity flies.
- Line 9 sets the mass of the entity. Note that source's weight unit is kilograms.
- Line 10 sets the angular velocity of the entity.
- Line 11 defines how long (in seconds) before the entity disappears.
HandGrenade (sub-parent key) (top)
|
|
- Line 3 sets the frame of the grenade throw the grenade spawns.
Detonator (sub-parent key) (top)
|
|
- Line 3 specifies which custom explosive type is used by detonated by the detonator.
- Line 4 sets the radius at which the detonator is able to trigger the detonation of any explosive entity.
ShootPos (sub-parent key) (top)
|
|
- Line 3 defines the upwards (aiming up) pitch value for the bullet model spawn.
- Line 4 defines the downwards (aiming down) pitch value for the bullet model spawn.
- 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.
NPC (sub-parent key) (top)
|
|
- 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. - Line 9 defines the range of the weapon for NPCs in game units.
- Line 10 is a boolean to check whether or not the weapon will have muzzle flashes for NPCs.
- Line 11 is a boolean to check whether or not NPCs can use this weapon's grenade launcher if one is present.
Customization |