Configuration

Every setting lives in oxide-hud/config.lua. Open it in any text editor (Notepad++ or VS Code work well), change the values, and save.

Changes take effect after oxide-hud restarts. Type restart oxide-hud in your server console, or restart the server. Players keep their layouts.

All Settings

Speed Unit

The unit applies to every block showing the vehicle's speed or the odometer, the car and bike speedometers (Sweep, Ghost, Instrument, Rail and the classic set), and the MPH text label. Rings, bars and dials showing speed run to 200 mph, or 320 km/h. Boats and aircraft have their own units, below.

Config.SpeedUnit = 'kmh'  -- kilometres per hour

Boat and Aircraft Units

The boat speedometer (Helm) and the aircraft one (Glass), and every block showing boat or aircraft data, use these units. Each player sees the values in your server's units.

Config.Units = { water = 'kn', air = 'kn', altitude = 'ft', verticalSpeed = 'fpm', depth = 'm' }

A value that is not one of the choices uses the default. Rings, bars and scales run to 400 knots for aircraft (460 mph, 740 km/h), 60 knots on water (70 mph, 110 km/h), 6,000 feet per minute up and down (30 m/s), and 300 metres deep (1,000 feet).

Flight Warnings

Glass shows STALL and PULL UP in planes. GTA does not say when a plane stalls, so the HUD works both out from the plane's speed, angle and height. The defaults are cautious: they show only when the plane is in real trouble.

Config.Flight = {
    warnings = true,
    stallSpeed = 50,
    stallAngle = 18,
    minHeight = 20,
    pullUpSeconds = 4,
    pullUpHeight = 120,
}

Helicopters never show either warning.

Server Logo

The logo sits in the top-right corner. It is not part of a player's HUD: players cannot move it, and other resources' panels keep clear of it.

Using a web address

Config.ServerLogo = {
    enabled = true,
    image = 'https://example.com/images/logo.png',
    height = 48,
}

The address must start with https:// and link straight to the image file (it usually ends in .png, .jpg or .webp), not to a web page that shows it. Use a link that does not expire, such as an image on your own website: images hosted on imgur do not load in FiveM, and Discord attachment links stop working after about a day.

After changing config.lua, type restart oxide-hud in the server console. The logo appears in the top-right corner within a few seconds.

Using an image file

files {
    'locales/*.json',
    'web/dist/**',
    'logo.png',
}

Config.ServerLogo = {
    enabled = true,
    image = 'logo.png',
    height = 48,
}

If the image cannot be loaded, the logo does not appear, and the F8 console shows a line starting [oxide-hud] The server logo could not be loaded from with the address it tried. See Server Logo Does Not Show.

Default Layout

The default layout is the HUD that:

• every player who has never changed their HUD uses, including players who joined before you set it,
• Reset in the editor returns to,
• is listed as Default under Share > My layouts.

A player's HUD is only saved once they change something in the editor. Until then they follow your default, so changing the code changes their HUD too. Once they have changed it, it is their own and a new code no longer replaces it; they can switch to your default with Reset or Share > My layouts > Default, or you can put everyone on your layout with Locking the Editor.

To make one

Config.DefaultLayout = 'OXHUD1.eJy...'

If the code moves the minimap, players who never moved their minimap get its position too.

If the code cannot be read (it was cut short, made by a newer version of Oxide HUD, or is not an Oxide HUD code at all), players get Oxide HUD's own default instead and each player's F8 console shows one line starting [oxide-hud] Config.DefaultLayout cannot be used: with the reason. See The Default Layout Is Not Used.

Locking the Editor

With editing locked:

• /hud only shows Editing the HUD is turned off on this server. The editor does not open.
• Every player sees Config.DefaultLayout, or Oxide HUD's own default layout when that is empty, including its minimap position.
• Nothing a player saved is changed. Set it back to false and every player gets their own HUD back.

Config.DefaultLayout = 'OXHUD1.eJy...'
Config.LockEditing = true

Restart oxide-hud after changing it. Only true locks the editor.

Status Colours

Colours are hex codes, the same kind you use on websites ('#ff0000' is red). They are the Data color of each status value: every status block, in every style and template, uses them unless a colour is picked for it. Config.IconColors colours the icons. A player can still pick their own colour for one block in the editor (Colors in the inspector), or for every block showing that data (Theme > Data colors), and sees their own colour instead.

Config.Colors = {
    health = '#ef4444',
    armor = '#14b8a6',
    hunger = '#f59e0b',
    thirst = '#60a5fa',
    stress = '#e771f6',
    oxygen = '#bbbbbb',
    stamina = '#bbbbbb',
}

-- Lighter tints for the icons
Config.IconColors = {
    health = '#fecaca',
    armor = '#99f6e4',
    hunger = '#fde68a',
    thirst = '#bfdbfe',
    stress = '#ebbbff',
    oxygen = '#ffffff',
    stamina = '#ffffff',
}

Accent Colour

Oxide HUD uses your accent colour for:

• the editor: its buttons, highlights, the outline around each block and the boxes for other resources' panels;
• every part of a player's HUD set to Accent. In the templates that is the speed readouts and arcs, the fuel gauges while fuel is not low, the player ID badges and the accent lines of the speedometers.

Without an accent, those parts are Oxide red.

Colours that mean something keep their colour: the status values (set those in Status Colours), warnings such as low fuel, high revs and engine damage, and the seatbelt, lights, voice and money readouts. The Holo speedometer keeps its cyan.

A player can choose their own accent for their own HUD in the editor's Theme tab. It wins over yours unless you lock the accent.

You only set one colour. The HUD works out a lighter shade for text, a darker shade, and whether text drawn on top of the colour should be white or black. A very dark colour is lightened just enough to stay readable on the dark HUD.

Config.Theme = {
    accent = '#9b2c2c',
    lockAccent = false,
}

Restart oxide-hud after changing it. If the value is not a colour, your server console prints a line saying so and the HUD keeps its own colours.

Resources updated for Oxide HUD can use the same colour for their on-screen panels, such as notifications, the progress bar and job HUDs. Each of them has its own setting to keep its own colours instead.

Locking the Accent

Players can choose their own accent in the Theme tab, and pick their own colour for any part of a block (Colors in the inspector). By default their choices win over your accent.

Set lockAccent = true to keep your branding on every player's screen:

Config.Theme = {
    accent = '#9b2c2c',
    lockAccent = true,
}

With the accent locked:

• every part set to show the accent keeps your accent. A colour a player picked for such a part is ignored, and the editor offers no custom colour for it (No custom color: your server sets the accent.);
• a player's own accent, and their own colour for speed, fuel and the server ID (the data that uses the accent), are ignored. The Theme tab shows Your server sets the accent color. instead of the accent control;
• everything else is unchanged. Status values, warnings such as low fuel, cash, voice and every part not set to the accent still show the player's colours;
• players' choices are kept. Set lockAccent back to false and their colours come back.

lockAccent only works together with an accent. Only true locks it; any other value, or leaving the line out, leaves it unlocked. Restart oxide-hud after changing it.

Auto-Hide

Each status block hides itself while there is nothing worth showing. These numbers decide when, for every status block that still follows your config. Every value runs from 0 to 100.

To make a status value always visible, set a number it can never reach:

Config.AutoHide = {
    health = 101,   -- always show health (full health is 100)
    armor = -1,     -- always show armour, even at 0
    hunger = 101,   -- always show hunger
    thirst = 101,   -- always show thirst
    stress = -1,    -- always show stress, even at 0
    oxygen = 100,   -- oxygen only ever shows underwater
    stamina = 5,
}

These are the starting point. A player can change when any block hides in its Rules (see Rules). A block whose rule they changed keeps their choice; every other block follows your config, including after you change it.

Inside the editor, every block is shown regardless, so players can place them.

Editor

Config.DefaultGridSize = 50
Config.EditCommand = 'hud'   -- players type /hud

Reserved Areas

Oxide HUD knows where its own blocks, the minimap and the logo are, and places other resources' panels clear of them. It cannot see things drawn by other scripts. List those here, and panels are placed clear of them too.

Each entry has:

All four numbers are in vh: percent of the screen height. 10 is a tenth of the screen height at any resolution. On a 1080p screen, 1 vh is about 11 pixels, so a 400 x 300 pixel chat box is about 37 x 28 vh. A normal widescreen monitor is about 178 vh wide and 100 vh tall.

For the top, bottom and center anchors, x is measured from the middle of the screen (positive is to the right). For left, right and center, y is measured from the middle (positive is down).

Config.ReservedAreas = {
    -- A chat box in the top-left corner, from a chat resource that does not support Oxide HUD
    { id = 'chat', anchor = 'top-left', x = 0, y = 0, w = 60, h = 30 },
    -- A third-party display in the bottom-right corner
    { id = 'corner', anchor = 'bottom-right', x = 2, y = 2, w = 30, h = 20 },
}

What reserved areas do and do not do:

• They only move other resources' panels. They never move the HUD's own blocks.
• A panel a player has dragged somewhere in the editor stays where they put it.
• An entry with a width or height of 0 (or missing) is ignored.

Update Intervals

How often Oxide HUD reads each kind of data, in milliseconds (1000 = one second). Lower numbers make the HUD react faster but do a little more work. Higher numbers are lighter but slower to update. The defaults suit most servers.

Config.Intervals = {
    status = 200,
    death = 1000,
    vehicle = 100,
    fuel = 1000,
    vehicleIdle = 500,
    location = 1000,
    voice = 200,
    nui = 200,
    flight = 100,
    idle = 1000,
}

Translations

Every text in the editor and on the HUD lives in oxide-hud/locales/en.json: the editor's buttons and tabs, the names of the data, styles, options and templates, HUD labels such as CH and MPH, compass points and weapon names.

To add a language:

"reset": "Zurücksetzen",

setr ox:locale de

Good to know:

• Anything missing from your file shows in English. Oxide HUD never shows raw text keys.
• If the file has a mistake that breaks it (a missing comma or quote, for example), the whole HUD falls back to English. Check the file with any online JSON checker.
• Street and area names come from GTA itself and follow each player's game language.
• Text a player typed into their HUD, such as a label or the word on a warning lamp, stays as they typed it. The words on the built-in speedometer templates (SEATBELT, STALL, PULL UP, ANCHOR, BELOW DESIGN DEPTH, GEAR, THR) are typed text of this kind: players can change them in the editor, or you can give everyone translated ones through Config.DefaultLayout.
• Updating oxide-hud may add new lines to en.json. Compare your file with the new one after an update.

Choosing Seatbelt, Voice and Fuel Resources

Oxide HUD reads the seatbelt, voice and fuel through o-link, and o-link picks the resource for each by itself. You only need to step in when it picks the wrong one: for example when two seatbelt resources, two voice resources or two fuel resources are installed.

The choice is made in o-link's settings file, not in Oxide HUD's.

Seatbelt          = 'qbx_seatbelt',
Voice             = 'pma-voice',
Fuel              = 'LegacyFuel',

The values you can use:

Upper and lower case do not matter in these values.

The same block also has a Hud line. Leave it switched off: o-link finds Oxide HUD by itself.

What Players Set Themselves

Each player's HUD, theme, saved layouts and templates, the grid size after they change it, and the minimap's Hide on foot are chosen by each player in the editor and saved on their own computer. You choose what new players start with (Config.DefaultLayout) and whether the editor opens at all (Config.LockEditing), but you cannot change a player's own saved HUD. See What Each Player Keeps.

Next Steps