Features

What Oxide HUD does, from a server owner's and a player's point of view. For the settings behind it, see Configuration.

The Default Layout

A player who has never changed their HUD gets this layout:

The speedometer changes with the kind of vehicle:

From there, every player can change their own HUD with /hud. You can give every new player a different starting HUD with Config.DefaultLayout (see Your Server's Default HUD).

How a HUD Is Built

Blocks: Data and Style

Every piece of the HUD is a block: one piece of data shown in one style. "Hunger as a bar", "Speed as a dial" and "Cash as a value in a pill" are all blocks.

A player adds a block in two steps: first they pick what to show (the data), then how it looks (the style). Both can be changed later, and each style has its own options: size, colours, icon, label, thresholds and more.

Each mode can hold up to 100 blocks.

The Data

Some data only shows when it makes sense, in game (the editor always shows it so it can be placed):

• vehicle data and lamps only in a vehicle, and only in the kinds of vehicle they belong to: aircraft data in helicopters and planes, boat data in boats and submarines, the lean angle on motorcycles and bicycles, the rotors in helicopters, the landing gear only on aircraft that have one, the stall and pull up warnings in planes, the anchor on boats (not jet skis), the depth in submarines, the wind in boats, aircraft and surfaced submarines;
• a bicycle has no RPM, gear, fuel or engine, and only cars warn about the seatbelt;
• oxygen only underwater, stamina only on land;
• weapon data only while a weapon is in hand;
• the radio only on a radio channel or while transmitting;
• voice only while voice chat is connected;
• street, cross street and area only when GTA has a name for them.

The Styles

Groups

A group holds blocks (and other groups). There are two kinds:

• Free groups keep each block where the player put it. The blocks move, lock and hide together.
• Placing groups lay their blocks out for you: in a Row, a Column, a Grid, a Honeycomb, Rings inside rings or Stacked on top of each other. They can draw a frame behind their blocks (card, panel, glass, hologram, strip, tag, a dashboard plate, or a soft shadow with no edges) and Close gaps when a block in them hides.

In game, a group hides completely while every piece of data in it is hidden, so an unarmed weapon panel or a status card with every bar hidden leaves nothing behind.

Templates

Templates are ready-made groups. There are 42 of them:

The car and bike speedometers:

• Sweep (the default) — a 72-cell rev ring with a fixed red zone, lit cells that flash at the shift point, one big number, the gear in a hexagon in the accent colour (Oxide red unless your server sets one), fuel and engine at the foot, and a lean angle scale on motorcycles and bicycles.
• Ghost — the number, the gear and a thin rev line. Fuel (at 20% and under) and an unbuckled seatbelt appear as warning chips only when they matter.
• Instrument — a dashboard plate with a row of warning lamps (turn signals, headlights, high beams, handbrake, seatbelt, check engine, doors, siren, trailer), a rev ring around the gear, the speed, fuel and engine cells and the odometer.
• Rail — for racing: a rising shift light strip over a large italic speed, the gear in a block in the accent colour, fuel and engine, all on one slant.

The Classic set holds eleven more speedometers in older styles, folded away at the bottom of the gallery.

The words on the warning chips (SEATBELT, STALL, PULL UP, ANCHOR, BELOW DESIGN DEPTH, GEAR, THR) are plain text: select the lamp or text in the editor to change them.

Adding a template adds the player's own copy. They can change it freely, or break it apart into separate blocks. The built-in templates themselves never change. Groups a player receives as a share code are kept as their own templates, under Yours.

Rules: When a Block Hides or Warns

Every block that shows a percentage or a number has rules:

• Hide — Above or Below a value, or Never. Hunger hides above 80 by default, so the bar only appears once the character gets hungry.
• Warning at and Critical at — the values where the block turns amber, then red (when its colour mode is Warning colors). Each can be turned off.
• Pulse — Off, From warning or At critical: the block pulses while it is at that level.

The status rules start from Config.AutoHide on your server (see Auto-Hide). A block keeps following your config until the player changes that rule on it.

Stress, stamina and RPM are bad when high, so they warn going up. Everything else warns going down. Status blocks pulse once they are critical.

Colours

Every colour in a block is either a token or a colour the player picked:

• Data color — the colour of that data: health red, armour teal, cash green and so on. Status colours come from Config.Colors and Config.IconColors.
• Accent — the player's own accent if they picked one (unless your server locks the accent), otherwise your server's accent (Config.Theme.accent), otherwise Oxide red.
• Warning, Critical and Text — amber, red and white.

A block takes the colour set on it, then the colour set on its group, then its style's own. Anything still on a token changes with the theme: a server accent, a player's accent, or a code imported on another server recolours every part that uses it.

Server Logo

You can show your server's logo in the top-right corner of every player's screen. It is off by default. Turn it on and choose the image in Config.ServerLogo (see Configuration).

The logo is not a block: players cannot move or remove it in the editor. It hides together with the rest of the HUD, and other resources' panels keep clear of it.

The Editor

Every player builds their own HUD with the editor. It changes only their own screen, never anyone else's.

Opening and Closing

/hud only works once the HUD has loaded for your character. If your server set Config.LockEditing, /hud only shows Editing the HUD is turned off on this server.

The Screen

• Top-left bar — On Foot / In Vehicle (which layout you are editing), the vehicle type menu beside In Vehicle (see Vehicle Types), Undo, Redo, the grid button (show the grid and pick its size: 10, 20, 25, 50 or 100 pixels), the snap switch, and the sample data menu (see Sample Data).
• Top-right bar — Templates, Share, the ... menu (keyboard shortcuts, hide panels, undo everything since opening, reset this layout) and Done.
• Left panel — three tabs: Add, Layers and Theme.
• Right panel — the Inspector, which shows everything that can change about what you selected.

The panels never fade and stop two thirds of the way down the screen, so the minimap, status and speedometer stay in view. Press H to hide them and see the HUD clean. Each panel folds to its header with the arrow in its corner.

Adding a Block

The new block appears in the middle of the screen, in the mode you are editing, and is selected so you can change it straight away.

Adding a Template

Click Templates in the top bar, or Start from a template at the top of the Add tab. The gallery shows every template drawn live, by family, with the player's own templates under Yours and the Classic set folded away at the bottom. Pick one, look at the preview, and click Add to On Foot (or In Vehicle, or the vehicle type you are editing, such as Add to Air).

When you add a speedometer to a vehicle type, Hide the other speedometers here (on by default) hides the speedometers that type was showing from All vehicles, in the same undo step. They stay everywhere else. The gallery opens on the speedometers for the vehicle type you are editing.

Selecting and Moving

• Click a block or group to select it. Shift + click adds to or takes from the selection.
• Drag on empty space to draw a box: everything inside it is selected.
• Double click a group to pick one block inside it.
• Drag to move everything selected. While you drag, edges and centres snap to other blocks, and to the grid while it is shown; a guide line shows where. Hold Alt to drag without snapping.
• Resize with the handle on the bottom-right corner, or with Size in the inspector.
• Arrow keys move the selection 1 pixel, or 10 pixels with Shift.

When you drop something, it is pinned to the part of the screen it is in. The screen is split into thirds across and down: a block dropped in the bottom-right third stays in the bottom-right corner, one dropped in the top-middle stays centred at the top, and so on. That is what keeps a layout in place on other screen sizes (see Every Resolution).

With several things selected, the inspector offers Align (left, centre, right, top, middle, bottom edges), Group, Duplicate and Delete, and with three or more, Space across and Space down.

The Inspector

The inspector shows what you selected, in sections. Only the options that apply are shown, and every option has Back to default.

A group's inspector has its layout, gap, alignment, frame, Close gaps, its colours (used by the blocks inside unless they set their own) and its outline colour in the editor.

Grouping and Breaking Apart

• Group — select two or more things and press Ctrl+G, or click Group in the inspector. The new group is free: everything stays where it is.
• Change the layout — in the group's inspector, pick Row, Column and so on to have the group place its blocks. Going back to Free keeps each block where it is drawn.
• Ungroup — select a group and press Ctrl+Shift+G, or click Ungroup. Its blocks stay where they are on screen.
• Take out of the group — select one block inside a group and click Take out of the group.
• Break apart — a group added from a template shows Break apart, which turns it into separate blocks you can change one by one.

Layers

The Layers tab lists everything in the mode you are editing, front to back:

• Groups fold open to show what is inside them.
• Eye — hide something while you edit and in game, without deleting it.
• Lock — stop something being moved, resized or deleted by accident.
• Drag a row to change what draws on top, or to move a block into or out of a group.
• Double click a name to rename it.
• The count at the top shows how many blocks this mode holds, out of 100.
• Not shown here lists everything that does not show in the mode or vehicle type you are editing. Show here adds it.

Below them are the Minimap and Other resources (see Other Resources' Panels).

The Theme Tab

The Theme tab holds the player's own colours, for their own HUD only:

• Accent — the colour of every part set to Accent. It shows where the colour comes from now: Your color, The server's accent or Oxide red.
• Data colors — one colour per piece of data, used by every part set to Data color. A colour picked on a part still wins.

Every change recolours the HUD live and can be undone. If your server locks its accent (Config.Theme.lockAccent), the accent control is replaced by Your server sets the accent color., and the data that uses the accent (speed, fuel and server ID) shows a lock.

Undo and Redo

Ctrl+Z undoes and Ctrl+Y (or Ctrl+Shift+Z) redoes, up to 50 steps, including deleting and grouping. The history starts again each time the editor opens. Undo everything since opening in the ... menu puts the HUD back to how it was when you opened the editor (the minimap and other resources' panels stay where they are). Changes are saved as you go.

Keyboard Shortcuts

Shortcuts do nothing while you type in a text box, so typing a name never moves or deletes anything. The list is also in the ... menu, under Keyboard shortcuts.

Sample Data

The sample data menu in the top bar chooses what the HUD shows while you edit: Live (your character right now), Normal, Low needs, Underwater, Armed, On the radio, Driving, Riding a motorcycle, Cycling, Boating, In a submarine, Helicopter, Flying a plane or Landing a plane. Use it to see how a block looks when it warns, or to place weapon and radio blocks without a weapon or radio. In the editor every block shows, whatever its rules. While Live or Driving is picked, switching to a vehicle type picks that type's sample (Boating for Boat, and so on), and going back puts your choice back.

On Foot and In Vehicle

Every player has two modes: one for walking around and one for driving. The HUD switches between them by itself when the player gets in or out of a vehicle.

There is one list of blocks for both modes. Each block has its own place in each mode, or is not shown in a mode at all (Show in the inspector). Changing a block's look changes it in both modes; moving it only moves it in the mode you are editing. The editor opens on the mode that matches where you are.

Vehicle Types

In a vehicle, the HUD knows what kind of vehicle the player is in: a car (quad bikes and trains count as cars), a motorcycle or bicycle, a boat (jet skis, and amphibious vehicles while they float), a submarine, a helicopter or a plane. The Deluxo and the Oppressor count as the car and motorcycle they are, even while flying.

The menu beside In Vehicle picks which layout you are editing: All vehicles, Car, Bike, Boat (with Submarine under it) and Air (with Helicopter and Plane under it). The bar then reads, for example, In Vehicle · Air.

• Each vehicle type follows the one above it: Submarine follows Boat, Helicopter and Plane follow Air, and Car, Bike, Boat and Air follow All vehicles. A block placed in All vehicles shows in every vehicle until a type gives it its own spot or hides it.
• Select a block that follows: the inspector says Follows All vehicles (or the type it follows), and Layers marks it with a link. Hide here hides it in this type and the types under it; Follow puts it back. Moving it gives this type its own spot, and the other types keep theirs.
• What you add while editing a type shows only in that type and the types under it.
• Reset this layout in a type puts that type and the ones under it back to the default HUD.

The Minimap

• In the editor, the minimap has its own box. Drag it to move the minimap. Its position is saved separately for each mode.
• Select it to find Hide on foot, which shows the minimap only while in a vehicle. It is on by default. Each player chooses this for themselves.
• Put back in the corner returns it to where the default layout has it.

Saved Layouts

Click Share, then My layouts:

• Save — type a name and click Save. It keeps the whole HUD, the minimap position in each mode and the grid size. Saving under a name you already used replaces it (Replace).
• Use — switch to a saved layout. It can be undone.
• Delete — remove one of your layouts.

Default is always at the top: your server's default HUD, or Oxide HUD's own. Built-in names cannot be used for your own layouts.

Share Codes

A share code is a line of text that holds a HUD, so players can trade designs in Discord or anywhere else.

To share:

To use a code:

Codes are checked before anything is saved. A code that is damaged, made by a newer version, over 20,000 characters, holding more than 100 blocks in one mode, nesting groups too deeply, or containing any web address or image path is refused with a message saying why. Parts this HUD does not know are left out and counted.

The same check applies to what a player typed: a code whose text blocks, labels or names contain a web address or a file name (such as https://discord.gg/... or logo.png) can be copied, but is refused wherever it is used, including as Config.DefaultLayout. Remove it before copying the code.

Codes never touch your server: nothing is uploaded or stored anywhere but the player's own computer.

Reset

Reset this layout in the ... menu puts the mode or vehicle type you are editing back to the default HUD (your server's, if you set one). Resetting On Foot or In Vehicle also puts other resources' panels back where they place themselves and moves the minimap to where the default HUD has it; resetting one vehicle type leaves them where they are. The other mode is not touched. The HUD part of a reset can be undone.

Your Server's Default HUD

You can design a HUD in the editor and make it the HUD every new player starts with:

Every player who has never changed their HUD uses it, including players who joined before you set it, and it changes for them whenever you change the code. Reset returns to it, and it is listed as Default under My layouts. If the code moves the minimap, players who never moved theirs get its position too.

Once a player changes their HUD in the editor, it is their own: a new code no longer replaces it. They can switch to your default at any time with Reset or Share > My layouts > Default, or you can put everyone on it with Config.LockEditing.

To give everyone the same HUD and turn the editor off, also set Config.LockEditing = true (see Locking the Editor).

Every Resolution

Layouts are measured in screen heights, not pixels, and each block is pinned to an edge or corner. So:

• A layout made at 1920x1080 looks the same at 2560x1440 or 3840x2160: every block keeps its place and its share of the screen.
• On a wider screen (for example an ultrawide), blocks pinned to the left and right stay at the edges, and centred blocks stay centred.
• A block that would not fit on a smaller screen is pulled back onto the screen. Its saved position is kept, so it returns to its exact spot on the original screen.

The editor's panels grow with the screen as well, and never get smaller than at 1080p.

When the HUD Hides

The HUD hides itself, and shows again on its own, when:

Typing in chat, or a remote you use while driving, does not hide the HUD when that resource supports Oxide HUD.

While the HUD is hidden, GTA's own street and area names come back.

The editor is the one exception: the HUD stays on screen while the editor is open.

Other Resources' Panels

Oxide HUD is also the place other resources put their on-screen panels: a notification area, a progress bar, a job's stage header, a timer card. Resources that support it (through o-link) hand their panel's size and preferred corner to the HUD, and the HUD:

• places the panel clear of its own blocks, the minimap, the server logo, the areas you list in Config.ReservedAreas, and the panels placed before it,
• keeps it still when a block hides: every block and group keeps its full space, so panels do not jump each time a status bar hides,
• shows a placeholder for the panel in the editor (a dashed box, purple or in your server's accent colour, with the panel's name and the resource's name), so players can drag it somewhere else, separately on foot and in a vehicle. Resources that support it draw their real panel inside it with sample content, and it moves with the box while the player drags,
• tells the resource where the panel goes and when the HUD hides, so the panel can hide with it.

In the Layers tab, Other resources lists the panels by resource:

• Eye — hide a panel, or every panel of a resource, while you edit. Use it when panels sit on top of each other, such as a downed card and a progress bar. It only affects the editor and is remembered for next time.
• Solo — show only that resource's panels while you edit. Click it again, or close the editor, to show everything.
• Show in game (in the inspector, with the panel selected) — switch a panel off for play. It stays off until switched back on, in both modes, and other panels may move into the space it used. A switched-off panel shows as a faded placeholder marked Hidden in game. Panels a resource needs to work, such as notifications, the progress bar and the downed card, cannot be switched off; their switch is greyed out, with Shows information you must not miss underneath.

Short-lived panels, such as a prompt or a progress bar, keep clear of the HUD but may sit on top of other panels.

When a side of the screen is full, a panel is never pushed onto your speedometer, minimap or compass, and never pushed to the far edge of the screen. It stays on its own half of the screen, clear of the HUD, where it covers the least of the other panels, and it covers notifications, alerts and other panels a player must not miss only when there is no other way. Panels in the same corner always line up in the same order, whatever order the resources start in.

Cards that rise from the bottom of the screen, such as the phone's call and message card, stay against the bottom edge, as they do without Oxide HUD. When something of the HUD is drawn in that corner, such as the speedometer in a vehicle or a weapon panel while a weapon is out, they sit directly on top of it and never cover it.

Panels that never show at the same time, such as the stage cards of different jobs, share one spot instead of stacking down the screen. In the editor that spot shows one of them at a time; the arrows on its placeholder switch between them, and moving one moves them all.

Decor blocks (panels, lines, brackets) do not push panels away, so a background behind your HUD does not block a whole corner.

If you run another HUD element that Oxide HUD cannot see, such as a chat box from a chat resource that does not support Oxide HUD or a third-party corner display, reserve its space in Config.ReservedAreas (see Reserved Areas).

Developers can find how to register a panel in the API Reference.

Where the Data Comes From

A need your framework does not track reads as full (stress as none), so its block stays hidden unless a player sets its Hide rule to Never. Stock ESX has no stress unless a script registers an esx_status called stress, and a server without a needs system has no hunger or thirst. The odometer counts the distance driven in each vehicle during the current session; it starts again at 0 after reconnecting. Speed and the odometer follow Config.SpeedUnit; boats and aircraft follow Config.Units (knots, feet, feet per minute and depth in metres by default). Street and area names come from GTA itself, in the player's game language.

GTA does not model wind on aircraft, so airspeed is the speed along the nose and ground speed the speed over the ground. Height above ground reads 0 when the aircraft is parked.

What Each Player Keeps

These are saved on each player's own computer. Nothing is stored in your database:

• their HUD, with every block, group, rule and colour, in both modes,
• their theme (accent and data colours),
• their saved layouts and their own templates,
• the editor grid size (after they first change it; until then they start with Config.DefaultGridSize),
• Hide on foot for the minimap, and the minimap's position in each mode,
• where they moved other resources' panels, and which ones they hid in the editor or switched off in game.

You choose what new players start with (Config.DefaultLayout) and can turn editing off (Config.LockEditing), but you cannot change a player's own saved HUD.

Next Steps