HUD Customization
📄 Config file: shared/general.lua (Config.HUD)
The mechanic HUD, mileage, gear indicator, nitro gauge, seatbelt icon, and TCS/ESC indicator, is fully customizable in-game. Admins set the default layout everyone starts with, and each player can then move and restyle it to their own taste.
Which Elements Exist
Config.HUD = {
Mileage = true, -- Odometer / speed readout
Gears = true, -- Manual transmission gear indicator
Nitro = true, -- Nitrous level counter
Seatbelt = true, -- Seatbelt / harness indicator
Electronics = true, -- TCS & ESC status indicator
}These are global on/off switches. Turning one off removes it for everyone, and players cannot bring it back from the HUD editor.
Seatbelt also needs Config.EnableSeatbelt, and Electronics also needs Config.Electronics.Enable. If the system itself is off, the HUD element never shows.
For Players, /mechanic_settings
Any player can run /mechanic_settings to open the HUD editor. While it's open they can:
| Control | What it does |
|---|---|
| Drag | Move any element anywhere on screen. Positions hold up across different resolutions. |
| Scale | Make the element bigger or smaller. |
| Background | Show or hide the element's background panel. |
| Colours | Change the background colour and the text/icon accent colour. |
| Opacity | Make the background more or less transparent. |
| Visibility | Hide an individual element for themselves only. |
Clicking Save closes the editor and keeps the layout.
/mechanic_reset_hud wipes a player's own customization and puts them back on the server default layout.
For Admins, /mechanic_admin_hud
Admins run /mechanic_admin_hud to set the server-wide default layout, what every player sees before they change anything, and what /mechanic_reset_hud restores to.
The editor looks the same, but saving stores it as the server default instead of your personal layout.
Once a player has customized an element themselves, that element stays theirs, a new server default won't override it until they run /mechanic_reset_hud. Elements they never touched keep following the server default, so you can reposition the gear indicator without disturbing a player's carefully placed odometer.
HUD positions are not in the config file. There is nothing to edit in shared/general.lua for element placement, set the layout in-game with /mechanic_admin_hud and it is saved automatically.
Hiding the HUD Temporarily
If you need to hide the whole mechanic HUD from another resource, during a cutscene, for example, use the ToggleHUD export. See Developer Exports.
Using kartik-hud instead
When kartik-hud is running, the mechanic hands its indicators over to it, so players see one HUD instead of two. Everything sits in the player status row next to health, hunger and thirst, and only shows while driving. The matching parts of the built-in HUD switch off, and they come back if kartik-hud stops.
| Mechanic element | Shown in kartik-hud as |
|---|---|
| Nitro level | A Nitro gauge in the player status row. It turns red and blinks when low |
| Nitro held too long | An Overheating status that drains down to the blow-up and blinks red |
| Nitro cooldown / purge | A Nitro cooldown status that drains with the timer, and a Purge status while purging |
| TCS / ESC | TCS / ESC statuses: steady green while switched on, flashing yellow while the system is working, hidden while switched off |
| Racing harness | A Harness status, green when buckled and amber when not |
| Anti-lag | An ALS status (off by default) |
| Manual gearbox | The gear in kartik-hud's speedometer (R, N, 1…) |
| Mileage | kartik-hud's odometer |
| Seatbelt | kartik-hud's seatbelt light and warning chime |
Config.HUD = {
-- ...
Provider = 'auto', -- 'auto' (kartik-hud when running) | 'kartik-hud' | 'internal'
KartikHud = {
Nitro = true,
Electronics = true,
AntiLag = false,
Harness = true,
Gears = true,
Mileage = true,
Seatbelt = true,
},
}Turning an entry off keeps that element on the mechanic's own HUD. Provider = 'internal' never uses kartik-hud.
Players can recolour or hide each one in /hud → Player Status. See Custom Statuses & Buffs.