A lightweight, customizable FiveM HUD built with React + Vite on the NUI side and modular Lua on the client. It replaces the default radar/health layout with a modern, reason-based visibility system, a custom square minimap, vehicle gauges, aircraft instruments, seatbelt/harness/cruise logic, engine stalling, and runtime VOIP/fuel integrations.

• Custom square/round minimap — texture replacement via stream/squaremap.ytd, layout/clip/mask tuning, big-map recovery, and external map resource detection.
• Player status cluster — health, armor, hunger, thirst, stress, oxygen with configurable icon shapes (bar, hexagon, circle, square) and color themes.
• VOIP indicator — auto-detects pma-voice, saltychat, mumble-voip, tokovoip_script, and zerio-radio; shows talking state, proximity range, and radio channel/talk.
• Vehicle HUD — speedometer (mph/kph), gear, RPM, fuel, engine health, lights; supports disabling the speedometer entirely.
• Fuel integration — auto-detects ox_fuel, ps-fuel, cdn-fuel, LegacyFuel, qb-fuel, esx_fuel, and many others; falls back to native fuel with low-fuel alerts.
• Seatbelt & harness — seatbelt (B) with ejection protection, harness (H) with timed apply/remove and progress UI.
• Cruise control — toggle with Y (configurable), supports both speed-cap and auto-throttle modes.
• Engine stall / breakdown — impact-based stalling with power reduction, smoke damage, and breakdown after too many stalls.
• Aircraft HUD — altitude, airspeed (knots), heading, engine/rotor health, hydraulics proxy, landing gear, and searchlight.
• Location strip — street name, zone, heading compass, and optional nearest-postal postal code/distance.
• Dynamic weather strip — integrates Dynamic_weather / dynamic_weather for current/next weather and ETA, plus flash-flood/hurricane warnings.
• Polcam integration — hides the HUD when polcam is active and optionally forces the aircraft HUD overlay for the pilot.
• Cinematic mode — hides the HUD and radar for clean screenshots/recordings.
• Settings UI — open with /hudsettings (I) to switch layout/color presets, shape styles, blur/opacity, and move speedometer/ammo via drag.
• Visibility reason system — multiple independent reasons (user, external, polcam, cinematic, framework, qbxCharacter, qbxSpawn) all must be true for the HUD to show, making it easy for external scripts to hide/show the HUD safely.

1. Make sure es_lib is installed and starts before es_hud.

2. Build the NUI:

   cd web
   npm install
   npm run build

   If you use Bun, you can run bun install && bun run build instead.

3. Copy the es_hud folder into your FiveM resources directory.

4. Add to server.cfg:

   ensure es_lib
   ensure es_hud

5. Edit config/shared.lua to match your server framework and preferences.

The fxmanifest.lua expects a built NUI at web/dist/:

cd web
npm install
npm run build

web/dist and web/node_modules are intentionally ignored by .gitignore. Do not commit generated build output.

Keys can be changed in config/shared.lua or via FiveM key mapping settings.

These exports can be called from other client scripts:

All tuning is in config/shared.lua.

Config.HudPresets ships with four presets:

• classic — top-center indicator, bottom-left status, bottom-right speedometer.
• street — top-left indicator, bottom-center speedometer, neon accent theme.
• dispatch — utility-heavy, amber accents, right-side speedometer.
• ghost — minimal top-center readouts, soft monochrome, compact right-side driving HUD.

Config.Minimap controls clip type, size, mask, blur, and texture replacement targets. Set textureReplacement.enabled = false if you use a minimap pack that does not provide the squaremap textures.

es_hud/
├── fxmanifest.lua          # Resource manifest (cerulean, lua54, fxv2_oal, strict NUI callbacks)
├── init.lua                # Client entry point; loads config, settings, HUD threads
├── server.lua              # Restarts the `maps` resource on server start
├── config/shared.lua       # All user-facing configuration
├── modules/
│   ├── bridge/client.lua       # Framework hooks (standalone / QBX)
│   ├── cruise/client.lua       # Cruise control logic
│   ├── fuel/client.lua         # Fuel provider detection and alerts
│   ├── harness/client.lua      # Racing harness apply/remove
│   ├── integrations/client/dynamic_weather.lua  # Weather resource integration
│   ├── seatbelt/client.lua     # Seatbelt logic
│   ├── settings/client.lua     # Settings UI, persistence, presets
│   ├── stall/client.lua        # Engine stall/breakdown logic
│   ├── status/client.lua       # Player status and VOIP state gathering
│   ├── threads/client/hud.lua  # Main HUD loop, visibility, exports
│   ├── threads/client/vehicle_status.lua  # Vehicle/aircraft data loop
│   └── utility/shared/         # Minimap helpers and vehicle math
└── web/
    ├── vite.config.js
    ├── package.json
    └── src/
        ├── App.jsx / main.jsx
        ├── components/            # HUD, AircraftHUD, Indicator, StatusOxygenHex, SettingsModal, etc.
        ├── hooks/                 # Motion/animation hooks
        └── hudPresets.js          # Default layout/theme presets

The client Lua threads read game state, then push updates to the React UI through SendNUIMessage. Settings changes are persisted through es_lib and applied back to both the UI and native game state (minimap clip, radar, colors, etc.).

• Requires es_lib — this resource will not start without it.
• Build step required — web/dist is ignored and must be generated with npm run build before use.
• Server-side behavior — server.lua automatically restarts the maps resource when es_hud starts; ensure that is compatible with your server setup.
• Minimap texture replacement relies on stream/squaremap.ytd; disable it in config if you use a different minimap texture pack.
• Aircraft hydraulics is a proxy computed from body health and wing/control-panel damage because GTA V does not expose a dedicated elevator/hydraulics scalar.
• Framework support currently covers standalone and qbx; other frameworks may require bridge additions.
• Experimental features — fxmanifest.lua enables lua54, use_experimental_fxv2_oal, and strict NUI callbacks. Test on your target server build.

MIT © 2026 Ever3st

es_hud is an independent FiveM community resource. It is not affiliated with, endorsed by, or sponsored by Cfx.re, Rockstar Games, Take-Two Interactive, QBCore, QBX, or any other third-party project mentioned in the documentation. All product names, trademarks, and registered trademarks are the property of their respective owners.