nCore HUD – game HUD, speedometer, seatbelt, toasts and UI surfaces in one resource documentation

Game HUD, vehicle controls and a notification and UI toolkit for FiveM, in one resource with no dependencies.

nCore Development · intelnpc.com · Resource: ncore_hud · Version: see fxmanifest.lua

What it is#

Most servers run four or five resources to get a HUD, a seatbelt, indicators, notifications and a few progress bars. This one does all of it in one place. Players get a status band next to the minimap, a speedometer cluster that changes with the vehicle, a weapon panel and a vehicle panel. Developers get toasts, more than 40 surfaces, minigames, a mission tracker and key prompts.

It reads its own data, so no other script has to feed it. With ESX, QBCore or QBox it also reads cash, bank, job and needs. On ox_core and ND_Core it follows the character's login and logout, and it runs on its own as well. Players change it in a settings menu and a drag-and-drop editor, and the choices are saved on their own machine.

Features#

Game HUD#

• Status band next to the minimap with health, armor, hunger, thirst, stamina, oxygen, stress, hygiene, sleep and voice as rings, bars or blades. Stamina and stress are off by default.
• Info chips for RP mode, street and cross street, time, date, cash, bank, job and grade, player ID and player count. RP mode, street and time are on by default. The others are one switch each in Config.Hud.status.widgets, and players can turn them on in /hudsettings. A value that hasn't arrived yet isn't drawn, so nobody sees a false 0 or $0.
• Docking. The band follows the minimap, or sits in a fixed corner as a row or a column.
• Shows only when it should. The HUD appears once a character is loaded and the player is in the world. It hides again on logout, when the player is dead, in the pause menu, behind a screen fade and in cutscenes. Any script can hide it with a reason through the exports.
• Weapon panel with the weapon name, magazine and reserve counts and a magazine bar that changes color when low. The counter only shows for weapons that fire rounds, and throwables show how many you carry. It shows whenever a weapon is in hand, or only while aiming, firing and reloading if you switch Config.Hud.arms.alwaysOn off.
• Compass tape at the top of the screen, optionally with the street name.
• Wanted stars, mic pip and identity line as optional parts with server name, player ID and player count.
• Area and vehicle name cards replace GTA's text. One toggle in the settings turns both off.
• Postal codes on the street chip from bundled MIT-licensed data. GetPostal returns the nearest one to other scripts.
• Waypoint distance on the street chip when a waypoint is set.
• Hygiene and sleep work without another script. They drain slowly, are remembered between sessions and refill with RestoreNeed or SetNeed. If another script feeds either stat, the built-in one steps aside for that stat.
• RP mode (text, voice or both) is set by the server or picked by the player with /rpmode. It shows on a chip and on the vehicle panel.
• Voice range. /voicerange, or a key you give it, cycles whisper, normal and shout through pma-voice, or through FiveM's built-in voice when pma-voice isn't running. A colored ring on the ground shows how far you carry.
• Compact mode and widget rules. A gauge that stays full for a while fades to a ghost without moving the layout. Each gauge has its own warn level, can invert (like stress) and can show only in a vehicle, on foot or underwater.
• Theme. Seven colors, an optional glow and a plate-strength setting restyle the whole HUD.
• UI scaling from a 1080p baseline, with a manual zoom, panel opacity and edge offsets.
• Frame-rate governor. Off by default. It watches FPS and turns cosmetic effects down in steps.
• Hides GTA's own HUD parts that this resource replaces (street, area and vehicle names, weapon icon, minimap health and armor arcs), with options for stars, cash, reticle and more. Everything is restored when the resource stops, and it warns when a hidden part isn't covered by anything.

Settings menu and layout editor#

• /hudsettings opens one panel with General, Parts and Layout. General covers HUD on or off, km/h or mph, gearbox mode, RP mode, radar shape and UI sounds. Parts turns panels and single widgets on or off. Changes apply at once.
• /hudeditor lets players drag the band, cluster and weapon panel and scale them, with a grid to snap to. A toggle also shows the six toast anchors and the surface docks. Done saves, Cancel reverts and Reset clears the layout.
• /hud turns the whole HUD off for that player, and /hudunit switches km/h and mph.

Driving cluster#

• Tachometer that sweeps 230 degrees with a thin needle, motion smear, rev-limiter flutter and the gear on the hub. Speed shows as three digits with dimmed leading zeros, plus the plate. It is driver-only by default.
• One instrument per vehicle type. Cars, motorbikes, bicycles, boats, helicopters and planes each get their own.
• Fuel dial, ECO light and tell-tale lamps for low fuel, engine damage, beams, seatbelt, parking brake, door open and more. They light only when needed. Next to the fuel dial on a car a consumption readout shows L/100 km, or liters per hour under 12 km/h. It is worked out from the revs and marked with ≈. With Config.Hud.dash.eco.source = 'measured' it reads the tank where your fuel resource makes the level drop, and falls back to the revs where it doesn't.
• Turbo boost gauge with a live bar that builds and dumps. You choose whether it shows on turbo cars, on all vehicles or never.
• Hooks. getFuel and getGear point the cluster at your own fuel resource or gearbox script. By default the fuel dial reads GTA's own fuel level.

Vehicle controls#

• Seatbelt on B or /seatbelt, with buckle and unbuckle sounds. A belted player can't get out until they unbuckle, and the belt comes off when they leave the vehicle. There is no belt on bikes, bicycles or boats. Other scripts can read the belt state from the player's state bag.
• Turn signals and hazards on the arrow keys, synced to every player. They cancel after a turn, tick with a relay sound, pick up changes made by other scripts and light up on the cluster.
• Gearbox. Automatic shows P R N D. Manual shows an H-gate where Shift and Ctrl raise and lower the top gear. The mode can be set per class or model, and players choose with /gearbox, in the settings or on the vehicle panel.
• Parking brake that stays on until released, with /parkbrake. Vehicles can optionally start in park.
• Cruise control on J or /cruise. It needs a minimum speed, the engine on and all wheels on the ground, and it lights a lamp on the cluster. It isn't available on boats, aircraft, bicycles or trains.
• Vehicle panel. /vehmenu or K opens a panel with Drive, Body and Style tabs for engine, headlights, seatbelt, parking brake, gearbox, signals, seats, doors, windows, roof, neon and more. Keys are checked through a hook for your keys resource, or fall back to the lock state.
• Quick commands. L toggles the locks, plus /engine, /vehdoor and /vehlights.
• Odometer stored per plate on the server, shown in km or miles. GetOdometer and SetOdometer read and set it.
• Seatbelt hint at the bottom of the screen for an unbelted driver.

Minimap, map and pause menu#

• Radar visibility. It's hidden on foot and shown in a vehicle by default, and stays hidden on the loading screen, in character selection and after a logout. If the game turns it back on, the hide is applied again.
• Radar shape. Square and circle ship ready, players pick with /radarshape, and a custom mask is supported. Only the mask is replaced, so other minimap resources keep working.
• Layout presets and zoom. Optional presets move the minimap with ultrawide correction. /radarzoom tries a zoom live. Presets are off by default.
• Fullscreen map. /map or F9 opens GTA's real map with blips, zoom and waypoint, without the pause-menu tabs.
• Custom pause menu. Off by default. ESC or P opens an orbiting camera shot of the player or their car, with a column for name, ID, job, cash, bank and links, and rows for resume, map, HUD editor, GTA settings and disconnect. You add your own rows with AddPauseMenuButton and can limit rows by job or by your own check. It doesn't close a menu or camera another resource opened, and it respects ESC claims.
• Optional map skin pack you enable by copying its files into stream/.
• Stream conflict check. At start the server checks that the radar shape files are present and that no other resource streams the same files.

Notifications#

• Eight toast types: success, error, warning, info, loading, money, item and custom. Toasts can be pinned or critical, show an item picture with quantity, a progress bar or a money amount, and carry action buttons that report the click back to your script.
• Six anchors and seven enter and exit animations (slide, fade, zoom, flip, bounce, drop, glitch).
• Categories (general, dispatch, money, item, job, broadcast and system) with priority. High-priority toasts jump the queue. Players mute categories from the notification center or with /notifymute. Critical toasts always get through.
• Queue and grouping. Each anchor shows a set number of toasts and the rest wait in a priority queue. Identical toasts from the client merge into one with an xN counter, and a group key merges them on purpose.
• Notification center and Do Not Disturb. /notifydnd sends non-critical toasts straight to history. /notifycenter opens a slide-out history with unread highlights, Mark all read and Clear all.
• Server broadcast. Send a toast or any surface to everyone, to one or more jobs, to a list of IDs or to everyone within a radius, from Lua or with /notifybroadcast. Admin only.
• Framework bridges. Optional bridges route ESX, QBCore and ox_lib notifications into nCore toasts. They are off by default so nothing shows twice. The OxNotify export also takes ox_lib-style tables.
• Sounds. Bundled sound presets play through a limiter. Add your own .ogg, .mp3 or .wav files, or a URL, and set the master volume and a sound per type.
• Text formatting. With Config.RichText on, which is the default, <b>, <i>, <u>, <s>, <br>, a colored <span> and the ^1 and ~r~ color codes render, and every other tag is dropped. Switch it off and all text is escaped.
• GTA native notifications. Client and server exports for the feed notification, advanced notification with a character icon, help text, subtitle, busy spinner and the big shard.
• Restyle in one place. Config.ToastDefaults and Config.SurfaceDefaults change every toast of one type, or every copy of a surface, without touching the scripts that call them.
• /notifypos sets or cycles the default toast anchor.

UI surfaces and minigames#

• More than 40 surfaces through ShowSurface, UpdateSurface and HideSurface. Many have their own named export, and results come back through callbacks.
• Cards and banners: caption, title, progress card, announce banner, alert with Acknowledge, area card, achievement, wanted stars, key hints and a rank bar with level-up.
• Progress: 3-2-1 countdown, progress bar, progress circle, segments and ring timer.
• Trackers: objectives, stepper, checklist, resources, delivery, process, receipt and rally splits.
• HUD widgets: compass tape, weather, server bar, buffs, kill feed and respect gauge.
• World and RP panels: 911 call board, evidence card, zone capture, crew roster, radio, death screen with an EMS key, scoreboard, fuel pump and a stash grid.
• Minigames: a skillcheck on Space, a hack grid you click through in order against a timer, and a confirm modal. Each returns its result to your Lua callback.
• Mission tracker. An objective list on the right edge with the live task lit and finished ones struck through. Tasks with coordinates get a blip, GPS route and floor marker, and complete on arrival. It supports counted and optional tasks and a countdown that fails the mission. It ends with a complete or failed banner and fires onTask and onComplete. Missions can be driven from the client or the server.
• Key prompts. "[E] Refuel" style prompts at the bottom of the screen, with a press callback, hold-to-confirm, an optional draining timer, priority and exclusive mode. Key slots come from Config.Keys.

For developers#

• Server exports that mirror most client exports, with the player ID first and -1 for everyone.
• Custom stats and widgets. Feed any stat from your own scripts, or register your own gauge or chip on the band with icon, color, warn level, invert and show rules. Stats can be cleared again.
• Screen ownership. IsScreenBusy tells scripts whether something else owns the screen, so your menus don't open on top. Other scripts can register as owners with RegisterScreenOwner.
• ESC claims. Other resources can claim ESC while their menu is open, so the custom pause menu stays closed.
• Client events such as ncore_hud:seatChanged, cruise, gearSelected, parkBrake, indicatorChanged, voiceRangeChanged, rpModeChanged, settingChanged and areaChanged let scripts react instead of polling.
• Unstuck. Every cursor claim is tracked and a watchdog releases a cursor held with nothing on screen. /notifyunstuck closes everything and gives the player back their cursor and controls.
• Diagnostics. /notifydebug prints state to F8, /hudwidgets lists every band widget and the detected framework, and LastNuiError, FocusReport and HudTickFaults are exports.
• Camera helpers for scripted cameras: look-at, eased moves between keyframes, depth-of-field ramps and push and pop of third person.
• /runnotifydemo runs a guided tour of the toasts, many of the surfaces, the HUD parts and the native notifications, with the calling code on screen. Sections can run on their own. Admin only by default.
• /notifyshowcase plays a short interactive story for recording promo videos, with captions, chapter cards and a duration scale. Admin only by default.

By default the showcase sets its own time and weather through freezeTime and freezeWeather. Pause your time and weather sync script (vSync, qb-weathersync and the like) while you record, because those scripts apply time and weather again every tick and will override it.

Languages#

English, Hungarian and German are included. Config.Locale = 'auto' picks one from the server's locale convars or the player's game language and falls back to English. For another language, add one file in locales/, as described under Locale system.

Requirements#

Required: nothing. No database, no OneSync, no ox_lib.

Optional, used when they run:

• ESX, QBCore or QBox, for cash, bank, job, needs, stress and job broadcasts. On ESX, hunger, thirst and stress come from esx_status.
• ox_core and ND_Core, for the character's login and logout. Cash, bank, job and needs aren't read from them, so feed those with SetHudStat or SetHudStats.
• ox_lib, only for its notify bridge.
• pma-voice for voice range. Without it the HUD sets the range through FiveM's built-in voice.
• Your fuel resource or gearbox script, through the getFuel and getGear hooks.
• Your keys resource, through Config.VehicleControl.hasKeys. Without it the vehicle panel goes by the lock state.
• Weapon pictures from ncore_inventory, ox_inventory (following its inventory:imagepath convar), qb-inventory, qs-inventory or ps-inventory, or from your own folder through Config.Hud.arms.images. No weapon pictures ship with this resource.
• Menus don't open on top of ncore_inventory, ox_inventory, qb-inventory, qs-inventory or lb-phone. Add other resources to Config.Conflicts.list.
• ncore_vibehud. While it runs, the band, cluster, weapon panel and minimap control stand down.

Standalone works without any of them.

Don't rename the ncore_hud folder, other resources call it by name. Steps are in INSTALLATION.md.

Commands and keys#

Indicators use the arrow keys (left, right, down for hazards), and manual shifting uses Shift and Ctrl. Single-key surfaces read Space for the skillcheck, G for the EMS call, X to cancel a progress bar and Tab to close the scoreboard. Prompt slots are E, G, H and X. Commands marked "none" have no default key. Use the command, or set a key in the config where the option exists.

Config files#

• config.lua has every setting: framework, toasts, categories, sounds, HUD band, cluster, weapon panel, gearbox, seatbelt, indicators, cruise, vehicle panel, minimap, map, pause menu, prompts, missions, broadcast, demo and showcase.
• locales/*.lua are the language files.

Both stay open for editing in the Escrow edition. The most changed settings:

• Config.Framework auto-detects or forces ESX, QBCore, QBox or standalone. ox_core and ND_Core are only detected on auto.
• Config.Locale sets the language, or auto.
• Config.Hud.speedUnit sets the default km/h or mph.
• Config.Hud.rpMode sets the server RP mode.
• Config.Hud.theme sets the HUD colors, glow and contrast.
• Config.Hud.dash.getFuel and getGear hook your fuel or gearbox script.
• Config.VehicleControl.hasKeys hooks your keys resource.
• Config.Compat turns on the framework notify bridges.
• Config.PauseMenu.enabled turns on the custom pause menu.
• Config.Minimap.show sets when the radar shows.

Locale system#

With Config.Locale = 'auto' the language is picked in this order: the lr:locale convar, then locale, ox:locale, esx:locale and txAdmin-locale, then the player's game language, then English. A code with no language file is skipped, and codes like en-US or de_DE match en and de. To pin one language for everyone, set Config.Locale = 'de', or put setr lr:locale de in server.cfg (setr, so the players' game sees it too). The server console prints which language it picked and why.

To add a language, copy locales/en.lua to locales/xx.lua, change Locales['en'] at the top to Locales['xx'], translate the strings and set Config.Locale = 'xx', or leave it on auto. A key you haven't translated falls back to English. The new file loads by itself, and in the Escrow edition it stays editable like the others.

Compatibility flags#

Config.Compat routes framework notifications into nCore toasts.

All of them ship off. Turn one on only after the framework's own notification is switched off, or every message shows twice. Client scripts written for ox_lib's notify can call exports.ncore_hud:OxNotify(data) with the same table.

Exports and events#

Exports are called as exports.ncore_hud:Name(...). The main groups are toasts (Notify, Success, Error, Warning, Info, Loading, Money, Item, Update, Dismiss), surfaces (ShowSurface, UpdateSurface, HideSurface and the named ones such as Announce, Alert, Progress, Skillcheck, HackGrid, Modal), missions (Mission, MissionTask, MissionProgress, MissionComplete), prompts (ShowPrompt, UpdatePrompt, HidePrompt), HUD (SetHudStat, RegisterHudWidget, SetHudVisible, SetHudEnabled), vehicle (SetSeatbelt, SetIndicator, SetCruise, SetGearboxMode, SetParkBrake, GetOdometer, SetOdometer) and server broadcasts (Broadcast, BroadcastAll, BroadcastToJob, BroadcastToIds, BroadcastNear). The minimap, fullscreen map and pause menu exports exist only when that feature is enabled in config.lua.

Toast fields#

Notify takes one table and returns the toast's id, which Update and Dismiss take. The shorthands (Success, Error, Warning, Info, Loading, Money, Item) fill some fields for you and take the rest as their last argument.

The fields are type (success, error, warning, info, loading, money, item or custom), title, message, label (the small line above the title), icon, accent ('#rrggbb'), duration in ms, position (one of the six anchors), animation and exitAnimation, sound (a preset name, { file = 'sounds/x.ogg', volume = 0.8 } or false), category, priority (1 to 10), critical, pinned, group (toasts with the same key merge into one), id (to update or replace it later), progress (0 to 1), money (an amount that counts up, or down when negative), item ({ name = ..., qty = ..., image = ... }), actions and onAction. An action is { id = 'accept', label = 'Accept', style = 'primary' }, with primary, danger, accent or ghost as the style, and onAction is a Lua function that gets the button id and the toast id. Update(id, patch) takes any of these fields, plus attention = 'shake' or 'flash' to draw the eye to a toast that is already up. Config.ToastDefaults takes the same fields per type.

Surface catalog#

ShowSurface(name, props, cb) shows a surface and returns its id, UpdateSurface(name, id, patch) changes it and HideSurface(name, id) takes it away (without an id, every copy of it). These are the names:

Each surface's main props and their defaults are in Config.SurfaceDefaults, with a comment per line. /runnotifydemo <section> shows most of them, with the call that produced each one on screen.

Icons#

An icon field takes one of the HUD's own drawn icons or any Lucide icon name, such as heart, shield-half or trophy. The bundled font has 1,996 of them, each listed in web/assets/lucide/lucide.css as .icon-<name>.

Updating#

Updates don't install themselves. Download the new version (Escrow from your Cfx.re account, Full source from Tebex), keep your own config.lua and locale files, and copy every other file over the old ones. Settings added in a new version are listed under that version in CHANGELOG.md, so you can copy them into your config.

Common questions and fixes#

Nothing shows after a restart. Run /notifydebug for the state in F8, and /hudwidgets for every band widget, whether it has a value and which framework was detected. The HUD waits for a loaded character, and on standalone it comes up after the first spawn.

A ring or chip stays empty. /hudwidgets lists it as ON but NO VALUE when nothing feeds it. On ESX, hunger and thirst need esx_status. On ox_core, ND_Core or any other framework, feed it with SetHudStat.

The stress gauge doesn't move. It ships off, and it only reads stress from QBCore, QBox or esx_status. The HUD doesn't raise stress by itself.

Toasts show twice. A Config.Compat flag is on while the framework's own notification still runs. Switch one of the two off.

On a 1440p or 4K screen the UI is the same layout, larger. It is drawn for 1080p and scales with the screen height through Config.AutoScale. Config.UiScale, Config.PanelOpacity, Config.OffsetX and Config.OffsetY adjust it further.

To keep players from changing the HUD, Config.Hud.settings.enabled and Config.Hud.editor.enabled remove the settings menu and the editor. Config.Hud.playerToggle, Config.Hud.gearbox.playerToggle, Config.Hud.rpModePlayerChoice and Config.Minimap.silhouettePlayerChoice take single choices away. A player's saved layout stays on their machine. The server sets where everyone starts, but it can't push one layout to everyone later.

The radar keeps its stock shape on FiveM for GTA V Enhanced. The shape files in stream/ are Legacy files. Convert them once with Cfx.re's Alchemist, the steps are in mapskin/README.md.

A player is stuck with a cursor or frozen controls. /notifyunstuck closes everything and hands them back, and Config.UnstuckKey gives it a key.

Support#

Support is on intelnpc.com and I reply within 72 hours. It covers installing, configuring and bugs in the script as shipped. Payments and refunds are handled by Tebex under their terms.

nCore HUD is made by nCore Development. It is not approved, sponsored or endorsed by Rockstar Games.