> For the complete documentation index, see [llms.txt](https://ayccoes-assets.gitbook.io/ayccoes-assets/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayccoes-assets.gitbook.io/ayccoes-assets/ayc-hud/configurations.md).

# Configurations

This section explains all available configuration options for the HUD resource.

The values defined in `config.lua` serve as the default settings applied to all players when they first join the server. Depending on your server's permissions and configuration, players may be able to customize many of these settings through the in-game settings menu. If a player has not modified a setting, or is not permitted to do so, the default value configured here will be used.

Use this guide to understand what each option controls and how it affects the HUD's appearance, functionality, and gameplay experience.

You can find these configuration files in `shared/config.lua` and `shared/perms.lua`.\
The weapon label mappings can be viewed and modified in `shared/weapons.lua`.

***

## UI Colors

Customize the appearance of the HUD by modifying the color values.

```lua
Config.colors = {
    theme = "#cde6ff",
    armor = "#86fff9",
    hunger = "#fff9a8",
    thirst = "#86fff9",
    stress = "#ffa9c6",
    talking = "#ffa9c6",
    RPMMed = "#fff9a8",
    RPMHigh = "#ffa9c6",
    turnSignal = "#ff6524",
    danger = "#ff0055",
    gearReverse = "#ffa9c6",
    gearNeutral = "#fff9a8",
    bankBalance = "#86ffc6",
    cinematicBars = "#000000",
    weaponDurability = "#86fff9"
}
```

### Available Color Options

| Setting            | Description                    |
| ------------------ | ------------------------------ |
| `theme`            | Primary HUD theme color        |
| `armor`            | Armor indicator color          |
| `hunger`           | Hunger bar color               |
| `thirst`           | Thirst bar color               |
| `stress`           | Stress indicator color         |
| `talking`          | Voice activity indicator color |
| `RPMMed`           | Medium RPM warning color       |
| `RPMHigh`          | High RPM warning color         |
| `turnSignal`       | Turn signals glow color        |
| `danger`           | Critical status color          |
| `gearReverse`      | Reverse gear color             |
| `gearNeutral`      | Neutral gear color             |
| `bankBalance`      | Balance display color          |
| `cinematicBars`    | Cinematic black bars color     |
| `weaponDurability` | Weapon durability bar color    |

***

## HUD Style

Choose the overall HUD appearance.

```lua
Config.style = "sharp"
```

### Options

| Value   | Description               |
| ------- | ------------------------- |
| `sharp` | Modern sharp-edged design |
| `round` | Rounded UI elements       |

***

## Perspective Mode

Enable a perspective-based HUD effect.

```lua
Config.perspective = false
```

### Options

| Value   | Description                 |
| ------- | --------------------------- |
| `true`  | Enable perspective effects  |
| `false` | Disable perspective effects |

***

## Color Mode

Select how HUD colors are displayed.

```lua
Config.colorMode = "colorful"
```

### Options

| Value        | Description                         |
| ------------ | ----------------------------------- |
| `colorful`   | Uses all configured colors          |
| `monochrome` | Uses a single theme color (Primary) |

***

## Speedometer Unit

Set the vehicle speed display unit.

```lua
Config.speedometerUnit = "mph"
```

### Options

| Value | Description         |
| ----- | ------------------- |
| `kmh` | Kilometers per hour |
| `mph` | Miles per hour      |

***

## Compass Base

Determines how the compass calculates direction.

```lua
Config.compassBase = "camera"
```

### Options

| Value       | Description                          |
| ----------- | ------------------------------------ |
| `camera`    | Direction follows player camera      |
| `character` | Direction follows player ped heading |

***

## Cinematic Mode

Controls whether cinematic mode is enabled by default when players join the server.

```lua
Config.cinematicMode = false
```

> **Note:** You may not need to change this configuration.

### Options

| Value   | Description             |
| ------- | ----------------------- |
| `true`  | Cinematic mode enabled  |
| `false` | Cinematic mode disabled |

***

## Cinematic Bars

Show black bars when cinematic mode is active.

```lua
Config.cinematicBars = true
```

### Options

| Value   | Description            |
| ------- | ---------------------- |
| `true`  | Display cinematic bars |
| `false` | Hide cinematic bars    |

***

## Visibility Settings

Control when specific HUD elements are shown.

```lua
Config.visibility = {
    compass = "vehicle",
    worldInfo = "always",
    balance = "dynamic",
    map = "vehicle",
    postal = false,
    iconSize = "medium",
    textSize = "medium",
    playerDetails = false,
    customData = false
}
```

### Compass Visibility

```lua
compass = "vehicle"
```

| Value     | Description                                   |
| --------- | --------------------------------------------- |
| `always`  | Always visible                                |
| `vehicle` | Only visible while in a vehicle               |
| `command` | Togglable through commands (Default /compass) |

***

### World Info Visibility

```lua
worldInfo = "always"
```

| Value     | Description                                     |
| --------- | ----------------------------------------------- |
| `always`  | Always visible                                  |
| `command` | Togglable through commands (Default /worldinfo) |

***

### Balance Visibility

```lua
balance = "dynamic"
```

| Value     | Description                                            |
| --------- | ------------------------------------------------------ |
| `always`  | Always visible                                         |
| `command` | Controlled through commands (Default /cash or /bank)   |
| `dynamic` | Automatically shown when balance changes for 5 seconds |

***

### Map Visibility

```lua
map = "always"
```

| Value     | Description              |
| --------- | ------------------------ |
| `always`  | Always visible           |
| `vehicle` | Only visible in vehicles |

***

### Postal Visibility

```lua
postal = false
```

| Value   | Description      |
| ------- | ---------------- |
| `true`  | Enabled postals  |
| `false` | Disabled postals |

***

### Icon Size

```lua
iconSize = "medium"
```

| Value    | Description        |
| -------- | ------------------ |
| `medium` | Medium sized icons |
| `large`  | Large sized icons  |

***

### Text Size

```lua
textSize = "medium"
```

| Value    | Description        |
| -------- | ------------------ |
| `medium` | Medium sized texts |
| `large`  | Large sized texts  |

***

### Player Details Visibility

```lua
playerDetails = false
```

| Value   | Description             |
| ------- | ----------------------- |
| `true`  | Enabled player details  |
| `false` | Disabled player details |

***

### Custom Data

```lua
customData = false
```

| Value   | Description          |
| ------- | -------------------- |
| `true`  | Enabled custom data  |
| `false` | Disabled custom data |

***

## Readability Gradients

These options add subtle gradients to the four corners of the screen, which vastly improve the readability of HUD text and icons during the day. We recommend keeping the bottom right and bottom left enabled.

```lua
Config.readability = {
    topRight = false,
    topLeft = false,
    bottomRight = true,
    bottomLeft = true
}
```

***

## Performance Mode

Reduces the frequency of value updates to improve performance.

```lua
Config.performanceMode = false
```

### Options

| Value   | Description              |
| ------- | ------------------------ |
| `true`  | Optimize HUD performance |
| `false` | Full visual experience   |

***

Reduces the frequency of value updates to improve performance.

```lua
Config.performanceMode = false
```

### Options

| Value   | Description              |
| ------- | ------------------------ |
| `true`  | Optimize HUD performance |
| `false` | Full visual experience   |

***

## Stress System

The HUD includes a fully configurable stress system.

### Disable Stress

```lua
Config.removeStress = false
```

| Value   | Description                |
| ------- | -------------------------- |
| `true`  | Completely disables stress |
| `false` | Enables stress system      |

***

### Disable Stress for Law Enforcement

```lua
Config.disableStressForLEO = false
```

> Only applicable for QB-Core and Qbox frameworks.

| Value   | Description                       |
| ------- | --------------------------------- |
| `true`  | Police jobs do not receive stress |
| `false` | Police receive stress normally    |

***

### Weapon Stress Chance

```lua
Config.stressChance = 0.1
```

Chance of receiving stress while firing a weapon.

***

### Whitelisted Weapons

Weapons that will not generate stress.

```lua
Config.whitelistedWeapons = {
    `weapon_petrolcan`,
    `weapon_hazardcan`,
    `weapon_fireextinguisher`,
}
```

***

### Speeding Stress

Minimum speed required before speeding can generate stress.

```lua
Config.stressMinForSpeeding = 1000
```

#### Unbuckled Speeding Stress

```lua
Config.stressMinForSpeedingUnbuckled = 50
```

When a player is not wearing a seatbelt, stress can begin accumulating at this speed threshold.

***

## Stress Effects

Configure visual effects based on stress level.

### Effect Intervals

```lua
Config.stressEffectInterval
```

Determines how often stress effects occur.

| Stress Level | Range  |
| ------------ | ------ |
| Level 1      | 50–60  |
| Level 2      | 60–70  |
| Level 3      | 70–80  |
| Level 4      | 80–90  |
| Level 5      | 90–100 |

Higher stress levels trigger effects more frequently.

***

### Blur Intensity

```lua
Config.stressBlurIntensity
```

Controls screen blur strength during stress effects.

| Stress Level | Blur Intensity |
| ------------ | -------------- |
| 50-60        | 1500           |
| 60-70        | 2000           |
| 70-80        | 2500           |
| 80-90        | 2700           |
| 90-100       | 3000           |

***

### Camera Shaking Threshold

```lua
Config.stressMinForShaking = 50
```

Stress must reach this level before screen shake effects occur.

***

## Stress Relief

Automatically reduces player stress over time.

```lua
Config.StressRelief = {
    enabled = true,
    interval = 36000,
    amount = 1,
}
```

### Settings

| Setting    | Description                              |
| ---------- | ---------------------------------------- |
| `enabled`  | Enable automatic stress reduction        |
| `interval` | Time between relief ticks (milliseconds) |
| `amount`   | Stress removed each interval             |

***

## Electric Vehicle Support

The HUD automatically detects electric vehicles and adjusts vehicle-related displays accordingly.

```lua
Config.electricVehicles = {
    `airtug`,
    `caddy`,
    `caddy2`,
    `caddy3`,
    `cyclone`,
    `cyclone2`,
    `dilettante`,
    `imorgon`,
    `iwagen`,
    `khamelion`,
    `neon`,
    `omnisegt`,
    `raiden`,
    `surge`,
    `tezeract`,
    `virtue`,
    `voltic`,
    `voltic2`,
    `envisage`
}
```

### Adding Custom Electric Vehicles

Simply add the vehicle spawn name to the list:

```lua
Config.electricVehicles = {
    `virtue`,
    `tezeract`,
    `mycustomev`
}
```

***

## Permissions Configuration

This section controls which HUD features players are allowed to modify.

The `Perms` table defines access permissions for different parts of the HUD settings system, including movement editing, visual settings, cinematic options, visibility controls, and color customization.

If a value is set to `true`, players are allowed to modify that specific option in the in-game HUD settings menu. If set to `false`, the option will be locked and cannot be changed by the player.

***

## Movement Permissions

Controls which HUD elements can be repositioned in edit mode.

```lua
Perms.Move = {
    playerStatus = true,
    vehicleHUD = true,
    compass = true,
    worldInfo = true,
    weaponHUD = true,
    balance = true,
    notifications = true
}
```

### Options

| Setting         | Description                                |
| --------------- | ------------------------------------------ |
| `playerStatus`  | Allows moving health, armor, hunger, etc.  |
| `vehicleHUD`    | Allows moving vehicle-related HUD elements |
| `compass`       | Allows repositioning the compass           |
| `worldInfo`     | Allows moving world information display    |
| `weaponHUD`     | Allows moving weapon HUD                   |
| `balance`       | Allows moving money/balance display        |
| `notifications` | Allows moving notification UI              |

***

## Settings Permissions

Controls which general HUD settings players can change.

```lua
Perms.Settings = {
    style = true,
    colorMode = true,
    perspective = true,
    speedometerUnit = true,
    compassBase = true
}
```

### Options

| Setting           | Description                                  |
| ----------------- | -------------------------------------------- |
| `style`           | Allows changing HUD style (e.g. sharp/round) |
| `colorMode`       | Allows switching between color modes         |
| `perspective`     | Allows enabling/disabling perspective mode   |
| `speedometerUnit` | Allows changing km/h or mph                  |
| `compassBase`     | Allows changing compass orientation mode     |

***

## Cinematic Permissions

Controls access to cinematic features.

```lua
Perms.Cinematic = {
    cinematicMode = true,
    cinematicBars = true
}
```

### Options

| Setting         | Description                              |
| --------------- | ---------------------------------------- |
| `cinematicMode` | Allows enabling/disabling cinematic mode |
| `cinematicBars` | Allows toggling cinematic black bars     |

***

## Visibility Permissions

Controls which HUD elements players can change visibility mode for.

```lua
Perms.Visibility = {
    compass = true,
    worldInfo = true,
    balance = true,
    map = true
}
```

### Options

| Setting     | Description                                |
| ----------- | ------------------------------------------ |
| `compass`   | Allows changing compass visibility mode    |
| `worldInfo` | Allows changing world info visibility mode |
| `balance`   | Allows changing balance visibility mode    |
| `map`       | Allows changing map HUD visibility mode    |

***

## Color Permissions

Controls which HUD colors players are allowed to customize.

```lua
Perms.Colors = {
    theme = true,
    armor = true,
    hunger = true,
    thirst = true,
    stress = true,
    talking = true,
    RPMMed = true,
    RPMHigh = true,
    danger = true,
    gearReverse = true,
    gearNeutral = true,
    bankBalance = true,
    cinematicBars = true,
    weaponDurability = true
}
```

### Options

| Setting            | Description                       |
| ------------------ | --------------------------------- |
| `theme`            | Main HUD theme color              |
| `armor`            | Armor bar color                   |
| `hunger`           | Hunger bar color                  |
| `thirst`           | Thirst bar color                  |
| `stress`           | Stress indicator color            |
| `talking`          | Voice indicator color             |
| `RPMMed`           | Medium RPM warning color          |
| `RPMHigh`          | High RPM warning color            |
| `danger`           | Critical/danger state color       |
| `gearReverse`      | Reverse gear indicator color      |
| `gearNeutral`      | Neutral gear indicator color      |
| `bankBalance`      | Bank balance display color        |
| `cinematicBars`    | Cinematic bar color               |
| `weaponDurability` | Weapon durability indicator color |

***

## Fuel System

Here you can add your fuel system script name (folder name) for HUD integration.

```lua
Config.fuel = "LegacyFuel"
```

***

## Salty Chat

Use this configuration to set the microphone voice ranges for SaltyChat.

```
Config.SaltyChat = {
    voiceLevels = {
        [1] = 3.5,
        [2] = 8.0,
        [3] = 15.0,
        [4] = 32.0,
    },
}
```

***

## SNT Weapon Durability

This section enables HUD integration with snt-inventory's weapon durability and metadata.

```
Config.sntWeaponDurability = {
    enabled = true,
    metadataKey = "durability"
}
```