Documentation
Everything in Interface: the first-time setup, the F9 HUD editor, status HUD, speedometer, minimap and compass, seatbelt, stress, the roleplay chat, chat admin panel and VIP tags.
Interface replaces everything GTA draws over the game with widgets each player styles and places for themselves. The server decides what is allowed; the player decides how it looks.
Widget | Shows | Styles |
|---|---|---|
Status HUD | Health, armour, hunger, thirst, voice, stress, oxygen and stamina. | 22 |
Vehicle HUD | Speed, RPM, gear, fuel, engine health and seatbelt; the Dashboard style adds lights, high beams, engine and lock. | 11 |
Minimap | Circle or square, framed by a border theme. | 2 shapes · 11 borders |
Compass | Heading, street and zone, top centre, while driving. | 7, including Off |
Info displayer | Server ID, cash, bank, job and players online. | 13 |
Weapon HUD | The weapon's picture, ammo in the clip and in reserve. | 11 |
Notifications | Messages from Interface and from any script using its export. | 10 |
Progress bar | Timed actions, with animations and props. | 11 |
Chat | Roleplay chat with commands, tabs, VIP tags and 3D bubbles over players' heads. | 11 · 8 bubble styles |
Every player's layout is saved in their own game client, not on the server. Two players on the same server can have completely different HUDs.
The first time a player loads a character, a welcome screen with music opens instead of the HUD and walks them through it, one choice per screen:
The accent colour, then the status HUD style.
A style for each, then the info displayer and the weapon HUD.
The vehicle HUD, then the chat: style, bubble style, font, size, position, timestamps and tabs.
Every widget on a sample background, ready to drag into place. ESC goes back, Enter finishes after a confirmation.
Three settings change this flow:
Setting | Effect |
|---|---|
|
|
| Forgets the saved HUD on every login so the setup always runs — for showcase servers. Also enabled with |
| The image behind the preview step. |
The music is picked at random from Config.Music and played at Config.MusicVolume (0.0–1.0). Four tracks ship in web/music/: action-stylish (on by default), metal-dark, powerful-epic and steel-bars.
F9 (or Config.MenuKeybind) opens the editor at any time. The minimap and every widget come on screen so they can be moved, and a slow cinematic camera circles the player (Config.EnableCinematicMode). Drag any widget to move it; ESC closes the editor and saves everything.
Tab | What you set there |
|---|---|
Hud | Style, row or column layout, scale (0.5–2), and a switch per status to hide the ones you never want. |
Notifications | Style, text alignment and scale. A sample notification shows while you choose. |
Displayers | Info displayer style, weapon HUD style, scale, and which fields show: ID, cash, bank, job, players online, weapon. |
Progress | Style and scale, with a looping sample. |
Car Hud | Speedometer style, scale, minimap shape, compass and map border. |
Theme | The accent colour used by every widget. |
Chat | Style, bubble style, font, font size, input style, scale, opacity, fade time, width, maximum messages, position (3×3 grid), timestamps and tabs — with a live preview. |
Settings | Guide grid, presets, sharing a design, and resetting positions. |
Six presets apply a complete look in one click — layout, every style, colour and chat: Clean, Dashboard, Minimal, Cyber, Racing and Tactical.
Share design → Copy code turns the whole HUD — colour, styles, scales and positions — into a code starting with QSUI1:. Another player pastes it under Import a design and presses Apply code. It is the easiest way to give a whole community the server's official look.
The guide grid (small, medium or large) is drawn only while the editor is open, to line widgets up.
Config.ConfigurationMenu = false removes the editor and its key entirely; players keep whatever they chose in the first-time setup.
Health and armour come from the game; hunger and thirst from esx_status on ESX or player metadata on QBCore; stamina and oxygen from the player; voice from your voice resource — its ring grows with the current voice range.
The 22 styles: Hexagon (default), Dashboard, Basic, Modern, Diamond, Skew, Circle, Icon + Percentage, Pill, Neon Ring, Shield, Wave, Arc, Minimal Bar, Octagon, Rounded Square, Futuristic, Tech Ring, Blade, Reactor, Glitch Bar and Cyber. Dashboard is a wide panel docked under the minimap, sized to its width.
With auto-hide on, a status only appears when it needs attention: when it drops to its threshold or below — or, for stress, rises to it. Voice is never hidden, and everything shows while the editor is open.
Config.Optional.statusAutoHide = {
enabled = false, -- true = statuses only show when they need attention
thresholds = { -- a percentage, or false = always visible
health = 50,
armour = false,
hunger = 50,
thirst = 50,
stress = 50, -- shown at 50% stress or more
oxygen = 99, -- shown as soon as the player starts using air
stamina = 50,
}
}Getting into a vehicle brings up the speedometer, the minimap and the compass. The 11 speedometer styles: Advanced (default), Dashboard, Basic, Modern, Minimal, Racing, Cockpit, Futuristic, GT Race, Apex and Cyber. Speed is shown in Config.Units — kmh or mph.
Piece | Options |
|---|---|
Minimap shape | Square (default) or Circle — the game's minimap is reshaped with the textures in |
Map border | Holo (default), Dashboard, None, Futuristic, Neon, Minimal, Tactical, Chrome, Carbon, Overload, Cyber. Dashboard adds a row with the in-game clock, weather, wind and altitude. |
Compass | Arc (default), Ruler, Badge, Minimal, Cyber, Tactical, or Off. Shows the heading, the street and the zone. |
Config.HideRadar = true (the default) hides the minimap on foot. If the border frame does not sit exactly on the map at your players' resolution, adjust its position in Config.MapBorder, one entry per shape.
The info displayer shows the player's server ID, cash, bank, job and the number of players online out of sv_maxclients. Money is formatted with Config.Intl — locale and currency, e.g. de-DE with EUR.
The server can remove any field for everybody. A field switched off here is greyed out in the editor with "Disabled by the server configuration":
Config.Optional.display = {
id = true,
online = true,
job = true,
cash = true,
bank = true,
weapon = true,
}The weapon HUD appears while a weapon is drawn, with its picture and ammo. Pictures live in web/images/weapons/ and are matched through Config.WeaponIconByHash; an addon weapon with no entry shows a generic picture. To give one its own, add its hash and a picture name to that table.
Both are drawn by Interface for any script that calls them — see Commands and Exports. Notifications come in 10 styles (Modern, Basic, Classic, Minimal, Neon, Toast, Gradient, Banner, Futuristic, Cyber); the progress bar in 11 (Skew, Basic, Classic, Circle, Wave, Gradient, Minimal, Retro, Ring, Futuristic, Cyber).
A progress bar can play an animation or scenario, attach props every nearby player sees, and lock movement, sprint, driving, combat or the camera. It stops by itself if the player dies, ragdolls, falls, swims or is cuffed — unless the script allows it — and X cancels it when it is cancellable.
B buckles and unbuckles, with a notification and the seatbelt icon on the vehicle HUD. Motorcycles, bicycles and boats have no seatbelt. While buckled the player cannot leave the vehicle.
Without it, a hard crash above roughly 110 km/h can throw the player through the windscreen, hurting them in proportion to the speed. Heavy crashes also stall the engine. When InteractSound is installed, nearby players hear the buckle.
The stress system ships off (Config.Stress = false). Turned on, it rises from:
Speeding — above Config.MinimumSpeed (100) buckled, or Config.MinimumSpeedUnbuckled (50) without a seatbelt, checked every 10 seconds.
Shooting — each shot has a Config.StressChance (10%) chance to add some. Jerry cans, hazard cans and extinguishers never count (Config.WhitelistedWeaponStress).
Other scripts — through the same events qb-hud uses, see Integrations.
Jobs in Config.DisableJobsStress (police and ambulance by default) never gain it. From Config.MinimumStress (50) the screen blurs now and then — stronger and more often as it climbs (Config.Intensity, Config.EffectInterval) — and at 100 the player also stumbles and blacks out briefly.
Eating, drinking, healing and dying relieve it automatically on both frameworks. Stress is saved per character: in users.stress on ESX and in metadata on QBCore.
T opens the chat. Suggestions appear as you type a command, with its parameters; Tab completes, ↑ ↓ browse what you sent before, and Ctrl + Tab switches channel. The input has an emoji picker and two buttons that roll a die or play rock-paper-scissors. Messages support ^0–^9 colours, clickable links and @mentions, which play a sound to the person mentioned.
L cycles the chat between Show when active (it fades after a few seconds), Always visible and Hidden. The key is Config.ChatToggle — a default players can rebind in Settings → Key Bindings → FiveM; enabled = false removes it and keeps everyone on "Show when active".
Command | Who reads it |
|---|---|
| Players within 20 metres. |
| Players within 20 metres. |
| Everyone — or only players nearby with OOC proximity on. |
| Everyone except police, signed ANONYMOUS. Police jobs ( |
| Only that player. |
| Every admin online, plus a copy for the sender. Renamed or removed with |
| Admins only can send it; everyone sees it as an admin message. |
Dice · Rock-paper-scissors | Buttons in the chat input; the result goes to players within 20 metres. |
Job channels | Commands you create in the admin panel, read only by one job from a minimum grade. |
Typing without a command is blocked by default — Config.EnablePlainGlobalChat or the admin panel's Plain global chat switch turns it into a global message. Config.EnableChat = false switches the chat off entirely.
Flood protection (Config.FloodProtection): more than 12 messages in 10 seconds blocks the player for 5; messages under 200 ms apart are dropped; a warning comes at 4. Admins are exempt, and exemptCommands lists commands it ignores.
Word filter (Config.Badwords): a blocked word is replaced by * characters. It sees through repeated letters ("fuuuck") and leetspeak ("5h1t"), and can warn the sender.
Messages can float above the speaker's head for nearby players — up to four stacked, shrinking and fading with distance. They ship off. Switch them on in Config.DrawText3D — that is where every player's game reads the timing, range and size — and then pick the commands and the cooldown in the admin panel's 3D Bubbles tab:
Config.Bubbles3D = true -- false removes the feature and its options everywhere
Config.DrawText3D = {
enabled = false, -- bubbles on or off
commands = { 'me', 'do' },
displayTime = 10000, -- ms
cooldown = 1500, -- ms between bubbles per player
maxRange = 20.0,
showInChat = true, -- also print the message in the chat
}Each player picks the bubble look in the editor: Classic, Stripe, Legend, Minimal, Outline, Futuristic, Cyber or Racing.
/chatadmin opens it for admins. Everything here is saved to the database and applied to every player at once — no restart.
Tab | What it holds |
|---|---|
Commands | Enable or disable /me, /do, /ooc, /anon, /a, /report, dice, rock-paper-scissors and /pm, and give each a colour and icon. |
Bad Words | The filter switch, warn sender, leetspeak detection, the replacement character and the word list. |
3D Bubbles | Which commands show bubbles, time, cooldown, range, scale and opacity. Hidden when |
Job Channels | Private channels per job: a command (e.g. |
Category Tabs | The tabs under the chat input — ME, DO, OOC, ANON, PM — with their names and colours, or none at all. |
VIP Tags | Grant, edit and remove VIP tags, online or offline, and filter the list by tier and status. |
Actions | Plain global chat, OOC proximity, clear the chat for everyone, and send an announcement. |
Every save, clear and announcement is logged to Discord when a webhook is set.
A VIP tag puts a badge before the player's name and colours it, in the chat and in their 3D bubbles. Tags belong to the Rockstar license, so they follow the player across characters.
Tier | Look |
|---|---|
| Gold, still. |
| Cyan to blue, shimmering. |
| Purple, pulsing. |
| Gold and orange, moving gradient. |
| Red and gold, rainbow animation. |
Four ways to hand one out:
The VIP Tags tab of /chatadmin — search any character, online or not, and choose permanent or until a date.
/givevip <id> <tier> [days] in game or in the server console; no days means permanent.
/redeemvip <tbx-id> <tier> — the player redeems a Tebex purchase themselves. Each transaction works once.
Your own store or bot writes chat_vip_tags and calls refreshVip — see Integrations.
Expired tags are removed on their own. /removevip <id> takes one away.
Config.Theme sets the colours of the setup screens, the editor and the admin panel; mainColor is the accent every player starts with before picking their own. Pair it with your own preview background, music and an official QSUI1: design code to give new players the server's look from the first minute.
What | Where | Changed by |
|---|---|---|
HUD layout, styles, colour, chat look | The player's game client | Each player, in the setup and the editor |
Chat visibility (the L key) | The player's game client | Each player |
Commands, filter, bubbles, job channels, tabs |
| Admins, in /chatadmin |
VIP tags |
| Admins, commands, Tebex, your scripts |
Everything else |
| You, with a restart |
The word filter, plain global chat and OOC proximity in
config.luaonly seed the database on the first start; after that the admin panel is the source of truth. 3D bubbles are the exception:Config.DrawText3Dmust stay enabled in the file for players to see them at all.