# Configuration

> Config reference for ML Recoil

Category: RECOIL · Source: https://miciomods.it/docs/ml-recoil-configuration · Last updated: 2026-07-09

## 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

**shared/config.lua**

```lua
Config.Debug = false
Config.ClassicRecoil = true
Config.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`.

**shared/config.lua**

```lua
Config.DamageSystem = {
    Enabled = true,
    DefaultDamage = 10,
    MinModifier = 0.001,
    MaxModifier = 10.0,
}
```

- `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.

> **WARNING:** Keep vanilla_damage.lua accurate
>
> The modifier is computed against the base values in `shared/vanilla_damage.lua`. If your server runs a modified weapons.meta, update those base values so the resulting damage stays correct. Weapons absent from that table keep a modifier of `1.0`.

## PvP

**shared/config.lua**

```lua
Config.PvP = {
    DisableHeadshotKills = true,
}
```

- `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`.

**shared/config.lua**

```lua
Config.XPSystem = {
    Enabled = true,
    Type = 'client',
    DefaultSkillName = 'shooting',
}
```

- `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.

**shared/config.lua**

```lua
Config.Stance = {
    Enabled = true,
    CrouchMultiplier = 0.7,
    MovementMultiplier = 1.3,
    RunningMultiplier = 2.0,
}
```

- `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.

**shared/config.lua**

```lua
Config.ProgressiveRecoil = {
    Enabled = true,
    IncrementPerShot = 0.1,
    MaxMultiplier = 2.5,
    ResetTime = 400,
}
```

- `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.

**shared/config.lua**

```lua
Config.AimFix = {
    Enabled = true,
    ShakeDuration = 250,
}
```

- `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:

**shared/config.lua**

```lua
[joaat('WEAPON_PISTOL')] = {
    Damage = 26,
    ClassicRecoilAmt = 0.5,
    VerticalRecoil = 0.85,
    HorizontalRecoil = 0.15,
    ShakeName = 'PISTOL_RECOIL_SHAKE',
    ShakeIntensity = 0.8,
    AimSway = 0.8,
}
```

- `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.

> **INFO:** Adding a weapon
>
> Copy any block, change the `joaat()` key to your weapon name, and tune the fields. To get a damage change, also add the weapon's base value to `shared/vanilla_damage.lua`.