Config

Add a realistic recoil feel to your weapons without making them annoying.

// Config

Config = {}

-- Master toggles
Config.Enabled = true
Config.Debug = false                 -- /recoil_debug toggles runtime debug prints
Config.DisableWhileInMenu = true     -- pauses logic when pause menu is open

-- Input / detection
Config.ADSControl = 25               -- INPUT_AIM (Right Mouse / LT)
Config.RunControl = 21               -- INPUT_SPRINT
Config.RecoilTickMs = 0              -- 0 = every frame when armed, otherwise sleeps this many ms (0 recommended)

-- Recoil behavior (global multipliers)
-- Vertical recoil knobs:
-- 1) Config.Global.RecoilScale (master strength)
-- 2) Config.DefaultWeapon.PitchMin/PitchMax (fallback per-shot kick)
-- 3) Config.Weapons[WEAPON_*].PitchMin/PitchMax (per-weapon)
-- 4) Config.Global.MaxPitch (hard cap on accumulated recoil)
-- 5) SustainGrowPerShot / SustainMax (extra climb over sustained fire)

Config.Global = {
  -- Recoil scale depending on stance/state
  ADSMultiplier = 0.05,              -- lower recoil when aiming down sights
  HipMultiplier = 0.15,
  RecoilScale = 0.018,               -- overall recoil strength (lower = less recoil)
  MovingMultiplier = 0.20,
  SprintingMultiplier = 0.20,
  InAirMultiplier = 0.20,
  VehicleMultiplier = 0.20,
  DuckingMultiplier = 0.25,          -- IsPedDucking (only true if your server enables crouch)
  CoverMultiplier = 0.15,

  -- Sustained fire
  SustainGrowPerShot = 0.000,         -- additional recoil per shot while holding trigger
  SustainMax = 0.000,                 -- max added recoil from sustain
  SustainResetMs = 240,              -- if you stop shooting for this long, sustain decays quickly

  -- Horizontal drift shaping
  HorizontalBias = 0.00,             -- -1..+1 overall push to one side (0 = neutral)
  HorizontalRandomness = 0.025,       -- 0..1 randomness amount (lower = less side-to-side)
  ExtraHorizontalScale = 0.000,      -- extra side drift added per shot (set 0 to disable)
  PatternSeedPerWeapon = true,       -- stable drift per weapon so it feels consistent

  -- Recovery
  RecoverySpeed = 24.0,              -- higher = returns to neutral faster (per second)
  MaxPitch = 0.05,                    -- clamp recoil pitch offset (degrees)
  MaxHeading = 0.025,                  -- clamp recoil heading offset (degrees)

  -- Camera shake (optional, subtle)
  CameraShakeEnabled = true,
  CameraShakeType = 'SMALL_EXPLOSION_SHAKE',
  CameraShakeScale = 0.12,           -- global shake scale multiplier (raise/lower to taste)

  -- Aim sway (optional)
  AimSwayEnabled = false,
  AimSwayPitch = 0.008,               -- degrees (subtle)
  AimSwayHeading = 0.010,            -- degrees (subtle)
  AimSwaySpeed = 0.85,               -- speed multiplier
  AimSwayMoveBoost = 1.25,           -- sway increases while moving
}

-- Default recoil profile (used when weapon not listed below)
Config.DefaultWeapon = {
  -- Camera punch per shot (degrees)
  PitchMin = 0.006,
  PitchMax = 0.010,
  HeadingMin = -0.004,
  HeadingMax = 0.004,

  -- Extra per-shot shake (multiplies global)
  Shake = 1.0,

  -- First shot kick (semi-auto / tap fire feel)
  FirstShotMultiplier = 1.00,

  -- Automatic scaling
  AutoFireMultiplier = 0.38,
}

-- Weapon-specific profiles
Config.Weapons = {
  -- Pistols
  WEAPON_PISTOL = { PitchMin=0.008, PitchMax=0.014, HeadingMin=-0.005, HeadingMax=0.005, Shake=0.8, FirstShotMultiplier=1.12, AutoFireMultiplier=0.9 },
  WEAPON_COMBATPISTOL = { PitchMin=0.004, PitchMax=0.007, HeadingMin=-0.005, HeadingMax=0.005, Shake=0.85, FirstShotMultiplier=1.12, AutoFireMultiplier=0.9 },
  WEAPON_PISTOL50 = { PitchMin=0.005, PitchMax=0.009, HeadingMin=-0.006, HeadingMax=0.006, Shake=1.1, FirstShotMultiplier=1.18, AutoFireMultiplier=0.9 },

  -- SMGs
  WEAPON_SMG = { PitchMin=0.006, PitchMax=0.01, HeadingMin=-0.006, HeadingMax=0.006, Shake=1.05, FirstShotMultiplier=1.10, AutoFireMultiplier=0.65 },
  WEAPON_MICROSMG = { PitchMin=0.006, PitchMax=0.01, HeadingMin=-0.006, HeadingMax=0.006, Shake=1.0, FirstShotMultiplier=1.10, AutoFireMultiplier=0.65 },

  -- Rifles
  WEAPON_CARBINERIFLE = { PitchMin=0.006, PitchMax=0.01, HeadingMin=-0.006, HeadingMax=0.006, Shake=1.15, FirstShotMultiplier=1.08, AutoFireMultiplier=0.65 },
  WEAPON_ASSAULTRIFLE = { PitchMin=0.007, PitchMax=0.012, HeadingMin=-0.007, HeadingMax=0.007, Shake=1.20, FirstShotMultiplier=1.08, AutoFireMultiplier=0.65 },
  WEAPON_SPECIALCARBINE = { PitchMin=0.012, PitchMax=0.02, HeadingMin=-0.006, HeadingMax=0.006, Shake=1.15, FirstShotMultiplier=1.08, AutoFireMultiplier=0.65 },

  -- Shotguns
  WEAPON_PUMPSHOTGUN = { PitchMin=0.02, PitchMax=0.032, HeadingMin=-0.008, HeadingMax=0.008, Shake=1.35, FirstShotMultiplier=1.0, AutoFireMultiplier=0.9 },
  WEAPON_SAWNOFFSHOTGUN = { PitchMin=0.022, PitchMax=0.034, HeadingMin=-0.008, HeadingMax=0.008, Shake=1.40, FirstShotMultiplier=1.0, AutoFireMultiplier=0.9 },

  -- Snipers
  WEAPON_SNIPERRIFLE = { PitchMin=0.015, PitchMax=0.024, HeadingMin=-0.004, HeadingMax=0.004, Shake=1.1, FirstShotMultiplier=1.0, AutoFireMultiplier=0.9 },
  WEAPON_HEAVYSNIPER = { PitchMin=0.018, PitchMax=0.028, HeadingMin=-0.004, HeadingMax=0.004, Shake=1.2, FirstShotMultiplier=1.0, AutoFireMultiplier=0.9 },
}

-- Blacklist weapons (no recoil script applied)
Config.Blacklist = {
  WEAPON_STUNGUN = true,
  WEAPON_FIREEXTINGUISHER = true,
  WEAPON_PETROLCAN = true,
  WEAPON_SNOWBALL = true,
  WEAPON_BALL = true,
  WEAPON_FLARE = true,
  WEAPON_GRENADE = true,
  WEAPON_SMOKEGRENADE = true,
  WEAPON_PIPEBOMB = true,
}

-- Optional: per-weapon aim sway overrides (otherwise global sway used)
Config.AimSwayOverrides = {
  -- WEAPON_SNIPERRIFLE = { Pitch=0.04, Heading=0.05, Speed=0.8 },
}