Page tree
Skip to end of metadata
Go to start of metadata


Recoil is the "kick" of a weapon when it is fired, causing the user's aim to drift off the target, thus limiting accuracy and forcing the user to compensate. This differs from spread, which is a random error that changes the intended trajectory of each fired projectile, while the weapon remains aimed at the same spot. By contrast, recoil changes the orientation of the weapon itself, so even a weapon with no spread will no longer be able to hit the same spot.

Recoil mechanics

Recoil strength

Each fired projectile creates an impulse that will throw the user's aim off-target. The strength of this impulse is determined by the recoil strength parameter. Each projectile will add a 2D (pitch and yaw) impulse to the weapon, rotating it away from the original orientation. The impulses from subsequent projectiles are added to the total recoil angular velocity, so sustained fire will continuously increase the recoil effect.

Recoil pattern

The recoil pattern determines the directions in which the recoil impulses described above take effect. Each time a projectile is fired, an impulse vector is calculated based on the recoil pattern. Most impulses will be directed toward a bias direction (typically in the direction upward from the barrel), and to simulate the pseudo-randomness of the recoil effect, some projectiles will create an impulse in a random direction within the set pattern. The per-shot probability of this random impulse can be adjusted using the random probability parameter.

Arc pattern

The arc pattern is the most conventional type of recoil pattern, which assumes a weapon that primarily "kicks upward". The green arrow shows the bias, which is the direction where normal recoil impulses will push the user's aim. The red arrows show possible directions for random recoil impulses, where the angles of all such impulses w.r.t the vertical direction are constrained to this arc. The pattern arc size parameter can widen the arc, allowing for greater horizontal deviations with each shot.

Circle pattern

The circle pattern behaves similarly to the arc pattern, except that it allows random impulses in the full 360° range (which means it does not need the arc size parameter). This is primarily useful for more wild recoil behavior, e.g a handheld machine gun during sustained fire.

Recoil resistance

In order to prevent the recoil impulses from making the weapon spiral out of control, weapons have recoil resistance, which is a constant force that acts opposite the recoil force while it is nonzero. After each recoil impulse is applied, this force will attempt to bring the recoil movement to a halt, thus it can be balanced with recoil strength to create the appropriate recoil behavior. For example, setting a high recoil strength and low resistance will allow a single shot to widely displace the user's aim, and the recoil effect will take longer to "decay".

The user's current state also affects their resistance. This is achieved using the resistance multipliers, e.g crouching can be expected to increase the user's ability to resist the recoil impulses, while jumping has the opposite effect.

NOTE: the recoil resistance parameter must be nonzero, otherwise the recoil impulse will never decay and will endlessly throw off the user's aim.

Recoil recovery

Recovery is an optional mechanic that allows for automatically correcting the user's aim. After the resistance has reduced the recoil angular velocity to zero, the recovery will take over and move the user's aim back toward the center of their recoil pattern. The recoil recovery parameter sets the speed of this effect, so an appropriate value must be found to make the transition look natural. The recovery also depends on the recoil pattern size, which sets a limit on how far the user's aim can deviate before it can no longer be returned to the original position. If the recoil impulses move the user's aim beyond the pattern radius, then the pattern itself will "drift" with the recoil, and the recovery will only restore the aim to the new center position of the pattern. However, there is a flag; Recoil Aimpoint Static that will disable the aim drifting beyond the recoil pattern's size and instead limit the recoil size to just the recoil pattern size, where the player's aim will stay until fire is stopped (if recovery is enabled).


Recoil parameters

Weapon recoil can be set for infantry weapons and even vehicles. To set up recoil for a weapon, parameters need to be edited in both Ammo and Weapons definitions. For testing, they can also be edited while in-game using the "EDIT_RECOIL" console command, which will adjust the settings for the currently selected weapon.

Ammo definition parameters

Parameter nameDefault value

Short description

Recoil strength0.0Recoil strength determines the amount of recoil energy created by each projectile fired from the weapon. Higher values will make the recoil effect much faster and stronger (i.e "the aim will drift off-target more rapidly")

Weapon definition parameters

Parameter nameDefault value

Short description

Recoil patternArc patternSets the pattern of the recoil effect ("arc" or "circle")
Recoil pattern size0.0Sets the size of the recoil pattern (setting to zero disables recovery)
Recoil bias(0, 0) vectorSets the direction in which recoil impulses will be biased
Random probability0.0Sets the per-shot probability of a recoil impulse with a randomized direction
Recoil pattern arc size15.0Sets the arc size of the recoil pattern (only used by "arc")
First shot multiplier1.0Multiplies the strength of the recoil impulse of the first shot by this amount
Recoil resist1.0Sets the recoil resistance strength
Resist jump multiplier1.0Multiplies the resistance by this amount while the user is jumping
Resist injured multiplier1.0Multiplies the resistance by this amount while the user is injured
Resist crouching multiplier1.0Multiplies the resistance by this amount while the user is crouching
Resist scoped multiplier1.0Multiplies the resistance by this amount while the user is scoped (sniper rifle, iron sights, etc.)
Recoil recovery0.0Sets the speed of recovery (setting to zero disables recovery)
Recoil Aimpoint Static false Sets if the recoil recovery point won't shift with extended bursts 
  • No labels