Configuration

Overview

All tuning lives in two escrow-ignored files. shared/config.lua holds every behaviour toggle and the per-weapon profiles; shared/vanilla_damage.lua holds the base weapons.meta damage values used to convert a target Damage into an engine modifier. There is no server-only config file and no secrets to set.

Global Toggles

1Config.Debug = false
2Config.ClassicRecoil = true
3Config.DisablePistolPunch = true

• Debug: prints per-shot detection lines to the F8 console.
• ClassicRecoil: adds GTA's built-in vertical recoil amplitude (SetWeaponRecoilShakeAmplitude) on top of the camera kick, scaled by ClassicRecoilAmt.
• DisablePistolPunch: blocks the melee pistol-whip controls (140-142) while a configured weapon is held, so firing never triggers a punch.

Damage System

Scales damage engine-side. The modifier is Weapon.Damage / VanillaDamage[hash], clamped between MinModifier and MaxModifier. Defaults match vanilla, so installing changes nothing until you edit a weapon's Damage.

1Config.DamageSystem = {
2    Enabled = true,
3    DefaultDamage = 10,
4    MinModifier = 0.001,
5    MaxModifier = 10.0,
6}

• Enabled: set to false to leave weapons.meta untouched and apply no modifier.
• DefaultDamage: fallback target damage when a weapon profile omits Damage.
• MinModifier / MaxModifier: clamp range for the computed modifier.

PvP

1Config.PvP = {
2    DisableHeadshotKills = true,
3}

• DisableHeadshotKills: when true, calls SetPedSuffersCriticalHits(ped, false) so headshots deal normal damage instead of an instant kill. Applied on spawn and on ped change.

Skill Multiplier (XP System)

Controls where the recoil multiplier comes from. Type = 'client' resolves it locally via GetClientSkillMultiplier; Type = 'server' requests it from the server callback, which calls GetPlayerSkillMultiplier.

1Config.XPSystem = {
2    Enabled = true,
3    Type = 'client',
4    DefaultSkillName = 'shooting',
5}

• Enabled: when false, the multiplier is fixed at 1.0 and no skill lookup runs.
• Type: 'client' or 'server', selecting which hook is called.
• DefaultSkillName: skill name passed to the hook when a weapon profile sets no SkillName.

Stance

Scales recoil by movement state. Crouching steadies the aim; walking and sprinting add penalty.

1Config.Stance = {
2    Enabled = true,
3    CrouchMultiplier = 0.7,
4    MovementMultiplier = 1.3,
5    RunningMultiplier = 2.0,
6}

• CrouchMultiplier: applied while stealth-crouched (below 1.0 = steadier).
• MovementMultiplier: applied while walking (speed above 1.0).
• RunningMultiplier: applied while running or sprinting.

Progressive Recoil

Recoil climbs shot after shot during sustained fire and resets after ResetTime ms of no shooting.

1Config.ProgressiveRecoil = {
2    Enabled = true,
3    IncrementPerShot = 0.1,
4    MaxMultiplier = 2.5,
5    ResetTime = 400,
6}

• IncrementPerShot: added to the multiplier per shot in a burst.
• MaxMultiplier: ceiling for the progressive climb.
• ResetTime: gap in milliseconds that resets the burst counter.

Aim Fix

Adds a short HAND_SHAKE sway burst when the player starts aiming down sights, settling after ShakeDuration ms.

1Config.AimFix = {
2    Enabled = true,
3    ShakeDuration = 250,
4}

• ShakeDuration: settle time in milliseconds before the sway eases to its steady value.

Per-Weapon Profiles

Config.Weapons is keyed by weapon hash (joaat('WEAPON_*')). The shipped list covers the vanilla pistols, SMGs, shotguns, rifles, an MG and snipers, plus an optional DGM Apoc block. Any weapon not in the table is left at its vanilla behaviour. Each profile has the same shape:

1[joaat('WEAPON_PISTOL')] = {
2    Damage = 26,
3    ClassicRecoilAmt = 0.5,
4    VerticalRecoil = 0.85,
5    HorizontalRecoil = 0.15,
6    ShakeName = 'PISTOL_RECOIL_SHAKE',
7    ShakeIntensity = 0.8,
8    AimSway = 0.8,
9}

• Damage: target damage; converted to an engine modifier against the vanilla base.
• ClassicRecoilAmt: classic vertical amplitude used when Config.ClassicRecoil is on.
• VerticalRecoil: upward camera pitch added per shot.
• HorizontalRecoil: sideways camera kick per shot, randomised left or right.
• ShakeName: camera shake preset (the full list of valid names is documented at the bottom of config.lua).
• ShakeIntensity: shake strength per shot.
• AimSway: hand sway intensity while aiming.