Features
One command opens everything: /chud. Inside are four tabs — Crosshair, Hit Effects, Scoreboard and Marketplace — plus profiles, share codes and a backup code. Every setting belongs to the player and follows them across characters; what they are allowed to change belongs to you, through config/features.lua.
Every feature ships off. A fresh player has a clean screen until they turn something on, unless you change that in config/defaults.lua — with one exception: a default-on crosshair only reaches a player once they have a database row, which happens at their first kill, death or crosshair toggle.
The Menu and the Keybind
/chud | Opens the menu. Unrestricted — every player can use it. There is no keybind for opening it |
| F9 | Toggles the crosshair on and off. Registered through FiveM's own keybind screen, so players can rebind it |
| Escape | Closes the menu and saves |
The F9 default only reaches players who have never bound that key themselves; changing F5Cfg.Keybind later does not re-bind anyone. With EnableCrosshair = false the binding stays visible in FiveM's settings and does nothing.
It disappears while the pause menu is open, and while any resource holds NUI focus — including other scripts' menus, not just this one.
Crosshair
Eleven shapes: cross, dot, circle, square, plus, cross+dot, T-shape, chevron, diamond, triangle and corners — each with size, thickness, gap, colour, alpha, an optional outline and an optional centre dot. 64 presets in nine categories are one click away, and any of them can be tuned afterwards.
Dynamic spread
The classic FPS behaviour: the gap opens while the player moves and fires, then closes again.
| Setting | Effect |
|---|---|
dynamicShooting | How far the gap opens while shooting — and it stays at 70 % of that for 200 ms after the last shot |
dynamicMovement | How far it opens while moving faster than a walk |
dynamicRecovery | How quickly it closes again |
The spread is recalculated about 60 times a second and only pushed to the screen when it actually moved, so it costs nothing while standing still.
Aiming visibility
Two independent switches, plus a dimmer:
- Show only while aiming — no crosshair from the hip.
- Hide while aiming — hand the screen over to the weapon's own sight.
- ADS opacity — keep the crosshair while aiming, at reduced opacity.
Aiming counts as free-aim, the aim camera, the aim control being held, or aiming from cover.
Looks
| Feature | What it does |
|---|---|
| Glow | A soft halo, either in the crosshair's own colour or a colour of its own |
| Rainbow | Cycles the colour continuously, at a speed the player sets |
| Animation | pulse, rotate or breathe |
| HP colour | The crosshair shifts between two colours as the player's health drops |
| Hit animation | The crosshair pulses on every hit — scale and duration are configurable |
The colour is derived from GTA's 100–200 ped health range. A framework that raises maximum health will skew the percentage.
Per-weapon crosshairs
A player can save a different crosshair for a category — pistols, SMGs, rifles, shotguns, snipers, heavy, melee, throwables — or for a single weapon, and the HUD swaps automatically as they change weapon (checked five times a second).
Three modes: the default crosshair, a selection of categories, or all weapons at once. Saving to a category writes that crosshair to every weapon in it, so a weapon that is in no category simply uses the player's normal crosshair. Categories and their contents are yours to edit in config/weapons.lua.
Custom image crosshair
Instead of a shape, a player can use a picture — uploaded from their PC, or fetched from an https:// URL — with its own size, opacity and rotation. When it is active it replaces the shape entirely.
| Rule | Value |
|---|---|
| Upload size | Up to 512 KB encoded, roughly a 384 KB source file |
| Accepted uploads | PNG, JPEG, WEBP, SVG |
| URL | https:// only, 10–500 characters |
| Blocked URLs | Credentials in the address, IP literals, localhost, private and .local / .internal / .home names |
| Host whitelist | Off by default (any public HTTPS host); Validation.CustomImage.allowedUrlHosts restricts it, matched exactly with no wildcards |
An oversized file is refused in the menu rather than silently dropped on save. Uploaded pictures are stored in their own database column, so a normal login does not have to fetch them.
Some hosts reject requests from the CitizenFX client outright, which shows up as a URL crosshair that simply never appears. If a URL image does not load in game but works in a browser, that host is the reason — try another one.
The image travels with a player's profiles, but not with share or backup codes: those carry the size, opacity, rotation and URL only. Publishing an image crosshair to the marketplace can be blocked with MarketplaceSections.publishCustomImage.
Hit Effects
Seven independent effects, each with its own switch, colours and timing.
| Effect | Fires when | Notes |
|---|---|---|
| Hitmarker | Any hit you land | Optional sound, at most one per victim every 20 ms |
| Hit particles | Any hit you land | A GTA particle burst on the victim — 10 to choose from, two of them colourable |
| Damage numbers | A hit that does measurable damage | Floating number at the victim, with a separate colour and multiplier for headshots |
| Killmarker | A hit that kills | Optional sound and an optional word next to the mark |
| Headshot marker | A headshot that does not kill | A killing headshot shows the killmarker instead |
| Kill flash | A kill | A brief full-screen tint, gold for a headshot |
| Hit direction | You take damage | An arc pointing at your attacker, from their position relative to your heading |
17 effect presets in five families (FPS Classics, Immersive, Minimal, Flashy, Full Package) set several of these at once — "CS2 Competitive", "Apex Legends", "Tactical Realism" and so on.
How damage is measured
This is worth knowing, because it is what makes the numbers trustworthy.
- Against NPCs, your own client watches the victim's health and reports the drop it actually observed. A hit with no observed drop shows no number, and the killing blow deliberately shows none either — that is the killmarker's job.
- Against players, your client never guesses. The victim's client measures its own health loss and reports it back to you through the server. That is why damage numbers in PvP match what really happened, even with packet loss on your side.
A headshot is recognised from the bone the victim was last damaged on.
Scoreboard
Killstreak
A streak is a run of kills with no more than timeout between them (15 seconds by default), and by default it resets on death.
Each threshold is an exact match: with tiers at 6 and 8, a seventh kill announces nothing — the counter still moves. Nine tiers ship, from DOUBLE KILL at 2 to BEYOND GODLIKE at 20, each with its own colour, icon and sound, and the top ones with a screen effect.
The tier list is yours, not the player's: it always comes from config/defaults.lua, on every save and on every imported share code. Players can pick a different icon per tier, mute the sounds, and restyle the announcement — five styles, four positions, or a position they drag themselves.
The live counter is separate: it appears after a configurable number of kills, sits wherever the player puts it, and fades after a stretch with no kills.
K/D HUD
Kills, deaths and ratio, in eight styles and four corners (or dragged anywhere), with per-stat icons, colours, labels, dividers and an animation that plays when a stat changes.
- Stats live per account, not per character — the same K/D on every character a player has.
- A player can reset their own K/D from the menu.
- What counts as a kill is your call: see
CountNPCKills.
With CountNPCKills = false, a kill is only recorded when the victim is a player and that player has their K/D display switched on. Players who dislike the display stop accumulating stats. With CountNPCKills = true everything is recorded regardless.
Kill feed
Recent kills and deaths, in five styles, four corners or a dragged position, with a scale, a duration, up to ten entries, six entry animations, corner radius, an accent bar and an optional glow.
Each entry can show the weapon icon, the weapon name, a headshot marker, the distance, the players' server ids, a timestamp and Steam avatars.
| Who sees what | |
|---|---|
| Your kills | Everyone (each client decides whether to display them) |
| Your deaths to a player | You, and the killer as their kill |
| Your death with no killer — a fall, drowning, a crash | Only you, credited to NPC, and only when ShowNPCKillsInFeed is on |
Show all kills is off by default: the feed then shows only the player's own kills and deaths. Turning it on shows everyone else's kills too.
Weapon icons come from images/icons/, matched to the weapon name; the weapon's label comes from your framework's weapon list. Avatars need a steam_webApiKey in server.cfg.
Profiles
Up to five named profiles per player (configurable), each holding a complete HUD. A player can save, load and delete them; there is no rename.
The menu's reset restores every HUD setting to your defaults. Kills and deaths live in their own columns and are untouched — a player clears those with the separate K/D reset.
Changing a slider does not just change the live HUD — it also rewrites the profile the player currently has active. There is no "unsaved changes" state to lose.
Applying a marketplace listing, importing a share code or restoring a backup switches the player back to Default.
Share Codes and Backup Codes
Share codes are for giving one part of your HUD to someone else — three separate kinds, each with its own prefix and its own on/off switch:
| Code | Carries |
|---|---|
CR_… | The whole crosshair — shape, size, colours, outline, dynamic spread, glow, rainbow, animation, HP colour, the on/off flag — plus the custom image's settings and every per-weapon crosshair |
FX_… | The hit effects |
SB_… | The scoreboard: killstreak, K/D HUD and kill feed styling |
The only thing a crosshair code leaves out is the bytes of an uploaded picture. Everything else travels, including the custom image's switch, source and URL — so importing one replaces those settings with the sender's, and a picture the importer uploaded themselves is erased rather than preserved. If the sender had an uploaded image switched on, the importer ends up with the toggle on and nothing to draw.
An image saved under a named profile other than Default survives there, because importing a code switches the player back to Default.
Backup codes (F5B_…) are the other half of the idea: one code holding the player's entire HUD — every tab — so they can restore it after a wipe or move it to another server running the script. They carry the custom image's settings but not the picture itself, and they do not carry profiles or K/D.
Every imported code is re-validated on the server, so a hand-edited code cannot smuggle in an illegal value.
Marketplace
A crosshair marketplace inside the menu: players publish their own crosshairs, browse and search everyone else's, apply them in one click, like them, and look at what a given author has published. Moderators get a tab of their own for hiding, deleting and banning.
Full detail on Marketplace.
What Players Cannot Change
Worth stating plainly, because it is what makes the HUD safe to hand out:
- Killstreak tiers, their names, sounds and thresholds.
- Any value outside the ranges in
config/limits.lua— everything is clamped server-side on save. - Any section you have switched off — the server pins or clears those fields whatever the client sends.
- Their own kills and deaths: those move only through the kill and death events, one at a time, rate-limited.
See Also
- Configuration — every setting behind these features
- Marketplace — publishing, applying and moderation
- Permissions — giving different groups different menus
- NUI & Assets — sounds, fonts and weapon icons
- Troubleshooting — when something does not show up