BETTER HUD V3

# Risk HUD V3 — Custom HUD with Speedometer, Visa System & Layout Editor for FiveM

**Every player builds their own HUD. Three styles, any color, every element draggable.**

A complete FiveM HUD script for ESX, QBCore and QBox: status bars, money, weapon, speedometer, radio list, compass, notifications, announcements, team chat and a visa system with playtime rewards. Players customize it ingame, you keep control of what they may change.

---

## Why this one

Most FiveM HUDs are one fixed layout in one fixed color that you have to edit in CSS. This one isn't.

- **Players design their own HUD.** A settings menu (`/hud`) lets everyone pick a style per element group, change every color and drag every element to their own spot.

- **Three complete styles.** Diamond, Line and Tile, each hand-drawn, not recolored boxes. Mix them per group.

- **You stay in control.** One switch each locks styles, colors, visible elements and positions for everybody.

- **More than a HUD.** Notifications, help notify, progress bar, announcements, item popups, team chat and a visa system are built in, so you replace several scripts at once.

---

## Three Styles, Three Speedometers

| Group | What it covers |

| --- | --- |

| **Server info** | Voice range, online players, player ID, visa |

| **Money** | Cash, bank and black money |

| **Status** | Health, armor, stamina, food, water, job, street and zone |

| **Radio list** | Channel and members, with who is talking |

| **Messages** | Notifications, announcements, help notify, progress bar, item popups, chat |

Every group has its own style: **Diamond**, **Line** or **Tile**. Set your server default in the config, players change it for themselves.

The speedometer comes as **Digital**, **Round** or **Simple**, with speed, RPM, gear, fuel level and seatbelt icon. `km/h` or `mph`, and it works with LegacyFuel, ox_fuel or your own fuel script.

---

## Player Settings Menu

Players type `/hud` and get a live preview of everything they change.

| Tab | What the player does |

| --- | --- |

| **Styles** | Pick Diamond, Line or Tile per group, or one style for everything |

| **Colors** | Change the accent and every single color: health, armor, food, money, notifications and more |

| **Display** | Show or hide every element, set the compass to always, vehicle only or off |

| **Layout** | Drag every element where they want it, with grid snapping |

Settings are saved on the player's own PC and come back on every login. No database needed.

> Want one look for everyone? `lockStyles`, `lockColors`, `lockElements` and `lockPositions` each switch one tab off.

---

## Layout Editor

Every element can be moved: logo, server info, money, weapon, radio list, speedometer, health, armor, stamina, food, water, job, street, zone, notifications, announcements, help notify, progress bar, item popups, chat, team chat, compass and key hints.

| Control | What it does |

| --- | --- |

| **Drag** | Move the element, snapped to the grid |

| **Shift** | Move freely without the grid |

| **Arrow keys** | Nudge by one step |

| **Double-click** | Back to the default position |

Grid size and snapping are the player's choice. Your default layout stays untouched until they move something.

---

## Visa System

New players earn their rights by playing. The HUD counts playtime and turns it into a **visa level**.

- **Levels by playtime** — you set the minutes for every level, for example 5, 10, 5, 10, 5, then 20 minutes per further level

- **No fighting below a level** — new players can't attack until they reach `attackLevel`, which keeps trolls out of your city

- **Rewards at a place** — an NPC or marker where players press `E` and collect money or items for their level, one time each

- **Existing players** — everybody who played before the install gets a start level automatically

- **Admin commands** — `/setvisa` and `/visa`, usable by ACE or group

Playtime is stored in your database, the tables are created automatically. Other scripts can read the visa with simple exports, for example to unlock a job from level 10.

---

## Everything a HUD Needs

| Feature | Details |

| --- | --- |

| **Notifications** | Info, success and warning, with a countdown bar |

| **Help notify** | Key hint while the player stands at your marker or NPC |

| **Progress bar** | One export, waits until done, returns finished or cancelled |

| **Announcements** | `/announce` for everyone, `/announceto` for one player, txAdmin announcements included |

| **Item popup** | Shows every item added or removed with its image from your inventory |

| **Weapon display** | 90 weapon images included, with ammo |

| **Team chat** | `/t` for staff only, rank shown from your groups or ACE |

| **Command input** | Press `T`, type a `/command`, press Enter |

| **Compass** | Always, vehicle only or off, set by you and by the player |

| **Key hints** | F1, F2 and more, read from the player's own key bindings |

| **Safezones & deathzones** | Zone label in the HUD, with an optional countdown |

| **Seatbelt** | Key `B`, warning sound, and players fly out of the car in a hard crash without it |

| **Cinematic mode** | `/cinema` shows black bars and hides HUD and minimap |

| **Minimap** | Custom mask and position that fits the HUD |

---

## Built for Your Other Scripts

A documented export API ships with the script.

```lua

-- Hide the HUD while your own UI is open

exports['risk-hudv3']:HideHud('myscript')

-- Show a notification and a progress bar

exports['risk-hudv3']:Notify('success', 'Garage', 'Vehicle parked.', 5000)

local finished = exports['risk-hudv3']:Progress('Repairing vehicle', 5000)

-- Unlock something from visa level 10 (server side)

if not exports['risk-hudv3']:HasVisa(source, 10) then return end

```

Client and server exports for HUD visibility, notify, help notify, progress, item popups, zones, visa, playtime, seatbelt and announcements. Full list in `EXPORTS.md`.

---

## Compatibility

| | Supported |

| --- | --- |

| **Framework** | ESX · QBCore · QBox · standalone — auto-detected at runtime |

| **Inventory** | ox_inventory · ps-inventory · qb-inventory · codem-inventory · origen_inventory · framework native |

| **Voice** | pma-voice · SaltyChat |

| **Fuel** | LegacyFuel · ox_fuel · any script with one line in the config |

| **Database** | oxmysql · mysql-async · ghmattimysql — only used for the visa |

| **Resolution** | Responsive from 1080p to 4K and ultrawide |

| **Languages** | English · German · French · Spanish · Italian · Dutch · Portuguese |

---

## What You Get

- ✅ Three complete HUD styles: Diamond, Line and Tile

- ✅ Three speedometers: Digital, Round and Simple

- ✅ Player settings menu with live preview

- ✅ Free color picker for every single element

- ✅ Layout editor with drag and drop and grid snapping

- ✅ Server locks for styles, colors, elements and positions

- ✅ Visa system with playtime levels and attack lock

- ✅ Visa reward NPC with money and items per level

- ✅ Notifications, help notify, progress bar and item popups

- ✅ Announcements with txAdmin support

- ✅ Staff team chat with ranks

- ✅ Radio list with talking indicator

- ✅ Compass, seatbelt and cinematic mode

- ✅ Safezone and deathzone display

- ✅ 90 weapon images included

- ✅ Full export API with documentation

- ✅ 7 languages, every string translatable

- ✅ Rewards, announcements and team chat checked on the server

- ✅ Optimized loops, no per-frame work while on foot

---

## Installation

1. Drop `risk-hudv3` into your resources folder

2. Add `ensure risk-hudv3` to your `server.cfg`

3. Set your server name, logo and language in `config.lua` and restart

The visa tables are created automatically on the first start. No SQL import needed.

**Requirements:** `oxmysql`, `mysql-async` or `ghmattimysql` · ESX, QBCore or QBox

---

## FAQ

**What is Risk HUD V3?**

A FiveM HUD script for ESX, QBCore and QBox with three styles, a speedometer, a layout editor, a visa system and built-in notifications. Every player customizes it ingame.

**Does it work with ESX, QBCore and QBox?**

Yes. The framework is detected automatically. A standalone mode without framework is included.

**Can players move the elements themselves?**

Yes. `/hud` opens the layout editor. Set `lockPositions = true` if you want one fixed layout.

**Can I force one style and color for everyone?**

Yes. Four switches in the config lock styles, colors, visible elements and positions separately.

**Does it replace my notify and progress bar?**

Yes. Notify, help notify, progress bar and item popups are built in with exports. Point your scripts at the exports and you can remove the old ones.

**Does it work with my inventory?**

Yes. `ox_inventory`, `ps-inventory`, `qb-inventory`, `codem-inventory`, `origen_inventory` and the framework native API are detected automatically. If yours is missing, one function in the editable `inventory/` folder adds it.

**Does it work with pma-voice and SaltyChat?**

Yes, the voice range display works with both. The radio list needs pma-voice.

**Do I need a database?**

Only for the visa system. Without it the rest works as usual, set `Config.Visa.enabled = false`.

**Can I add my own language?**

Yes. The `locales/` folder is not escrowed. Copy a language file, translate it and set `Config.Locale`.

**Can I use my own logo and server name?**

Yes. Title, subtitle, tagline and logo are set in `Config.Brand`.

**Does it cost performance?**

No. Nothing runs every frame while the player is on foot, and the update intervals are set in the config.

---

https://youtu.be/r4iglpTqPO0