Installation

Requirements

FiveM server (recent artifacts, OneSync not required)
Optional: oxmysql — without it HUD data is stored in server resource KVP
Optional: qbx_core (primary) / qb-core / es_extended for money, job, hunger, thirst, stress
Optional: pma-voice or saltychat (falls back to mumble natives), a fuel resource (ox_fuel state bag, LegacyFuel, ps-fuel, cdn-fuel, lj-fuel, okokGasStation), qbx_seatbelt / qb-smallresources, ox_inventory (weapon labels), lb-phone / npwd (phone detection)

No internet access is needed by clients: fonts, icons and sounds are local.

Steps

Copy the ns-hud folder into your resources (e.g. resources/[ns]/ns-hud).
Database (only with oxmysql): tables are created automatically on first start (Config.Storage.autoMigrate = true). To create them manually import sql/hud.sql — it never drops or overwrites existing data.
Add to server.cfg after your framework, oxmysql and voice resource:
```
ensure oxmysql
ensure qbx_core
ensure pma-voice
ensure ns-hud
```

Optional permissions:

# admin tools (/hudreset, /hudtest)
add_ace group.admin ns-hud.admin allow
# only when Config.Editor.permission = 'ace'
add_ace group.vip ns-hud.editor allow

Disable other HUDs (qb-hud, ps-hud, esx_hud…) so the two do not draw over each other.
Restart the server, join and type /hud.

Integrating other HUD features

Phone: if your phone is not lb-phone / npwd and does not set LocalPlayer.state.phoneOpen, call exports['ns-hud']:SetPhoneOpen(true/false) from it, or add its state bag key to Config.Context.phoneStateBags.
Seatbelt: qbx_seatbelt and seatbelt:client:ToggleSeatbelt are detected; otherwise call exports['ns-hud']:SetSeatbelt(bool).
Custom status systems: exports['ns-hud']:SetPlayerStatus({ hunger = 80, thirst = 60, stress = 5 }).
Framework notifications: see Routing all notifications to ns-hud.

Routing all notifications to ns-hud

Scripts send notifications through the framework's notify function, not through ns-hud. Like other HUD resources, ns-hud takes them over with one edit to that central function: individual scripts do not need to change. Each snippet forwards to ns-hud while it is running and falls back to the original UI when ns-hud is stopped.

Qbox / ox_lib (covers lib.notify, ox_lib:notify, exports.qbx_core:Notify and server-side Notify) - ox_lib/resource/interface/client/notify.lua, at the top of function lib.notify(data):

function lib.notify(data)
    if type(data) == 'table' and GetResourceState('ns-hud') == 'started' then
        local ok, sent, err = pcall(function() return exports['ns-hud']:Notify(data) end)
        if ok and (sent or err ~= 'err_invalid_data') then return end
    end
    -- original code continues below

QBCore - qb-core/client/functions.lua, at the top of function QBCore.Functions.Notify(text, texttype, length, icon):

    if GetResourceState('ns-hud') == 'started' then
        local data = type(text) == 'table'
            and { title = text.caption and text.text or nil, message = text.caption or text.text }
            or { message = text }
        data.type, data.duration = texttype, length
        local ok, sent, err = pcall(function() return exports['ns-hud']:Notify(data) end)
        if ok and (sent or err ~= 'err_invalid_data') then return end
    end

ESX - es_extended/client/functions.lua, at the top of function ESX.ShowNotification(message, notifyType, length):

    if GetResourceState('ns-hud') == 'started' then
        local ok, sent, err = pcall(function() return exports['ns-hud']:Notify({ message = message, type = notifyType, duration = length }) end)
        if ok and (sent or err ~= 'err_invalid_data') then return end
    end

Restart the edited resource and ns-hud. Notes:

Updating ox_lib / qb-core / es_extended overwrites this edit - re-apply it after every update.
All forwarded notifications arrive from one resource, so Config.Notifications.rateLimit is shared by every script; raise it if notifications go missing under load.
Notifications are shown in the HUD notification stack (or the player's notifyPosition preference); ox_lib positions, styles and sounds are ignored.

Updating

Replace every file except config.lua and locales/*.lua (compare them with the new version and copy new keys). Data and tables are kept.

Troubleshooting

HUD not visible: check F8 for [ns-hud] errors; /togglehud may be active; Config.Context.hideWhenPaused hides the HUD in the pause menu.
Settings not saved: oxmysql must start before ns-hud, or set Config.Storage.backend = 'kvp'.
Duplicate street / vehicle names: Config.NativeHud.enabled = true hides GTA's own texts.