ns-hud — NullSect HUD Engine

Simple by default, powerful when customised. A widget-based FiveM HUD: players get a clean classic GTA-style HUD out of the box, and can rebuild almost every part of it in a live in-game editor. Other resources plug their own widgets, rules and notifications into it through a public API.

Turkish: README.tr.md · Install: INSTALLATION.md · Config: CONFIGURATION.md

Features

• 29 built-in widgets — health, armor, hunger, thirst, stamina, stress, oxygen, cash, bank, player ID, server time, voice, compass, street, zone, speed, RPM, gear, fuel, engine, vehicle damage, seatbelt, cruise / limiter, indicators, weapon, ammo, job, objective, notifications.
• Live editor (/hud) on the real HUD: drag & drop, corner resize, 11 anchors (9 screen anchors + beside / above minimap), offset, size, scale, opacity, rotation, colour, icon, font, spacing, variant, visibility, smart-hide. Snap grid, undo/redo, keyboard nudging, ESC to close (asks before discarding).
• Layouts & profiles — ready layouts Classic, Minimal, RP, Racing, Streamer, Glass, Neon plus up to 10 personal layouts per player (save, save-as, rename, delete, switch at any time).
• Themes — Classic, Minimal, Modern, Racing, Glass, Neon, all on the same engine (CSS variables + widget variants: bar / pill / ring / vertical / badge / hex, digital / gauge, bar / segments / line).
• Context-aware — vehicle / on-foot / armed / firearm / underwater / job / phone / paused / dead; widgets hide when irrelevant.
• Rule system — data-driven WHEN … THEN … (show, hide, style, opacity, scale) from config, per layout (rule editor in the UI) and from scripts.
• Notification manager — 4 levels (critical / important / normal / background), stacking, max visible, priority queue, de-duplication (×3), per-resource spam limit, synthesized sounds with volume.
• Focus mode (one key, keeps speed / compass / objective…), cinematic mode (HUD, minimap, notifications, black bars), phone behaviour (shrink / hide).
• Freecam / photo mode (/freecam) — free / orbit / follow camera, smooth zoom (FOV), roll, speed control, depth of field with auto focus and focus on what you aim at, camera shake, motion blur, 17 screen filters (Rockstar Editor film looks, B&W, noir, CCTV…), letterbox (2.39 / 2.00 / 1.85 / 1.33), composition grids, vignette, local time / weather, hide your character, a keyframe camera path that glides through every keyframe on a spline (duration, loop, ease), and lock & play: set up a shot, press K and keep playing through that camera: walk or drive while it follows you at the same angle (optionally swinging round with your vehicle). The server decides who may use it and how far the camera may go (walls block it by default); purely local, nobody else sees anything.
• Car control (/carcontrol, key binding or the ox_lib radial menu) — a panel with a live top-down car that mirrors and controls every door, the hood, trunk, each window, the seats, indicators / hazard lights, interior light, neon and the convertible roof; engine on / off, seat switching, vehicle extras and the boat anchor. Speed, engine / body health and fuel at a glance. You keep driving with the keyboard while the panel is open, Alt hides the cursor so the mouse controls the game again (Alt brings it back), and you can drag it anywhere (the position is remembered).
  • Synced for everyone through a server-checked vehicle state bag, including indicators and the interior light that GTA does not sync, and players who arrive later see the same state.
  • Seat aware: every control has an access level (driver, front, any, none); passengers can still use their own door and window. Standing next to your car you can open doors, trunk and windows and switch lights (needs the keys).
  • Real cruise control that holds the speed uphill, overtakes when you accelerate and comes back when you let go, cancels on the brake; speed limiter; both adjustable in 5 km/h (or mph) steps and shown on the HUD.
  • Indicators that switch off by themselves after the turn, with blinking arrows on the HUD; separate bindable keys for left / right / hazard / cruise / limiter.
  • Fair play: no neon on cars without a neon kit, no engine start without keys, no seat change while fast, belted or cuffed, extras never repair the car, no auto-shuffle into the driver seat.
• Accessibility — HUD / text / icon scale, global opacity, animation speed, UI sound volume, high contrast, larger text, reduced motion, colour-blind palettes (protanopia / deuteranopia / tritanopia).
• Resolution-safe — reference grid scaled by screen height, GTA safezone respected, game aspect followed (multi-monitor), every widget clamped inside the safe area (rotation included). Tested 720p → 4K, 21:9 and 32:9.
• Persistent — oxmysql (auto-migrated tables) or server KVP fallback; per license or per character.
• Performance — one adaptive loop (80 ms in vehicle, 250 ms on foot, 1 s hidden), values diffed and batched into a single NUI message per 40 ms window; zero NUI traffic while nothing changes.
• Secure — server-authoritative storage, strict validation of every layout / rule / pref, ownership checks, rate limits, per-player lock; external widget data is sanitised and rendered with textContent only.
• Qbox first, QBCore / ESX / standalone through bridge/; voice adapters for pma-voice, SaltyChat and mumble.

Commands

Keys are registered with RegisterKeyMapping, players can rebind them in Settings → Key Bindings → FiveM.

Freecam keys

Keys are GTA control ids in Config.Freecam.controls (with the hint labels in Config.Freecam.keyLabels). Settings are remembered per player on their own PC.

Car control

Change the levels in Config.CarControl.access. On foot (within 5 m, with the keys) the panel offers doors, hood, trunk, windows, interior light and neon.

Client exports

All exports remember the calling resource; everything it registered is cleaned up automatically when it stops.

local hud = exports['ns-hud']

hud:RegisterWidget(def)            --> ok, errKey
hud:RemoveWidget(id)
hud:ShowWidget(id) / hud:HideWidget(id)
hud:SetWidgetVisible(id, true|false|nil)   -- nil = back to automatic
hud:UpdateWidget(id, data)         -- merge
hud:SetWidgetData(id, data)        -- replace
hud:GetWidget(id)                  --> { definition, data, override }
hud:ResetWidget(id)
hud:Notify(data)                   -- or Notify(message, type, duration)
hud:ClearNotifications()
hud:SetObjective(title, text) / hud:ClearObjective()
hud:AddRule(rule) / hud:RemoveRule(id)
hud:SetContext(key, value)         -- custom rule field 'ext.<key>'
hud:SetPhoneOpen(bool|nil) / hud:SetSeatbelt(bool) / hud:SetPlayerStatus({ hunger = 80, thirst = 60, stress = 10 })
hud:SetFocusMode(bool) / hud:ToggleFocusMode() / hud:IsFocusMode()
hud:SetCinematicMode(bool) / hud:IsCinematicMode()
hud:SetHudHidden(bool) / hud:IsHudVisible()
hud:OpenEditor() / hud:IsReady()
hud:IsFreecamActive() / hud:StopFreecam()
hud:OpenCarControl() / hud:CloseCarControl() / hud:IsCarControlOpen()

Local event ns-hud:cl:freecam (active) fires when the freecam starts / stops, so other scripts can pause their own key handling. ns-hud:cl:freecamplay (playing) fires when the camera is locked / unlocked (while locked the player has the controls again).

Server: exports['ns-hud']:Notify(playerId | -1, data).

Registering a job widget (taxi example)

local function registerTaxiWidget()
    exports['ns-hud']:RegisterWidget({
        id = 'taxi_ride', label = 'Taxi', category = 'job', icon = 'taxi', color = '#f5c518',
        template = 'panel',           -- 'panel' (title + rows) | 'value' | 'status' (bar)
        focus = true,                 -- stays visible in focus mode
        fields = {
            { key = 'passenger', label = 'Passenger', icon = 'user' },
            { key = 'destination', label = 'Destination', icon = 'pin' },
            { key = 'fare', label = 'Fare', format = 'money' },     -- text | number | money | percent | distance | time | speed
            { key = 'eta', label = 'ETA', format = 'time' },
        },
        defaults = { anchor = 'cr', x = 0, y = -40 },
    })
end
AddEventHandler('ns-hud:cl:ready', registerTaxiWidget)            -- ns-hud (re)started
CreateThread(function()
    if GetResourceState('ns-hud') == 'started' then registerTaxiWidget() end
end)

-- during a ride
exports['ns-hud']:SetWidgetVisible('taxi_ride', true)
exports['ns-hud']:UpdateWidget('taxi_ride', { passenger = 'Michael', destination = 'Airport', fare = 84, eta = 95 })
-- ride finished
exports['ns-hud']:SetWidgetVisible('taxi_ride', false)

Same pattern for other jobs, e.g. bus { route, next_stop, passengers, stop_requests }, locksmith { job, target, distance (format = 'distance'), objective }, tow { call, vehicle, distance, objective }. Instead of manual visibility, set jobs = { 'taxi' } and the widget shows whenever the player has that job.

Rules

exports['ns-hud']:AddRule({
    id = 'taxi_meter_running',
    when = { { 'ext.meter', '==', true }, { 'speed', '>', 120 } },
    actions = { { 'style', 'taxi_ride', 'warning' }, { 'show', 'objective' } },
})
exports['ns-hud']:SetContext('meter', true)

Fields: vehicle onfoot armed firearm dead underwater health armor hunger thirst stress stamina oxygen speed rpm fuel engine body seatbelt job duty phone talking radio hour and ext.<key>. Operators: == != < <= > >= in. Actions: show hide style opacity scale; styles: warning danger highlight pulse muted success.

Notifications

exports['ns-hud']:Notify({
    title = 'Dispatch', message = 'New call at Legion Square',
    level = 'important',   -- critical | important | normal | background
    type = 'info',         -- info | success | warning | error
    icon = 'bell', duration = 6000, sound = 'chime', priority = 60, position = 'top-right',
})

License

© NullSect. Fonts: Barlow, Barlow Condensed, Share Tech Mono — SIL Open Font License (see nui/fonts/OFL-*.txt).