> For the complete documentation index, see [llms.txt](https://swampys.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://swampys.gitbook.io/docs/resources/gta-6-hud/configuration.md).

# Configuration

Configure HUD modules, controls, status bars, currency, crosshairs and minimap behavior.

All customer-facing options are stored in **config.lua**.

{% stepper %}
{% step %}

#### Modules

Enable or disable individual parts of the HUD:

```lua
Config.Components = {
    statusBars  = true,
    currency    = true,
    quickItems  = true,
    weaponWheel = true,
    crosshair   = true,
    wantedStars = false,
    minimap     = true,
}
```

The visibility exports can temporarily hide the HUD or minimap without changing this configuration.
{% endstep %}

{% step %}

#### Weapon wheel and controls

```lua
Config.Keys = {
    weaponWheel = 'TAB',
    wheelTab = 'Q',
    wheelTabHint = 'R1',
    wheelSelect = 'RETURN',
    wheelClose = 'BACK',
    quickItem1 = 'X',
    quickItem2 = 'Z',
}
```

The wheel can also use native GTA blur and frontend sounds:

```lua
Config.WeaponWheelEffects = {
    blur = {
        enabled = true,
        fadeIn = 180,
        fadeOut = 220,
    },
    sounds = {
        enabled = true,
        soundSet = 'HUD_FRONTEND_DEFAULT_SOUNDSET',
        open = 'SELECT',
        navigate = 'NAV_UP_DOWN',
        tab = 'NAV_LEFT_RIGHT',
        select = 'SELECT',
        itemOn = 'SELECT',
        itemOff = 'BACK',
        close = 'BACK',
    },
}
```

{% endstep %}

{% step %}

#### Crosshair

The crosshair automatically switches between pistol, rifle and shotgun variants. Hitmarkers are white for confirmed damage and red for a lethal hit.

```lua
Config.Crosshair = {
    passiveSpread = 2,
    restingSpread = 5,
    firingSpread = 15,
    rifleFiringSpread = 19,
}
```

{% endstep %}

{% step %}

#### Currency and Focus mode

```lua
Config.Currency = {
    symbol = '$',
    position = 'before',
    spacing = false,
    locale = 'en-US',
    decimalPlaces = 0,
}

Config.HudMode = {
    default = 'focus', -- 'focus' | 'essential'
    toggleControl = 20,
    moneyVisibleDuration = 5000,
    staminaVisibleDuration = 3000,
}
```

* **focus:** information appears only when relevant.
* **essential:** health and currency remain visible.
* **toggleControl:** GTA/FiveM control used to switch modes.
* Display durations are measured in milliseconds.
  {% endstep %}

{% step %}

#### Minimap

```lua
Config.Minimap = {
    showOnFoot = false,
    showGpsDistance = true,
    distanceUnit = 'km',
    xOffset = 0.0,
    yOffset = 0.0,
    nativeYOffset = 0.047,
    width = 0.1764,
    height = 0.18191,
    verticalOffset = -0.010,
    zoom = 1100,
}
```

Set **distanceUnit** to **km** for metres/kilometres or **mi** for feet/miles. Position and size values are screen-relative.
{% endstep %}

{% step %}

#### Status bars

Built-in bars are configured under **Config.StatusBars**:

```lua
Config.StatusBars.health.enabled = true
Config.StatusBars.armor.hideWhenZero = true
Config.StatusBars.mental.enabled = false
```

You can add a custom bar directly from **config.lua**:

```lua
Config.CustomStatusBars = {
    {
        id = 'addiction',
        label = 'Addiction',
        icon = 'nui://my_inventory/web/images/addiction.png',
        color = '#D66BFF',
        order = 60,
        hideWhenZero = true,
        getValue = function()
            return LocalPlayer.state.addiction or 0
        end,
    },
}
```

Values are clamped between 0 and 100. Icons can use a built-in name, an HTTPS URL or a **nui://** URL.
{% endstep %}

{% step %}

#### Clothing slots

Accessory entries displayed in the wheel are defined in **Config.Clothing**. Each entry targets either a ped component or a prop:

```lua
{ id = 'mask', labelKey = 'clothing.mask', type = 'component', index = 1, offDrawable = 0 },
{ id = 'hat', labelKey = 'clothing.hat', type = 'prop', index = 0 },
```

The default configuration includes mask, hat, glasses, ears, chain, top, pants and shoes.
{% endstep %}
{% endstepper %}