> For the complete documentation index, see [llms.txt](https://codeforge.gitbook.io/codeforge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codeforge.gitbook.io/codeforge/sleek-series/sleek-hud.md). # 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: