Bucky HUD

#Overview

Bucky HUD is a complete heads-up display for QBCore servers on FiveM and FiveM for GTA V Enhanced. It replaces qb-hud and listens to the same events, so seatbelt, cruise, nitrous, harness, stress and money from other scripts keep working without changes.

Every player can restyle and rearrange it for themselves from an in-game menu. Their settings, layout and saved profiles are stored on their own PC, so nothing touches your database.

#Installation

#Step 1: Place the resource

Put bucky-hud in your resources, for example in [bucky-scripts], and make sure it starts after qb-core:

ensure qb-core
# ...
ensure [bucky-scripts]      # or: ensure bucky-hud

fxmanifest.lua declares dependency 'qb-core'.

#Step 2: Remove qb-hud

Bucky HUD replaces qb-hud. Stop it and move it out of your started folders (for example to resources/[disabled]/qb-hud). If qb-hud is still running, the server console prints a warning on start.

#Step 3: Patch qb-core's prompts and notifications (recommended)

qb-core draws its [E] prompts and its notifications in its own page, so no other resource can restyle them. A small patch in qb-core/client/drawtext.lua and qb-core/client/functions.lua hands both to Bucky HUD whenever it is running, and falls back to the stock look when it isn't. The exact changes are in patches/qb-core-prompts-to-bucky-hud.md.

Without the patch everything else works; prompts and notifications just keep qb-core's look.

#Step 4: Replace the default chat

Bucky HUD's chat replaces the default chat resource. In server.cfg, remove (or comment out) ensure chat, and turn off FiveM's built-in chat, which otherwise starts by itself on every boot:

# ensure chat
set resources_useSystemChat false

If the built-in chat starts anyway, Bucky HUD stops it and takes over (Config.Chat.StopDefault).

While the default chat is running, Bucky chat stays off so nothing shows twice, and the server console says so on start. To keep the default chat instead, set Config.Chat.Enabled = false.

#Step 5: Restart

On a running server, new files are only noticed after a refresh:

refresh
restart bucky-hud

On first start the F8 console prints Radar mask: rounded once the radar has its new corners.

#The HUD menu

Players open it with /hud or the I key (Config.MenuKey; players can rebind it under Settings → Key Bindings → FiveM). Every change applies live and is saved straight away.

The header has Reset (back to the server's defaults) and Edit layout.

The accent colour colours redlines, active lights, the selected menu items, the Card look and the player's GPS route on the map (Config.Map.RouteColor = 'accent').

#Speedometers and dashboards

#Road styles

Analogue and Classic have a rolling drum odometer set into the speedo face; the digits roll into each other like a real one, with the tenths drum in contrasting colours.

Auto picks the style by vehicle class (Config.AutoStyle): compacts and sedans get Modern, muscle and classics Classic, supercars and motorbikes Bold, off-road and work vehicles Analogue, vans Minimal, and so on. Config.ModelStyle sets a style for single models.

#Vehicle kinds

The dashboard adapts to what you're in (Config.ClassDash, Config.ModelDash):

#Aircraft

#Details

• Gear: R when reversing, N when stopped, D on EVs, P with the engine off. With bucky-driving's manual gearbox running, the dial shows the gear the player selected (N, R, 1, 2 …, even when stalled) and the gearbox's engine RPM, instead of the game's own gear.
• Engine off: every style goes dark as if its backlight were off (markings fade to unlit grey, displays drop to faint ghosts, lamps go out) and lights back up when the engine starts. Most styles sweep their gauges to full and back on start, like a real cluster.
• Dial scales fit the vehicle's top speed: 80 to 260 mph or 120 to 400 km/h. Numbers keep the same gap from the ticks at every scale, and three-digit scales get a smaller face.
• Extras under the speedometer: nitrous level (glowing while active), harness uses, truck air and trailer, bike lean, boat heading and depth. Chips only appear when they apply.
• Indicator bar: indicators, hazards, low and high beam, cruise, seatbelt, check engine and handbrake. With Analogue and Classic it becomes a row of jewel lamps.
• Sounds: an indicator relay tick and a seatbelt chime (four chimes when you pull away unbuckled, then one every ten seconds). Both are synthesised in the browser; no audio files.
• Housing and background: players can switch off the case around Analogue and Classic, and the dark panel behind the other styles, for a cleaner look over the road.

#Minimap

Bucky HUD keeps GTA's own radar, so blips, the GPS route, interiors and fog of war work as usual. It changes how the radar looks and where it sits:

• Rounded or classic corners. The radar's mask is swapped once for one drawn at runtime (nothing is streamed) with a crisp edge. The game's own mask has a soft glow that lets the map bleed past its frame once it's moved. Switching shape redraws only the mask's corners, which also works reliably on GTA V Enhanced. Config.Map.Radius sets the rounded corner size.
• Move and resize. In the layout editor the radar follows its frame live while dragging. The minimap, its mask and its backdrop move and scale together from the map's top-left corner.
• No health or armour bars under the radar (Config.Map.HideBars; /hudbars toggles them for the session). The frame ends where the map ends.
• Blips stay inside. The game pins off-map blips (police calls, the north marker) to the edge of its own frame, half outside. The mask shows a little more map on each side (Config.Map.EdgeRoom), so those blips sit inside the map.
• Alert rings. A big pulsing ring blip (like the one qb-policejob draws around a call) is drawn over the radar's mask and always spills past its edge. By default rings only show on the pause map; the call's own blip still shows on the radar (Config.Map.RingMode).
• Day/night tint that follows the in-game clock (Config.Map.DayStart, DayEnd).
• Waypoint distance in the map's top-left corner, in miles/feet or km/metres.
• Speed limit sign in the top-right corner, US rectangle or EU disc. GTA has no speed limits, so they come from street names (Config.SpeedLimits). The sign flashes red when you go over the limit plus Tolerance.
• Street card above the map: street, cross street, area and a compass letter. When the map hides (leaving a vehicle), the status icons and street card glide into its place.

#Status icons

Health, armour, hunger, thirst, stress, stamina and voice.

• Styles: Ring (a progress circle), Percent (the number under the icon), Fill (the icon's tile fills up) or Bars (two rows of icon and bar). Shapes: circle or rounded square.
• Visibility per icon: Always, Auto or Off. Auto only shows an icon when it needs attention, using Config.Auto: health below 100, hunger and thirst below 40, stress above 15, stamina while it's being used, armour while you have any.
• Stamina turns into oxygen underwater.
• Voice shows the proximity range, lights up in the accent colour while talking, turns blue on the radio and shows the radio channel.
• Icons pulse when critical, and a DEV tag shows in qb-admin dev mode.

Stress follows qb-hud's rules and events (Config.Stress): shooting and fast driving add stress, whitelisted jobs and weapons don't, and high stress blurs the screen now and then.

#Cash, bank and job

Cash and bank show always, for a few seconds after they change, or never. Changes pop up under them as green + $250 or red − $80 lines, labelled with the account. /cash and /bank show the balance even when it's switched off.

Job and duty show under them: job name, grade and On duty (with a green light) or Off duty. Players choose Always, With cash (only while the cash shows) or Off.

Five looks:

The job updates the moment it changes: a new job, a promotion, or going on or off duty.

#Prompts and notifications

Prompts show as key caps next to their text, on the left, right, top or bottom of the screen, with a press animation. They understand qb-core's formats: [E] - Open garage, E - Open garage, Press [E] to open, and several lines separated by <br>.

Notifications slide in on the right (or left, Config.Notify.Position), with an icon and colour per type, an optional caption, and a bar that runs down. Repeats of the same message stack as ×2, ×3 instead of filling the screen. At most Config.Notify.Max show at once.

Types: primary, success, warning, error, info, police, ambulance.

With the qb-core patch (see Installation), every QBCore script's DrawText prompts and QBCore.Functions.Notify calls use these automatically.

#Chat

Bucky HUD brings its own chat, drawn in the HUD's style and the player's accent colour. It replaces the default chat resource and answers all of its events and exports, so qb-core, qb-adminmenu, qb-inventory, ox_lib and every other script that writes to the chat work unchanged: chat:addMessage, chatMessage, suggestions, templates, ^1 colour codes and modes.

Five looks (menu → Chat):

Showing messages:

• Fade (default): new messages show for a while (4–30 s, Fade after), then fade out and fold away, so the corner of the screen stays clear. Opening the chat shows them all again.
• Always: the feed stays up.
• While typing: the feed only shows while the input is open.
• /toggleChat cycles the three (the default chat's command, kept for players' binds), or /toggleChat whenactive | visible | hidden. Config.Chat.ToggleKey can put it on a key.
• Timestamps can be switched on for every look; Terminal always shows them.
• The chat hides on the pause menu and while the screen is faded out, and in cinematic mode unless you're typing.

Typing (T, Config.Chat.OpenKey; players can rebind it in GTA's key bindings):

• Command suggestions appear as soon as you type /: the best matches with their help text. Tab completes the highlighted one, ↑ ↓ move through them. Once a command is typed, its arguments show with the one you're on highlighted and its help underneath.
• History: with no suggestions open, ↑ ↓ go through what you sent.
• Page Up / Page Down scroll the feed; older lines fade softly at the top instead of being cut.
• A counter appears near the length limit (Config.Chat.MaxLength).
• Enter sends, Esc closes.

Colours: names without a colour of their own get one of eight, the same one every time, so people are easy to tell apart. Colours scripts send (color = { r, g, b }) are used, and ones too dark to read on the dark looks are lifted. ^0–^9, ^* bold, ^_ underline, ^~ strike and ^r work in names and text.

Templates from other scripts (qb-adminmenu announcements, qb-inventory ID cards, qb-drugs dealer lists, anything using template = or chat:addTemplate) keep their layout. Their common classes (chat-message, advert, server, emergency...) are restyled to match each look.

Safe by design: what players type is always shown as text, never read as HTML, and only the HUD's own page can send chat or run commands (nui_callback_strict_mode).

The chat can be moved and resized in Edit layout like every other part, and the menu page and the layout editor show it with sample lines so each look can be judged.

#Layout editor and screen fence

Edit layout (in the menu header) turns the HUD into a canvas:

• Drag the minimap, speedometer, indicator bar, status icons, player ID, cash & job, street card and chat anywhere.
• Resize from 50% to 200% by dragging a corner handle (the opposite corner stays put) or by scrolling over a part. A badge shows the size.
• Parts that are usually hidden (the speedometer on foot, the minimap, cash, the job) show with sample data while editing.
• Reset layout puts everything back; Done or Esc saves and returns to the menu.

Positions are stored as fractions of the screen, so a layout carries over to other resolutions.

The screen fence keeps the HUD on screen and tidy, without taking control away from players:

• Nothing hangs off the screen. After a resolution or aspect change, a bigger HUD size or a wider speedometer, each part is pulled back inside the edges. That is only an offset: the saved spot is kept, and the part returns there once it fits again. A moved minimap is clamped and saved, because the game's radar has to move with it.
• Default spots never collide. The status icons go under the map when there's room and otherwise beside it, on whichever side has space. The street card goes above the map, or under it when the map is at the top. Any part still in its default spot steps aside (up, or down for parts hanging from the top) instead of covering another part.
• Players stay in charge. Parts a player placed are never moved to avoid others, so players can overlap things on purpose.
• Resizing stops at the screen edge.

#Profiles

Players save their whole setup (colours, styles, sizes and layout) under a name on the Profiles page: type a name and press Save or Enter. Using an existing name replaces that profile after a confirmation.

• Load applies a profile. The profile matching the current setup is marked In use.
• The save icon puts the current setup into a profile; the bin deletes one. Both ask once more.
• Each profile shows its accent colour, speedometer and status style, size and how many parts it moves.
• /hudprofile Street switches by name; /hudprofile alone goes to the next profile, so it can sit on a key: bind keyboard J hudprofile.
• Up to Config.Profiles.Max profiles (8), stored on the player's PC. Loading one starts from the defaults, so profiles saved before an update still load cleanly.

#Commands and keys

#Configuration reference

Everything is in config.lua.

#Config.MenuKey

Default key for the menu ('I'). Players can rebind it in GTA's key bindings.

#Config.Defaults — starting settings for every player

Players change these in the menu; their choices are saved on their PC.

#Config.Profiles

#Config.Chat

#Config.Map

#Config.Auto

When Auto icons appear: health = 100 (below), hunger = 40, thirst = 40 (below), stress = 15 (above), stamina = 95 (below, while in use).

#Config.SpeedLimits

#Config.Currency

Symbol in front of amounts ('$').

#Dashboards

#Config.Stress

Same rules and events as qb-hud: Enabled, Chance per shot, SpeedBuckled / SpeedUnbuckled (mph), MinimumForEffects, WhitelistedJobs, WhitelistedWeapons, NoStressClasses, and the blur Effects per stress level.

#Config.Notify

Position = 'right' (or 'left'), Length = 5000 ms, Max = 4.

#Config.Tick

Update rates in ms: Status = 250, Vehicle = 80, Air = 50, World = 1000.

#For developers

#Exports (client)

exports['bucky-hud']:ShowPrompt('[E] Refuel', 'left')   -- 'left', 'right', 'top', 'bottom'
exports['bucky-hud']:ShowPrompt({ { key = 'E', label = 'Refuel' }, { key = 'G', label = 'Pay by card' } })
exports['bucky-hud']:PressPrompt()                       -- key press animation, then hides
exports['bucky-hud']:HidePrompt()
exports['bucky-hud']:Notify('Saved', 'success', 5000)    -- or { text = '...', caption = '...' }

The same four are available as local client events: bucky-hud:client:prompt, bucky-hud:client:hidePrompt, bucky-hud:client:pressPrompt, bucky-hud:client:notify.

#Chat

Bucky chat answers everything the default chat resource does, under the same names:

Scripts that call exports.chat:... directly need exports['bucky-hud']:... instead; none of the QBCore resources do.

#Events it listens to (qb-hud names)

#Fuel

Fuel is read from bucky-fuel first, then LegacyFuel (exports[res]:GetFuel(vehicle)), then the vehicle's fuel state bag, then the game.

#The Bucky Ecosystem

Bucky HUD is the screen the rest of the Bucky scripts talk through. Each script works on its own, and they link up when installed together.

Bucky HUD and Bucky Driving are also sold together as the Bucky Drive Pack.

#Performance

Bucky HUD is built to stay out of the frame budget:

• Timers, not frames. Status every 250 ms, vehicle dashboards every 80 ms (aircraft 50 ms) only while seated, street names and waypoint every second (Config.Tick).
• Only changes are sent. The client compares every value with the last one sent; the interface only receives what changed and only redraws what changed.
• The chat has no per-frame loop. T is a key mapping; pause and loading screens are checked four times a second. Each message is one small DOM node, and the feed keeps the last Config.Chat.MaxMessages.
• One small per-frame call while the radar is showing, to keep the game's health bars hidden (the game resets them every frame).
• The radar mask is drawn once per session over a few frames, in batches that shrink if the frame rate drops. Changing shape redraws only its corners.
• Light interface. Needle shadows are flat shapes instead of blur filters, the dial shadow doesn't depend on the needles, and sound timers only exist while they're playing.

To check it on your server, open the F8 console and run resmon 1 and look at the bucky-hud line, on foot and while driving. It is designed to stay well under 0.1 ms.

#Troubleshooting

The minimap is blank or grey. Open and close the pause menu once. If it happens every time, run /hudmapdebug and check the F8 line. The radar is refreshed each time it's shown, which fixes the GTA V Enhanced blank radar.

The corners don't change when I switch Rounded / Classic. The F8 console should print Radar mask: rounded or classic. If you restarted the resource many times in one session, reconnect once.

Blips or a thin line show at a minimap edge. Tune Config.Map.EdgeRoom for that side: raise it if blips poke out, lower it if a thin empty line shows.

Police alert rings spill over the map. That's Config.Map.RingMode = false or 'near'. 'map' (the default) keeps them off the radar.

Prompts and notifications have the old qb-core look. The qb-core patch isn't applied, or qb-core was updated and the patch was lost. See Installation.

The HUD frame is offset from the radar. Use Config.Map.Nudge (px at 1080p). /hudmapdebug outlines where the HUD thinks the radar is.

Parts moved after changing resolution. That's the screen fence pulling them back on screen. They return to their saved spot when they fit again; a moved minimap is re-saved inside the screen.

Messages show twice, or T opens the old chat. The default chat is still running. Remove ensure chat and set resources_useSystemChat false in server.cfg, then restart the server (or stop chat). The server console prints a warning on start while both are running.

T does nothing. Check the key under Settings → Key Bindings → FiveM → Chat: type a message. The chat doesn't open over the HUD menu or the pause menu.

A script's chat message looks unstyled. Custom templates keep their own HTML. The common chat-message classes are restyled; other classes show as the script wrote them.

Something looks stuck. /resethud reloads the HUD without restarting the resource.

Everything is too small or too big. Menu → General → HUD size (80–130%), or resize single parts in Edit layout.

#Files

bucky-hud/
├── fxmanifest.lua
├── config.lua               all settings (see Configuration reference)
├── client/
│   ├── main.lua             settings, profiles, status loop, money, job, menu, commands
│   ├── minimap.lua          radar mask, position, alert rings, street and speed limit loop
│   ├── vehicle.lua          dashboard picking and telemetry
│   ├── stress.lua           stress rules and screen effects
│   ├── prompts.lua          prompt and notification exports
│   └── chat.lua             chat events, exports, T key, suggestions
├── server/
│   ├── main.lua             stress events, qb-hud warning
│   └── chat.lua             chat routing, hooks, modes, joins, /say
└── html/
    ├── index.html
    ├── css/hud.css          HUD, menu, layout editor
    ├── css/dash.css         dashboards
    ├── js/app.js            HUD, menu, layout editor, screen fence, profiles
    ├── js/chat.js           chat feed, input, suggestions, five looks
    └── js/dash.js           dashboard builders

Player data is stored in the client's resource KVP: bucky-hud:settings and bucky-hud:profiles.

#Changelog

#1.0.2

• Fixed: after a fresh join the minimap could stay square or in the default spot until the resource was restarted. It is now applied again once it first shows in the world.

#1.0.1

• Shows the selected gear and the gearbox RPM when Bucky Driving is installed.
• The qb-core prompt and notification patch guide is now included in patches/.
• config.lua stays editable in the escrowed release.

#1.0.0

• 7 road speedometer styles and 3 aircraft instrument sets, picked per vehicle class, with EV, motorbike, truck and boat dashboards.
• Dashboards go dark with the engine off and sweep on start; dial numbers fit every scale; rolling drum odometer set into the Analogue and Classic speedo face.
• GTA's own radar with rounded or classic corners, movable and resizable, no health bars, edge blips kept inside, alert rings kept off the radar.
• Status icons in 4 styles and 2 shapes, each Always / Auto / Off.
• Cash, bank and job with duty, in 5 looks.
• Prompts and notifications for every QBCore script (with the qb-core patch).
• Layout editor with corner resizing, and a screen fence that keeps everything on screen and default spots apart.
• Named profiles with /hudprofile.
• Load-in: the HUD waits until the player is in the world (no loading screen, fade or spawn camera), reloads everything including the radar, then glides in part by part.
• Player ID chip at the top right.
• Chat replacing the default chat resource, in 5 looks, with command suggestions, history, fading messages and full compatibility with its events, exports and templates.