👱SLEEK HUD

Here check the installation guide

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

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:

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:

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

Money Display

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

Gang Display (QBCore only)

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

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.

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

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

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

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

---

Seatbelt System

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

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

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

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

Stress Relief

Items — configurable inventory items that reduce stress on use:

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:

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

Job whitelist — disable stress for specific jobs:

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

Visual Effects

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

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:

Config.CustomStress = true
Config.UseStress = false

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

Database

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.

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.

Config.Commands.Announce = 'announce'

Usage in-game: /announce Your message here

Test command: /testhudannounce Your message here

---

Notifications

Toggle individual HUD notifications:

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:

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:

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:

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:

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:

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

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

Whitelisted weapons do not generate stress.

---

Translations

Add or edit language packs in config/config_lang.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:

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:

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

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

---

Support

Discord: https://discord.gg/UTVssdrXRV