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.
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.
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.
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.
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.
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.
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).
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 name||Default value|
|Recoil strength||0.0||Recoil 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 name||Default value|
|Recoil pattern||Arc pattern||Sets the pattern of the recoil effect ("arc" or "circle")|
|Recoil pattern size||0.0||Sets the size of the recoil pattern (setting to zero disables recovery)|
|Recoil bias||(0, 0) vector||Sets the direction in which recoil impulses will be biased|
|Random probability||0.0||Sets the per-shot probability of a recoil impulse with a randomized direction|
|Recoil pattern arc size||15.0||Sets the arc size of the recoil pattern (only used by "arc")|
|First shot multiplier||1.0||Multiplies the strength of the recoil impulse of the first shot by this amount|
|Recoil resist||1.0||Sets the recoil resistance strength|
|Resist jump multiplier||1.0||Multiplies the resistance by this amount while the user is jumping|
|Resist injured multiplier||1.0||Multiplies the resistance by this amount while the user is injured|
|Resist crouching multiplier||1.0||Multiplies the resistance by this amount while the user is crouching|
|Resist scoped multiplier||1.0||Multiplies the resistance by this amount while the user is scoped (sniper rifle, iron sights, etc.)|
|Recoil recovery||0.0||Sets 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|