Usage

The HUD shows automatically when a player spawns. It hides on disconnect or character unload, and shows a death overlay when the medical adapter fires the bridge died/revived events.

General Settings

All options are in config.lua. Restart the resource after changes.

Option	Default	Description
Config.Debug	false	Reserved for future debug logging
Config.ThemeColor	"#87DA21"	Accent color for car/aircraft HUD, voice, compass icons, etc. Hex (#RRGGBB) or RGB ("r, g, b"). Does not control health/armor (see below).
Config.HealthColor	"#87DA21"	Health bar and value color (independent of theme)
Config.ArmorColor	"#00B2FF"	Armor bar and value color (independent of theme)
Config.ServerLogo.url	"https://prodigyrp.net/assets/logo.png"	Server logo image URL. Leave as an empty string ("") for no logo.
Config.ServerLogo.position	"top-right"	Logo placement: "top-right", "top-left", "top-center", "bottom-right", "bottom-left", "bottom-center"
Config.HealthUpdateMs	200	How often health and armor are refreshed (ms)
Config.MinimapUpdateMs	1000	How often street/compass location data is refreshed (ms)
Config.VehicleUpdateMs	100	How often the speedometer is refreshed (ms). 0 = every frame
Config.SpeedUnit	"MPH"	Speed and waypoint distance unit — "MPH" or "KMH"
Config.Compass	"always"	Compass visibility — "always", "vehicle", or "never"
Config.MinimapType	"rect"	Minimap style — "rect" (square) or "circle"
Config.MapOffset.x	0.015	Horizontal minimap offset
Config.MapOffset.y	-0.035	Vertical minimap offset
Config.ShowMinimap	"always"	Radar visibility — "always", "vehicle", or "never" (same options as Compass)

Theme and status colors

Config.ThemeColor = "#87DA21"   -- car HUD, voice, compass accents
Config.HealthColor = "#87DA21"  -- health bar only
Config.ArmorColor = "#00B2FF"   -- armor bar only

Change colors at runtime:

exports["prp-hud"]:SetThemeColor("#FF5500")
exports["prp-hud"]:SetHealthColor("#FF0000")
exports["prp-hud"]:SetArmorColor("#00B2FF")

Compass

The top bar shows direction, street name, and zone.

Config.Compass value	Behaviour
"always"	Visible whenever the HUD is shown
"vehicle"	Visible only in a vehicle
"never"	Hidden unless forced via export or GPS

Direction labels (N, E, S, W) are defined in locales/*.json.

Exports

Export	Description
SetCompassMode(mode)	Change mode at runtime — "always", "vehicle", or "never"
SetCompassVisible(visible)	Force the compass on or off
ResetCompassVisible()	Clear the forced override
ShowCompass()	Shortcut for SetCompassVisible(true)
HideCompass()	Shortcut for SetCompassVisible(false)

exports["prp-hud"]:SetCompassMode("vehicle")
exports["prp-hud"]:ShowCompass()

GPS event

Toggle the compass on foot (useful when Config.Compass = "vehicle"):

TriggerEvent("prp-hud:client:activateMap")       -- toggle
TriggerEvent("prp-hud:client:activateMap", true)  -- force on
TriggerEvent("prp-hud:client:activateMap", false) -- force off

Minimap

Two minimap styles are available: rect (square) and circle.

Set the default in config.lua:

Config.MinimapType = "rect"   -- or "circle"
Config.ShowMinimap = "always" -- "always", "vehicle", or "never"

Config.ShowMinimap value	Behaviour
"always"	Radar visible whenever the HUD is shown
"vehicle"	Radar visible only in a vehicle
"never"	Radar hidden unless forced via export

The default GTA waypoint distance under the radar is hidden. prp-hud shows its own distance chip above the minimap while the vehicle HUD is active (see Waypoint distance).

Switch style or visibility at runtime:

exports["prp-hud"]:SetMinimap("circle")
exports["prp-hud"]:SetMinimap("rect")

exports["prp-hud"]:SetMinimapMode("vehicle")
exports["prp-hud"]:SetMinimapVisible(true)
exports["prp-hud"]:ResetMinimapVisible()

Adjust position with Config.MapOffset. Other resources can read the current anchor:

local anchor = exports["prp-hud"]:GetMinimapAnchor()

Exports

Export	Description
SetMinimap(type)	Set minimap style — "rect" or "circle"
SetMinimapMode(mode)	Change visibility mode — "always", "vehicle", or "never"
SetMinimapVisible(visible)	Force the radar on or off
ResetMinimapVisible()	Clear the forced override
GetMinimapAnchor()	Returns the current minimap anchor data

Status icons

Default statuses (hunger, thirst, stress) are defined in Config.Statuses. Values come from prp-bridge (bridge.fw.getHunger(), etc.) and are normalized to 0–1 for the HUD.

Statuses render in id order (lowest first). Set id on each entry to control left-to-right order:

Config.Statuses = {
    PLAYER_HUNGER = {
        id = 1, -- shown first
        icon = "Salad",
        color = "255, 229, 0",
        max = 1,
        stateBag = "hunger",
        getValue = function()
            return bridge.fw.getHunger() / 100
        end,
    },
    PLAYER_THIRST = {
        id = 2,
        icon = "GlassWater",
        color = "98, 234, 253",
        max = 1,
        stateBag = "thirst",
        getValue = function()
            return bridge.fw.getThirst() / 100
        end,
    },
    PLAYER_STRESS = {
        id = 3,
        icon = "Brain",
        color = "181, 89, 254",
        max = 1,
        hideProgress = true, -- icon only, no vertical bar
        stateBag = "stress",
        getValue = function()
            return bridge.fw.getStress() / 100
        end,
    },
}

Hunger, thirst, and stress use 0–100 where 100 = full. Divide by 100 in getValue.

Status options

Field	Description
id	Display order (lower = further left)
icon	Lucide icon name
color	RGB string ("r, g, b")
max	Max value for the bar (usually 1)
stateBag	Optional player state bag key for live updates
getValue	Function returning the current value (0–1)
hideProgress	Hide the vertical bar; keep the icon
hideHigh	Hide when value is near full (≥ 0.9)
hideZero	Hide when value is 0
inverted	Invert the bar fill

Add a custom status

From another resource:

exports["prp-hud"]:RegisterStatus(
    "oxygen",
    0.75,
    1,
    "Waves",
    "0, 255, 0",
    true,
    false,
    { id = 10, hideZero = true }
)

Clear all dynamic statuses:

exports["prp-hud"]:ResetStatus()

HUD visibility

Export	Description
Show()	Show the HUD
Hide()	Hide the HUD
Toggle()	Toggle visibility

exports["prp-hud"]:Show()
exports["prp-hud"]:Hide()

Phone offset

Shift the bottom-right HUD stack when a phone UI is open:

exports["prp-hud"]:SetPhoneHeight(120)  -- pixels
exports["prp-hud"]:SetPhoneHeight(0)    -- reset

Voice indicator

Voice data is handled by prp-bridge (BridgeConfig.Voice = "pma-voice"). prp-hud listens for proximity, talking, and radio/phone state automatically — nothing to configure in config.lua.

Disable pma-voice's built-in UI so it does not overlap with prp-hud. In server.cfg, set the pma-voice voice_enableUi convar to 0:

setr voice_enableUi 0

If pma-voice is not running, the voice indicator falls back to a disconnected state.

Speedometer

The vehicle HUD appears automatically when you are the driver (seat -1) and the main HUD is visible. It hides when you exit the vehicle or move to a passenger seat.

Speed uses Config.SpeedUnit ("MPH" or "KMH"). RPM comes from GetVehicleDashboardRpm / 1.3 while the engine is running.

Config.SpeedUnit = "MPH" -- or "KMH"

Fuel

Fuel is read through prp-bridge (BridgeConfig.VehicleFuel). Set your fuel script in bridge config (for example ox_fuel, qb-fuel, LegacyFuel). The HUD calls bridge.vfuel.get(vehicle) and displays the value as 0–1.

Engine and check engine

• Engine running — shown for all vehicle classes except bicycles (class 13).
• Check engine — lit when GetVehicleEngineHealth(vehicle) <= 300.

Seatbelt

Seatbelt defaults to on (client/belt.lua). The indicator is hidden for motorcycles, bicycles, boats, helicopters, and planes (classes 8, 13, 14, 15, 16).

Wire your seatbelt script to the exports below, or edit client/belt.lua directly (escrow-open).

Nitro

Nitro is off by default (client/nitro.lua). Implement Nitro.IsVisible, Nitro.GetLevel, and related functions in that file, or drive values from another resource via exports.

Aircraft HUD

Helicopters (class 15) and planes (class 16) swap the car speedometer for the aircraft instruments: fuel, airspeed, artificial horizon (pitch/roll), altitude, AGL, engine, and landing gear when the vehicle has gear.

Ground vehicles send aircraftData = false so the car HUD returns. Theme accents on the aircraft UI follow Config.ThemeColor.

Waypoint distance

While the vehicle HUD is visible and a GPS waypoint is set, a distance chip appears above the minimap (markerDist). Units follow Config.SpeedUnit (mil for MPH, km for KMH). The native GTA satnav distance under the radar is disabled.

Exports

Export	Description
VehicleShow()	Force the speedometer on (bypasses driver seat check)
VehicleHide()	Force the speedometer off
VehicleToggle()	Toggle forced visibility
SetSeatbelt(state)	Set seatbelt buckled (true / false)
GetSeatbelt()	Returns current seatbelt state
SetVehicleOverride(field, value)	Override a field (fuel, checkEngine, engineRunning, seatbelt, speed, rpm, or visibility fields). Pass nil as value to clear one override
ClearVehicleOverrides()	Clear all vehicle overrides
SetNitroVisible(visible)	Show or hide nitro UI
SetNitroLevel(level)	Nitro level (0–1)
SetNitroBurst(burst)	Burst level (0–1)
SetNitroFlowRate(flowRate)	Flow rate (0–1)
SetNitroBurstHit(burstHit)	Burst-hit indicator

exports["prp-hud"]:SetSeatbelt(false)

exports["prp-hud"]:SetVehicleOverride("fuel", 0.25)
exports["prp-hud"]:SetVehicleOverride("fuel", nil)

exports["prp-hud"]:SetNitroVisible(true)
exports["prp-hud"]:SetNitroLevel(0.8)