Weapons, recoil & magazines

Three places: bs_weapons/config/config_weapons.lua (attachments, magazines, noise), bs_skills/config/config_recoil.lua (recoil) and the weapon items in bs_inventory/config/config_items.lua.

Weapons are items

A weapon is an inventory item with data.weapon = 'WEAPON_X'. Ammo is items too (ammo_pistol, ammo_rifle…). A gun you find in the world is empty, that’s on purpose. Guns an admin spawns come with one mag (spawnRounds).

Attachments

Attachments are real items you fit on a wheel. Default key O (Weapons.Settings.openKey, command /weaponwheel). Slots in Weapons.Slots: muzzle, optic, grip, light, laser, magazine.

Each attachment in Weapons.Attachments maps the item to the base game component per weapon, because a pistol suppressor is a different component from a rifle one. A wrong pairing doesn’t break anything, the slot just isn’t offered.

What they do (Weapons.Effects):

suppressor = { noiseScale = 0.28 },   -- 90 m of noise becomes ~25 m
grip       = { recoil = 0.85 },
extmag     = { ammo = 1.5 },

The suppressor matters a lot here, zombies hear gunshots (Weapons.Noise).

Magazines

Weapons.Magazines, one row per weapon:

WEAPON_PISTOL       = { base = 12, ext = 16, ammo = 'ammo_pistol' },
WEAPON_SMG          = { base = 30, ext = 45, drum = 100, ammo = 'ammo_pistol' },
WEAPON_ASSAULTRIFLE = { base = 30, ext = 45, drum = 100, ammo = 'ammo_rifle' },

Every base value is also in the F1 console (Weapons & Recoil).

Mag check (Weapons.MagCheck): players can check their mag. By default it says roughly how full (“about half”) not the exact count. Set exact = true if you want “17 / 30”.

Recoil

Skills.Recoil in bs_skills/config/config_recoil.lua. Each shot kicks the camera up by the group’s kick, drifts sideways up to drift, never climbs past maxClimb, and shakes by shake:

groups = {
    pistol  = { kick = 0.35, drift = 0.10, maxClimb = 2.5, shake = 0.05 },
    rifle   = { kick = 0.30, drift = 0.12, maxClimb = 3.5, shake = 0.10 },
    shotgun = { kick = 1.10, drift = 0.25, maxClimb = 3.0, shake = 0.22 },
    sniper  = { kick = 1.40, drift = 0.20, maxClimb = 3.0, shake = 0.20 },
    ...
},

weapons.WEAPON_X overrides a group for one gun (the .50 pistol, revolver, heavy sniper…).

What scales it:

• Combat skill: level 0 is lowSkillMult (1.35), max level highSkillMult (0.70). Steady Hands perk x steadyHandsMult.
• Attachments: suppressor and grip cut climb and shake.
• Drugs: the bsDrugMods.sway statebag also scales recoil, clamped to drugMin..drugMax.
• Focus booster: x steady.
• F1: Global.recoilMultiplier for everyone.

After you stop shooting, 60% of the climb comes back down over 250 ms (recoverFraction, recoverMs). Set debug = true to print each shot’s numbers to F8 when tuning.