Installation

Guide for installing NC-HUD on your FiveM server.

Prerequisites

FiveM Server
ox_lib (latest version)
One of: QBCore, QBox, ESX, Ox Core, or Standalone

Step 1: Download

Clone or download from GitHub:

git clone https://github.com/noxcore/nc-hud.git

Or download the latest release.

Step 2: Install Dependencies

Ensure ox_lib is installed:

ensure ox_lib

Step 3: Add Resource

Place the nc-hud folder in your server's resources directory
Add to your server.cfg:

ensure ox_lib
ensure nc-hud

⚠️ Important: nc-hud must start AFTER ox_lib

Step 4: Configure

Edit shared.lua to match your server environment. Framework is auto-detected.

Key settings to check:

Config.FuelResource — Your fuel system
Config.VoiceResource — Your voice system
Config.DeathResource — Your death detection system
Config.Keybinds — Keybind preferences

See the Configuration guide for all options.

Step 5: Build UI (optional)

The resource ships with a pre-built UI in ui/dist/. If you want to modify the React source:

cd nc-hud/ui
pnpm install
pnpm run build

Step 6: Restart Server

refresh
ensure nc-hud

File Structure

nc-hud/
├── shared.lua              # Configuration (editable)
├── fxmanifest.lua          # Resource manifest
├── framework/              # Framework adapters (editable)
│   ├── qb.lua              # QBCore
│   ├── qbx.lua             # QBox
│   ├── esx.lua             # ESX
│   ├── ox.lua              # Ox Core
│   └── standalone.lua      # Standalone
├── modules/                # Client modules (editable)
│   ├── hud.lua             # Core HUD display toggle
│   ├── speedometer.lua     # Vehicle data & indicators
│   ├── playerstatus.lua    # Health, armor, hunger, thirst, etc.
│   ├── playerinfo.lua      # Server ID, time, job, money
│   ├── minimap.lua         # Circular minimap overlay
│   ├── compass.lua         # Heading & postal codes
│   ├── weapon.lua          # Weapon name, ammo, stungun
│   ├── settings.lua        # Settings panel & KVP persistence
│   └── themes.lua          # Theme registration & broadcasting
├── data/
│   ├── postals.json        # Postal code coordinates
│   └── resolutions.lua     # Screen resolution presets
├── util/
│   └── client.lua          # Utility functions
├── stream/                 # Minimap assets (.ytd, .gfx)
└── ui/                     # React UI (Vite + pnpm)
    ├── src/                # Source code (editable)
    └── dist/               # Built output

All files are open source (GPL v3) and fully editable.

Troubleshooting

HUD not appearing

Check if ox_lib is running
Verify resource order in server.cfg
Check server console for errors

Fuel not displaying

Verify Config.FuelResource in shared.lua
Check that your fuel resource is running

Minimap scale issues

Adjust Config.Minimap.circleMapScale in shared.lua
Check data/resolutions.lua for your screen resolution

Last updated: February 17, 2026