Installation Guide

Step-by-step setup for oxide-hud — prerequisites, downloading it free from the Cfx.re Portal, start order, removing your framework's HUD, optional resources, verification and updating.

Step-by-step setup for oxide-hud. Follow the steps in order — most issues come from skipping one.

Prerequisites

Required resources

Resource	Minimum version	Purpose
ox_lib	latest	Utility library
o-link	1.12.0	The bridge between Oxide HUD and your framework. It is where the HUD gets the character's needs, money, name and death state, and reads your fuel, seatbelt and voice resources

If you already run other Oxide resources, you already have both. Check that your o-link is up to date: open o-link/fxmanifest.lua and look at the version line.

o-link 1.12.0 is a hard requirement

On an older o-link, the HUD stays off on purpose and the console prints [oxide-hud] Oxide HUD needs o-link 1.12.0 or newer. See The HUD Never Shows.

Supported frameworks

Oxide HUD runs on QBCore, Qbox and ESX.

Framework	Support
QBCore	Full
Qbox (`qbx_core`)	Full
ESX	Full. Stock ESX has no stress and no "downed" state, so the stress block stays hidden and the HUD hides only when a player is fully dead
No framework	Works. There is no character, so the character name stays empty and cash and bank show 0

Oxide HUD has no database tables and nothing to import. Each player's layout is saved on their own computer.

Installation Steps

Download it

Oxide HUD is free. Once you have claimed it, it is listed in your assets on the Cfx.re Portal. Download oxide-hud from there.

Oxide HUD is protected (escrowed): it only starts on a server whose license key belongs to the same Cfx.re account that claimed it. config.lua and the translation files stay plain text, so you can still edit them.

Extract it into your resources

Open the zip and copy the oxide-hud folder into your server's resources folder. If you run several Oxide resources, keep them together in a folder named [oxide].

Check two things:

The folder is named exactly oxide-hud. Not oxide-hud-1.0.0 or anything else. o-link looks for this exact name, and players' saved layouts belong to it.
fxmanifest.lua sits directly inside it: resources/oxide-hud/fxmanifest.lua. Not resources/oxide-hud/oxide-hud/fxmanifest.lua.

Remove your framework's own HUD

QBCore ships qb-hud, Qbox ships qbx_hud and ESX ships esx_hud. If yours is running, both HUDs draw at the same time and overlap. Follow Removing Your Framework's HUD below.

Add it to your `server.cfg`

server.cfg is the text file that tells your server which resources to start. It is usually in your server data folder, next to the resources folder. Open it in a text editor (Notepad++ or VS Code work well) and add this line below ensure o-link, as shown in Start Order:

ensure oxide-hud

If your Oxide resources live in an [oxide] folder and your server.cfg already has ensure [oxide], you do not need a separate line.

Save and restart the whole server

Save every file you changed, then fully restart your server, not just the resource. Oxide HUD streams its own minimap files, and streamed files only load when the server starts.

Start Order

Every Oxide resource uses the same four-group order in server.cfg:

# 1. Framework, and everything it needs
ensure oxmysql
ensure ox_lib
ensure qb-core          # or qbx_core, or es_extended

# 2. Your other scripts (voice, fuel, seatbelt, inventory, phone...)
ensure pma-voice
ensure LegacyFuel

# 3. o-link, the bridge. Starts after your framework and scripts, before any Oxide resource.
ensure o-link

# 4. Oxide resources. Keep these together, ideally in a folder named [oxide].
ensure oxide-hud

Your server.cfg already has most of these lines. You only add ensure o-link (if it is not there yet) and ensure oxide-hud. There is no required order inside each group.

Why this order matters:

o-link must start before Oxide HUD. The HUD gets all of its game data through o-link.
o-link must start after your framework and your fuel script. o-link checks which framework and which fuel resource are running at the moment it starts. If they are not running yet, it cannot use them.
Do not put ensure oxide-hud near the top. Because Oxide HUD needs o-link, starting Oxide HUD also starts o-link straight away if it is not running yet. If ensure oxide-hud sits above your framework, o-link starts too early and cannot find your framework. The HUD then shows up before anyone picks a character, and the name, cash and bank stay empty.

Removing Your Framework's HUD

Only one HUD should run. Find your framework below and stop its HUD.

Framework	Stock HUD to remove
QBCore	`qb-hud`
Qbox	`qbx_hud`
ESX	`esx_hud`

Stress on QBCore and Qbox

qb-hud and qbx_hud also run their framework's stress system: they raise stress while a player speeds or shoots, blur the screen at high stress, and apply the stress changes other scripts send (for example relief from food, or stress from a robbery, through hud:server:GainStress and hud:server:RelieveStress). Oxide HUD shows stress but does not change it. Once the stock HUD is removed, stress stays where it is unless another resource on your server handles those changes.

Open your server.cfg and look for a line that starts the HUD, such as ensure qb-hud.

If you find one, put # at the start of the line so the server skips it:

# ensure qb-hud

Check whether a folder line starts it. Many servers start whole folders at once, with lines such as ensure [qb], ensure [qbx] or ensure [esx]. Every resource inside that folder starts, including the HUD, even with no line of its own. Open your resources folder and find the HUD's folder (for example resources/[qb]/qb-hud).

Move the HUD's folder out of your resources folder, for example to your desktop. Moving it keeps a copy in case you want it back, and the server can no longer start it.

Save server.cfg.

If you also run a third-party HUD, remove it the same way.

Optional Resources

None of these are required. When one is running, Oxide HUD uses it automatically.

Voice and radio

Resource	What it adds
pma-voice	Voice range bars, the talking light and the radio channel
SaltyChat (`saltychat`)	The same, read from SaltyChat

Without either, the voice indicator reads FiveM's built-in voice chat (one range, the talking light) and the radio never shows, because the built-in voice chat has no radio.

If both are installed, choose one in o-link's settings. See Choosing Seatbelt, Voice and Fuel Resources.

Seatbelt

The seatbelt warning light reads one of these:

qbx_seatbelt (Qbox)
qb-smallresources (QBCore)

Without one of them, nothing tells the HUD when the belt is on, so the light always shows the belt as off. If you do not use seatbelts on your server, leave seatbelt lamps out of your HUD. (The default layout has none.)

Fuel

The fuel gauge reads any of these fuel resources:

BigDaddy-Fuel
cdn-fuel
esx-sna-fuel
lc_fuel
LegacyFuel
okokGasStation
ox_fuel
ps-fuel
qb-fuel
qs-fuelstations
Renewed-Fuel
ti_fuel
x-fuel

Without one, the gauge shows GTA's own fuel level.

Your fuel resource must start before o-link (group 2 in Start Order). o-link only picks up a fuel resource that is already running when o-link starts.

Verification

Start your server. The server console should show Started resource oxide-hud, with no red error lines that mention oxide-hud.

Join and pick a character. The HUD appears once your character has loaded, not on the character select screen. With the default layout you should see:

a dark box with your street and area name in the bottom-left corner,
a compass at the top of the screen,
a voice indicator in the top-right corner, if voice chat is connected.

Check the status bars. Health, armour, hunger, thirst and the rest hide themselves while they are full or empty, so a healthy, fed character may see none. Sprint for a few seconds: stamina appears in the bottom-left corner. This is normal.

Get in a vehicle. A speedometer appears in the bottom-right corner (a different one in boats and aircraft), and the minimap appears. (The minimap only shows in a vehicle by default. Each player can change this in the editor.)

Type /hud in chat. The editor opens over a dark grid, with Add, Layers and Theme on the left, the Inspector on the right, and On Foot / In Vehicle and Done at the top. Click Done to leave it.

Open the pause menu. The HUD disappears, then comes back when you close the menu.

If something does not look right, see Troubleshooting.

Updating

Back up oxide-hud/config.lua if you changed it, and any translation files you added to oxide-hud/locales/.

Download the new version of oxide-hud from your assets on the Cfx.re Portal.

Replace your oxide-hud folder with the new one. Keep the folder name oxide-hud.

Re-apply your settings in the new config.lua. Do not copy the old file over it, in case the new version added options.

Copy your translation files back into locales/.

Restart your server.

Players keep their HUDs and saved layouts. They are saved on each player's computer, not inside the resource folder.