Pepper HUD

Clean, modern HUD with 3 styles and an in-game editor – ESX & QBCore.

Overview

Pepper HUD shows everything players need – status, money, job, compass, ammo and a speedometer with seatbelt and cruise control. Every player sets it up with /hud: style (rings, bars, pills), colors, size, visible elements and position. Settings are saved locally per player, no database needed.

Features

• 3 switchable styles – rings, bars and pills
• In-game menu /hud with live preview: style, accent color, color mode, size, opacity, every element on/off
• Drag elements anywhere with the mouse, saved per player
• Health, armor, hunger, thirst, stamina, oxygen, voice chat (pma-voice and SaltyChat) including radio
• Cash, bank, black money (ESX) with plus/minus animation, job and grade, player ID, time
• Compass with street and area, ammo display
• Speedometer with RPM, gear, fuel, engine health, lights and lock state (km/h or mph)
• Seatbelt with ejection on crashes and cruise control
• Cinematic mode and square or round minimap
• Show-when-needed elements (e.g. armor only when you have some)
• Optional (from the next version, already in the code): weather and temperature with Pepper Weather, clothing cleanliness with Pepper Laundry
• Only sends changed values to the UI
• English and German; config, locales and framework bridge open

Requirements

Installation

1. Download the resource from the Cfx.re Portal (https://portal.cfx.re/assets/granted-assets).
2. Extract it to resources/[pepper]/pepper_hud. Do not rename the folder pepper_hud – escrow and the exports (exports.pepper_hud:…) depend on the name.
3. Start it in your server.cfg after your framework (and voice and fuel script, if any):

   ensure es_extended   # or qb-core
   ensure esx_status    # ESX only
   ensure pma-voice     # optional
   ensure pepper_hud
   

4. Disable other HUDs (esx_hud, qb-hud, ps-hud …), otherwise two HUDs overlap.
5. QBCore only: turn off seatbelt/cruise in qb-smallresources or set Config.Seatbelt.enabled / Config.Cruise.enabled to false.
6. English texts: set Config.Locale = 'en' in config/config.lua. There is no database and there are no items.

First test

1. Log in – status displays appear at the bottom, money, job, ID and time at the top right.
2. Type /hud: switch the style to bars and pick another accent color – the preview changes instantly.
3. Get into a car and press B (seatbelt click), then from 30 km/h press Y for cruise control; braking ends it.
4. Type /cinema – HUD and minimap disappear, black bars appear; /cinema again to leave.
5. After a reconnect your /hud settings are still there.

Configuration

These are server defaults – players can change much of it for themselves via /hud (saved locally on their PC, per server). New players start with Config.Defaults.

General

Commands and keys

Config.Commands = { menu = 'hud', cinema = 'cinema', seatbelt = 'seatbelt', cruise = 'cruise' }
Config.Keys = { seatbelt = 'B', cruise = 'Y', cinema = '' }

The keys are defaults; players change them under Settings → Key Bindings → FiveM.

Seatbelt and cruise control

Minimap, fuel and performance

Config.GetFuel = function(vehicle)
    local state = Entity(vehicle).state.fuel
    if type(state) == 'number' then return state end
    return GetVehicleFuelLevel(vehicle)
end

Menu rights and start values

Using it in game

In the menu's layout mode you drag elements anywhere with the mouse; Reset restores the default layout. The seatbelt does not apply to motorbikes, bicycles, boats, helicopters, planes and trains. Cruise control only works as the driver; braking, the handbrake or slowing down noticeably ends it.

Commands and permissions

There are no permissions (ACE/groups); what players may change is controlled with Config.Menu. Change the command names in Config.Commands.

Exports and events

All exports run on the client:

exports.pepper_hud:setVisible(false)
if exports.pepper_hud:isSeatbeltOn() then … end

FAQ

Two HUDs on screen – what now?

Disable other HUDs (esx_hud, qb-hud, ps-hud …) in your server.cfg. Only one HUD may run.

Two seatbelts or cruise controls (QBCore)?

Turn them off in qb-smallresources or set Config.Seatbelt.enabled / Config.Cruise.enabled to false.

Hunger and thirst stay empty (ESX)?

On ESX, Pepper HUD needs esx_status for hunger and thirst. Start it before pepper_hud.

Money, job and hunger are missing completely?

Then no framework was detected (the F8 console shows a hint). Start pepper_hud after es_extended or qb-core, or set Config.Framework to 'esx' or 'qbcore'.

Fuel always shows 0 or 100?

Adjust Config.GetFuel to your fuel script, e.g. return exports['LegacyFuel']:GetFuel(vehicle).

The minimap looks wrong?

Another script controls the minimap – set Config.Minimap.managed = false, then the HUD leaves it alone.

Players cannot change the style or colors?

Check Config.Menu (allowStyle, allowColors, allowLayout). Locked parts are always set to the defaults from Config.Defaults.

Where are player settings stored?

Locally on the player's PC (KVP), per server. No database is needed.

Which voice systems are supported?

pma-voice and SaltyChat – both are detected automatically (Config.Voice = 'auto'). 'none' hides the voice display.

How do I hide the HUD for my phone or camera script?

Call exports.pepper_hud:setVisible(false) on the client and setVisible(true) afterwards.

How do I change the colors for all new players?

Config.Defaults.accent and colorMode set the start values, Config.Colors the colors of the single displays, Config.AccentPresets the choices in the color picker. Players with their own settings keep their choice.

How do I connect my own status or money system?

The bridge files bridge/client/esx.lua and bridge/client/qbcore.lua are open. That is where the HUD reads money, job and status – adjust the events or lookups to your system.

How do I update Pepper HUD?

Download the new version from the Cfx.re Portal, back up config/config.lua and changed bridge or language files, then replace the folder. Player settings are kept. Changes are listed in the CHANGELOG.md in the resource folder.

Support

Questions or bugs? Open a ticket in our Discord: https://discord.gg/6NaFJWKDYu – link your purchase with /verify first.

Permanently tested on the Pepper Scripts dev server.

Changelog

Current version 1.0.0 (first version). In progress: optional weather display with Pepper Weather and clothing display with Pepper Laundry. All changes are listed in the CHANGELOG.md in the resource folder.

Found a mistake? Report it on Discord.