# SLEEK HUD

Advanced HUD for FiveM with status bars, vehicle speedometer, compass, aircraft instruments, bicycle HUD, stress system, seatbelt, zones, announcements, and a full player customization panel.

**Frameworks:** ESX / QBCore (auto-detected)\
**SQL:** oxmysql · mysql-async · ghmattimysql (auto-detected)\
**Lua:** 5.4

***

### Features

* Auto-detection of ESX / QBCore — no manual framework config needed
* Health, armor, hunger, thirst, oxygen and stress bars with configurable colors
* Cash, bank and optional third currency display (black money, crypto, etc.)
* Job and grade display with full label mapping
* Vehicle speedometer with 4 styles: Arc, Bold, Round, Minimal
* Compass heading bar (N/S/E/W with degrees) — toggleable from HUD Panel
* Aircraft HUD with compass rose, altitude and speed — activates in planes and helicopters
* Boat HUD with nautical compass rose, heading and speed in knots — activates in boats
* Bicycle HUD with minimal speedometer — activates on bicycles
* Seatbelt system with ejection, sounds and NUI warning — auto-disabled on bicycles
* Cruise control with keybind and command
* Weapon display with ammo count and weapon images
* Low fuel warning with sound
* Safe Zone / Red Zone system with on-screen indicators and map blips
* Server announcement system with centered overlay and progress bar
* Full HUD customization panel (display mode, color, size, speedometer style, toggles)
* Minimap control — always visible or vehicle-only
* Cinematic mode command
* Address / street name display
* Player count indicator
* Multi-language support (EN, ES — easily extensible)
* Stress visual effects (blur, timecycle, camera shake, screen pulses) with 5 intensity levels
* Stress relief items from inventory (ox\_inventory, qb, qs-inventory, esx)
* Stress from: weapons, vehicle speed, collisions, unbuckled driving
* Stress reduction in Safe Zones
* Job-based stress whitelist
* Discord-ready command system
* Low resource consumption

***

### Requirements

| Dependency                                       | Notes                                                  |
| ------------------------------------------------ | ------------------------------------------------------ |
| FiveM server build **5848+**                     | Lua 5.4 support                                        |
| **OneSync**                                      | Required                                               |
| **es\_extended** or **qb-core/qbox**             | Framework                                              |
| **oxmysql**, **mysql-async** or **ghmattimysql** | SQL wrapper (only needed if `Config.UseStress = true`) |
| **PolyZone**                                     | Required — used for Safe/Red zone detection            |
| **pma-voice**                                    | Optional — proximity cycle indicator                   |

***

### Installation

#### Step 1 — Place the resource

Copy `forge-hud` into your server's `resources/` directory.

#### Step 2 — server.cfg

```cfg
ensure PolyZone
ensure forge-hud
```

`PolyZone` must start **before** `forge-hud`.

#### Step 3 — Start your server

The resource **auto-creates** all required database tables on first boot — no manual SQL import needed.

> The `forge_hud_stress.sql` file is included as a reference, but auto-migration handles everything automatically.

#### Important

The HUD must be started with a **full server restart** — hot-ensuring while the server is running may cause issues with the minimap and player count markers.

***

### Configuration

All config files live in the `config/` folder:

| File                   | Purpose                                                                 |
| ---------------------- | ----------------------------------------------------------------------- |
| `config.lua`           | Master config — HUD features, stress, seatbelt, zones, sounds, UI theme |
| `config_framework.lua` | Framework bridge functions — adapt to custom frameworks here            |
| `config_lang.lua`      | Translations (EN, ES) for NUI and notifications                         |

#### Auto-detection

Framework, SQL library and voice system are detected automatically at startup. Override manually if needed:

```lua
Config.Framework = 'esx'           -- 'esx' or 'qb'
Config.StressDatabase.Wrapper = 'oxmysql'  -- 'oxmysql', 'ghmattimysql', 'mysql-async'
```

***

### HUD Elements

#### Status Bars

Health, armor, hunger, thirst, oxygen and stress. Each bar can be toggled individually:

```lua
Config.Settings = {
    ShowHealth = true,
    ShowHunger = true,
    ShowThirst = true,
    ShowArmor = true,
    ShowOxygen = true,
    ShowMicroVolume = true,
    ShowSpeedometer = true,
    ShowCompass = true,
    ShowJob = true,
}
```

#### Money Display

```lua
Config.ShowMoneyInHud = true
Config.ExtraMoney = {
    Active = false,          -- Enable third currency
    Image = 'wallet.svg'    -- Icon in nui/images/
}
```

#### Gang Display (QBCore only)

```lua
Config.ShowGang = true
```

***

### Vehicle HUD

#### Speedometer

4 built-in styles selectable from the HUD Panel:

| Style     | Description              |
| --------- | ------------------------ |
| `arc`     | Classic analog arc gauge |
| `digital` | Digital numeric display  |
| `sport`   | Sport-style RPM gauge    |
| `minimal` | Compact numeric-only     |

```lua
Config.UseMPH = false  -- true = MP/H, false = KM/H
Config.Menu.speedoType = "arc"  -- Default style
```

#### Compass

Heading bar at the top center with cardinal directions (N, NE, E, SE, S, SW, W, NW) and degree readout. Smooth lerp animation.

```lua
Config.UseCompass = true
Config.Settings.ShowCompass = true
```

Toggleable from the in-game HUD Panel.

#### Aircraft HUD

Activates automatically when entering a plane or helicopter. Replaces the car speedometer with:

* Compass rose with heading indicator
* Altitude display
* Airspeed display

```lua
Config.UseAircraftHud = true
```

#### Boat HUD

Activates automatically when entering a boat. Replaces the car speedometer with a nautical-themed HUD:

* Compass rose that rotates with vessel heading
* Heading readout in degrees
* Speed in knots (KN)
* Anchor icon

```lua
Config.UseBoatHud = true
```

#### Bicycle HUD

Activates automatically on bicycles. Shows a compact speedometer with a bicycle icon. Seatbelt system is automatically disabled on bicycles.

#### Fuel Warning

```lua
Config.UseLowFuel = true
Config.MinimumFuel = 20  -- Warning threshold (%)
```

***

### Seatbelt System

Full seatbelt with ejection on collision, NUI sounds and unbuckled warning.

```lua
Config.UseSeatBelt = true
Config.ToggleSeatbelt = 'B'           -- Keybind
Config.EjectSpeed = 45.0              -- Min speed for ejection (km/h)
Config.EjectAccel = 100.0             -- Min acceleration for ejection
Config.SeatbeltSound = {
    Enabled = true,
    Volume = 0.85,
    WarningIntervalMs = 1000,
}
```

Bicycles and motorcycles are excluded from the seatbelt system.

***

### Cruise Control

```lua
Config.Cruise = {
    Active = true,
    Keybind = 'U',
    Command = 'cruise',
}
```

***

### Stress System

Persistent stress saved to database. Multiple stress sources and configurable visual effects.

#### Stress Sources

| Source            | Config                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| **Weapons**       | `Config.StressChance`, `Config.WeaponStress` — burst aggregation per shot window                  |
| **Vehicle speed** | `Config.MinimumSpeed` (buckled), `Config.MinimumSpeedUnbuckled` — periodic stress above threshold |
| **Collisions**    | `Config.StressCollision` — damage-proportional stress on vehicle impacts                          |

#### Vehicle Stress Tuning

```lua
Config.VehicleStress = {
    intervalMs = 4000,
    baseMin = 3,
    baseMax = 6,
    overSpeedFactor = 0.04,
    maxPerTick = 12,
}
```

#### Stress Relief

**Items** — configurable inventory items that reduce stress on use:

```lua
Config.ReliefItems = {
    enabled = true,
    inventory = 'ox_inventory',  -- 'ox_inventory' | 'qb' | 'qs-inventory' | 'esx'
    cooldownSeconds = 1,
    items = {
        beer = 15,
        joint = 35,
        -- add more
    },
}
```

**Safe Zones** — automatic stress reduction while inside:

```lua
Config.SafeZoneStress = {
    enabled = true,
    amount = 18,
    intervalSeconds = 20,
}
```

**Job whitelist** — disable stress for specific jobs:

```lua
Config.DisableStressJobs = true
Config.StressWhitelistJobs = { 'police', 'ambulance' }
```

#### Visual Effects

5 intensity levels with configurable blur, timecycle, camera shake and screen pulses:

```lua
Config.StressEffects = {
    enabled = true,
    blur    = { enabled = true, effect = 'DRUG_2_drive' },
    shake   = { enabled = true, baseScale = 0.08, maxScale = 1.2 },
    screen  = { enabled = true, onEnter = 'FocusIn', onHigh = 'Rampage' },
    Levels = {
        [1] = { min = 20,  max = 49,  intervalMs = 60000, blurIntensity = 1400 },
        [2] = { min = 50,  max = 64,  intervalMs = 45000, blurIntensity = 1800 },
        [3] = { min = 65,  max = 79,  intervalMs = 35000, blurIntensity = 2200 },
        [4] = { min = 80,  max = 94,  intervalMs = 22000, blurIntensity = 2600 },
        [5] = { min = 95,  max = 100, intervalMs = 14000, blurIntensity = 3000 },
    },
}
```

#### External Stress

Use your own stress system instead of the built-in one:

```lua
Config.CustomStress = true
Config.UseStress = false
```

Then implement `MAV.Functions.GetStress` in `config_framework.lua`.

#### Database

```lua
Config.StressDatabase = {
    Wrapper = detectSQL(),           -- Auto-detected
    Table = 'forge_hud_stress',     -- Created automatically on start
}
```

***

### Zones

Safe Zone and Red Zone system — on-screen indicator and optional map blips.

```lua
Config.Zones = {
    settings = {
        blips = {
            enabled = true,
            safe = { enabled = true, color = 2, alpha = 120 },
            red  = { enabled = false, color = 1, alpha = 120 },
        },
    },
    ['SAFE'] = {
        { coords = vector3(x, y, z), radius = 50.0 },
    },
    ['RED'] = {
        { coords = vector3(x, y, z), radius = 30.0 },
    },
}
```

***

### Announcements

Server-wide announcement overlay triggered by admins. Centered on screen with backdrop blur, animated card, icon pulse and progress bar.

```lua
Config.Commands.Announce = 'announce'
```

Usage in-game: `/announce Your message here`

Test command: `/testhudannounce Your message here`

***

### Notifications

Toggle individual HUD notifications:

```lua
Config.Notification = {
    HudIsLoaded = true,
    MapIsLoaded = true,
    FuelIsLow = true,
    GainStress = true,
    Seatblet = true,
    CashChange = true,
    BankChange = true,
    LowHealth = true,
    LowThirst = true,
    LowHunger = true,
}
```

***

### UI Theme

Customize all colors from config — no CSS editing needed:

```lua
Config.UI = {
    Colors = {
        Accent = {
            Primary  = '#00c5ff',
            Muted    = '#31afd4',
        },
        Background = {
            Deep    = 'rgba(8, 11, 22, 0.88)',
            Surface = 'rgba(12, 16, 28, 0.60)',
            Border  = 'rgba(80, 120, 160, 0.10)',
        },
        Text = {
            Primary   = '#ffffff',
            Secondary = '#8a8fa8',
            Muted     = '#555b74',
        },
        Bars = {
            Health = '#ff4757',
            Armor  = '#3498db',
            Oxygen = '#1abc9c',
            Hunger = '#ffa502',
            Thirst = '#3742fa',
            Stress = '#a55eea',
        },
    },
    Font = 'Poppins',
}
```

***

### HUD Panel (Player Customization)

Players can open the HUD Panel to customize their experience:

* **Display modes:** Normal, Reduced, Minimal
* **Color picker** — change accent color
* **Size slider** — scale HUD elements
* **Speedometer style** — choose between 4 styles
* **Toggles:** Cinematic, No HUD, No Minimap, Compass

Settings are saved per player in browser localStorage.

Open with keybind (default `I`) or command:

```lua
Config.UseKeyOpen = true
Config.OpenMenu = 'I'
Config.Commands.OpenHUD = 'menu'
```

***

### Commands

| Command           | Description                      | Config Key                       |
| ----------------- | -------------------------------- | -------------------------------- |
| `/menu`           | Open HUD customization panel     | `Config.Commands.OpenHUD`        |
| `/cinematic`      | Toggle cinematic mode            | `Config.Commands.Cinematic`      |
| `/nohud`          | Toggle HUD visibility            | `Config.Commands.NoHud`          |
| `/resethud`       | Reset HUD to defaults            | `Config.Commands.ResetHUD`       |
| `/announce [msg]` | Server-wide announcement (admin) | `Config.Commands.Announce`       |
| `/toggleseatbelt` | Toggle seatbelt                  | `Config.Commands.ToggleSeatbelt` |
| `/cruise`         | Toggle cruise control            | `Config.Cruise.Command`          |
| `/zone`           | Teleport to zone (debug only)    | `Config.Commands.ZoneTP`         |

***

### Sounds

All sounds use GTA native audio. Configure per-event:

```lua
Config.Sounds = {
    ['BUCKLE']      = { Enabled = true, AudioName = 'CONFIRM_BEEP', AudioRef = 'HUD_MINI_GAME_SOUNDSET' },
    ['UNBUCKLE']    = { Enabled = true, AudioName = 'CANCEL', AudioRef = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    ['FUEL']        = { Enabled = true, AudioName = 'CANCEL', AudioRef = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    ['ANNOUNCE']    = { Enabled = true, AudioName = 'CHARACTER_SELECT', AudioRef = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    ['STRESS_MAX']  = { Enabled = true, AudioName = 'MP_RANK_UP', AudioRef = 'HUD_FRONTEND_DEFAULT_SOUNDSET' },
    ['STRESS_PULSE']= { Enabled = false, AudioName = 'FocusIn', AudioRef = 'Hints' },
}
```

***

### Jobs

Define job names and grade labels to display on the HUD. This also improves performance by avoiding framework lookups:

```lua
Config.Jobs = {
    ['police'] = { [0] = 'Recruit', [1] = 'Officer', [2] = 'Sergeant', [3] = 'Lieutenant', [4] = 'Chief' },
    ['ambulance'] = { [0] = 'Recruit', [1] = 'Paramedic', [2] = 'Doctor', [3] = 'Surgeon', [4] = 'Chief' },
    -- add all your server jobs here
}
```

***

### Weapons

Weapon images are stored in `nui/images/weapons/`. Add or replace PNGs matching the weapon hash name:

```lua
Config.Weapons = {
    [GetHashKey('WEAPON_PISTOL')] = { 'WEAPON_PISTOL' },
    [GetHashKey('WEAPON_CARBINERIFLE')] = { 'WEAPON_CARBINERIFLE' },
    -- add more
}
```

```lua
Config.WhitelistedWeaponStress = { `weapon_petrolcan`, `weapon_fireextinguisher` }
```

Whitelisted weapons do not generate stress.

***

### Translations

Add or edit language packs in `config/config_lang.lua`:

```lua
Config.Locale = 'en'  -- 'en', 'es', or add your own
```

Keys prefixed with `ui.` are sent to the NUI frontend. All other keys are used client/server side for notifications and chat messages.

***

### Custom Framework

If you use a custom or modified framework, edit the bridge functions in `config/config_framework.lua`:

* `MAV.Functions.Notify(message, type)` — notification system
* `MAV.Functions.GetFuel(vehicle)` — fuel reading
* `MAV.Functions.PlayerIsLogged()` — player loaded check
* `MAV.Functions.GetPlayerData()` — money, job, hunger, thirst
* `MAV.Functions.GetStaticId()` — static player ID (optional)

All event names (player loaded, job update, money change, etc.) are also configurable in this file.

***

### Exports

#### Client Exports

| Export              | Description                             |
| ------------------- | --------------------------------------- |
| `ShowSafeZoneHud()` | Show the SAFE ZONE indicator on the HUD |
| `ShowRedZoneHud()`  | Show the RED ZONE indicator on the HUD  |
| `HideZoneHud()`     | Hide the zone indicator                 |

**Usage:**

```lua
exports['forge-hud']:ShowSafeZoneHud()
exports['forge-hud']:ShowRedZoneHud()
exports['forge-hud']:HideZoneHud()
```

***

### Events

#### Server Events (trigger from other resources)

| Event                           | Parameters                 | Description                                        |
| ------------------------------- | -------------------------- | -------------------------------------------------- |
| `forge-hud:server:AddStress`    | `amount`, `reason`, `meta` | Add stress to the triggering player                |
| `forge-hud:server:RemoveStress` | `amount`, `reason`, `meta` | Remove stress from the triggering player           |
| `forge-hud:addStress`           | `value`                    | Legacy — add stress (no reason/meta)               |
| `forge-hud:server:announce`     | `message`                  | Broadcast announcement to all players (admin only) |

#### Client Events (trigger from server with TriggerClientEvent)

| Event                              | Parameters | Description                                   |
| ---------------------------------- | ---------- | --------------------------------------------- |
| `forge-hud:client:announceReceive` | `message`  | Show announcement overlay on target client(s) |
| `forge-hud:updateStress`           | `value`    | Force-set stress value on a client            |
| `forge-hud:resetStress`            | —          | Reset stress to 0 on a client                 |

**Example — add stress from another resource:**

```lua
-- Server-side
TriggerClientEvent('forge-hud:server:AddStress', source, 15, 'custom', nil)

-- Or from client-side
TriggerServerEvent('forge-hud:server:AddStress', 10, 'custom', nil)
```

**Example — send announcement from server:**

```lua
TriggerClientEvent('forge-hud:client:announceReceive', -1, 'Server restarting in 5 minutes')
```

***

### Support

Discord: <https://discord.gg/UTVssdrXRV>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://codeforge.gitbook.io/codeforge/sleek-series/sleek-hud.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.