> For the complete documentation index, see [llms.txt](https://bl-scripts-1.gitbook.io/bl-scripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bl-scripts-1.gitbook.io/bl-scripts-docs/bl-hud-v1.md).

# BL HUD v1

## Overview

BL HUD v1 is a redesign of our original HUD system for FiveM Roleplay servers.

The resource replaces the default GTA HUD with multiple modern layouts, a synced minimap system, driving interface, money and ammo displays, built-in settings, stress, nitro, cruise control, and optional server logging.

Built for QB-Core, Qbox, and ESX with full auto-detection support.

### Features

* Three HUD layouts (Rings, Bars, Orbit)
* Custom square and circle minimap support
* Driving HUD with speed, RPM, fuel, gear, seatbelt, nitro, and cruise indicators
* Money HUD (cash and bank)
* Ammo display when armed
* Low health visual effects
* Hunger and thirst warning indicators
* Stress system with configurable gain and decay
* Nitro system with heat and overheat protection
* Cruise control system
* Player settings menu (F9)
* HUD toggle (F10)
* Multi-framework support (QB, Qbox, ESX, auto detect)
* Multi-notify support (bl\_notify, ox\_lib, qb, esx, auto)
* Multi-fuel support (ox\_fuel, qb-fuel, LegacyFuel, cdn-fuel, native, auto)
* Multi-language support (en, de, es, fr)
* Configurable colours and layout positions
* Optional Discord, Fivemerr, and Fivemanage logging
* Version checking support
* Console detection logging

## Requirements

### Required

* FXServer
* Lua 5.4
* bl\_lib
* Asset Pack

```lua
dependency '/assetpacks'
```

### Optional

* qb-core
* qbx\_core
* es\_extended
* bl\_notify
* ox\_lib
* ox\_fuel
* qb-fuel
* LegacyFuel
* cdn-fuel
* esx\_status

{% hint style="info" %}\
ESX users require a stress status for stress integration.\
{% endhint %}

## Installation

### Quick Start

#### 1. Add the Resource

Add the resource to your server.

#### 2. Configure

Edit:

```
config/config.lua
```

#### 3. Add to server.cfg

```cfg
ensure bl_lib
ensure bl_hud_v1
```

Optional:

```cfg
ensure bl_notify
```

#### 4. Disable Existing HUDs

Disable resources such as:

* qb-hud
* qbx\_hud
* esx-hud
* Any custom HUD resource

#### 5. Restart Server

The resource automatically detects available systems.

Example:

```
[bl_hud_v1] Framework Detected: Qbox
[bl_hud_v1] Notify Detected: bl_notify
[bl_hud_v1] Fuel Detected: ox_fuel
```

## Usage

The HUD loads automatically when a player joins.

Players can customize settings using F9.

### Keybinds

| Key        | Action            |
| ---------- | ----------------- |
| F9         | Open HUD Settings |
| F10        | Toggle HUD        |
| Left Shift | Nitro Boost       |
| U          | Cruise Control    |

{% hint style="info" %}\
Keybinds can be changed through FiveM Key Bindings.\
{% endhint %}

### Settings Menu

Players can configure:

* HUD Style
* Minimap Shape
* HUD Scale
* HUD Opacity
* Speed Unit
* Money HUD Visibility
* Reset to Defaults

## HUD Styles

### Style A — Rings

Classic BL circular design.

SVG-based circular stat rings displaying:

* Health
* Armor
* Hunger
* Thirst
* Stress
* Stamina
* Voice
* Oxygen

### Style B — Bars

Horizontal pill-style bars displaying live values.

### Style C — Orbit

Stats are positioned around the minimap using configurable slots.

Example:

```lua
Config.HudLayout.styleC_OrbitSlots = {
    health  = 'tl',
    armor   = 'tc',
    stress  = 'tr',
    hunger  = 'ml',
    thirst  = 'bl',
    stamina = 'mr',
    voice   = 'br',
    oxygen  = 'bc',
}
```

Available Slots:

```
tl tc tr
ml    mr
bl bc br
```

Each slot may only be used once.

## Minimap

### Available Shapes

#### Square

```lua
Config.Minimap.shape = 'square'
```

Uses:

```
stream/squaremap.ytd
```

#### Circle

```lua
Config.Minimap.shape = 'circle'
```

Uses:

```
stream/circlemap.ytd
```

### Debugging

Enable minimap diagnostics:

```lua
Config.Minimap.debugShape = true
```

## Driving HUD

The Driving HUD automatically appears while inside a vehicle.

Displays:

* Speed
* Speed unit (KM/H or MPH)
* Gear
* RPM
* Fuel
* Seatbelt status
* Engine condition
* Nitro heat
* Cruise control status

### Fuel Detection

```lua
Config.Fuel.provider = 'auto'
```

Supported:

* auto
* native
* ox\_fuel
* qb-fuel
* cdn-fuel

Detection Order:

```
ox_fuel
↓
qb-fuel / LegacyFuel
↓
cdn-fuel
↓
native
```

## Notifications

### Supported Systems

* bl\_notify
* ox\_lib
* qb
* esx
* auto

Configuration:

```lua
Config.Notify = 'auto'
```

### Notification Events

* HUD Ready
* Seatbelt Toggle
* Vehicle Damage Warnings
* Nitro Overheat
* Cruise Speed Warnings

### Export

```lua
exports['bl_hud_v1']:Notify(
    'Message',
    'success',
    5000
)
```

### Event

```lua
TriggerEvent(
    'bl_hud:client:Notify',
    'Message',
    'inform',
    5000
)
```

## Built-In Systems

### Stress

Stress increases from:

* High speed driving
* Shooting weapons
* Taking damage

Enable:

```lua
Config.Stress.enabled = true
```

### Nitro

Features:

* Fuel consumption
* Heat generation
* Overheat lockout
* Optional engine damage

Configuration:

```lua
Config.Nitro.enabled = true
Config.Nitro.key = 'LSHIFT'
```

### Cruise Control

Maintains current vehicle speed.

```lua
Config.Cruise.enabled = true
Config.Cruise.key = 'U'
Config.Cruise.minSpeedKmh = 35.0
```

### Stamina Exhaust

Prevents sprinting when stamina is depleted.

```lua
Config.StaminaHud.exhaustLockSprint = true
Config.StaminaHud.refillPerSecond = 12
```

## Server Logging

BL HUD v1 includes optional outbound logging for server owners.

### Supported Providers

* Discord
* Fivemerr
* Fivemanage

All providers are disabled by default.

Configuration file:

```lua
server/logging.lua
```

### Configuration

```lua
HudLogConfig = {
    MinLevel = 'info',

    Discord = {
        Enabled = false,
        WebhookUrl = '',
        BotUsername = 'HUD',
    },

    Fivemerr = {
        Enabled = false,
        ApiKey = '',
        ResourceTag = '',
    },

    Fivemanage = {
        Enabled = false,
        Mode = 'http',
        Dataset = 'bl_hud_v1',
        ApiKey = '',
        FallbackHttp = true,
    },
}
```

### Built-In Logged Events

* Resource startup detection
* adminheal command usage
* savehud command usage

### Custom Logging

```lua
exports['bl_hud_v1']:Log(
    'info',
    'Your message',
    {
        event = 'custom_event'
    }
)
```

### Recommended server.cfg Secrets

```cfg
set bl_hud_v1.extern_discord_webhook "https://discord.com/api/webhooks/..."
set bl_hud_v1.fivemerr_api_key "YOUR_FIVEMERR_KEY"

set FIVEMANAGE_LOGS_API_KEY "YOUR_FIVEMANAGE_KEY"
set bl_hud_v1.fivemanage_api_key "YOUR_FIVEMANAGE_KEY"
set bl_hud_v1.fivemanage_dataset "bl_hud_v1"
```

{% hint style="info" %}\
Store API keys and webhook URLs in server.cfg instead of resource files.\
{% endhint %}

## Configuration

Main configuration file:

```
config/config.lua
```

Includes:

* Framework detection
* Notify detection
* Fuel detection
* HUD styles
* Layout positions
* Minimap settings
* Stress settings
* Nitro settings
* Cruise settings
* Stamina settings
* Colours
* Localisation
* Version checking

## Files Structure

```
config/config.lua              → Main configuration

client/client.lua              → Main HUD logic
client/locale.lua              → Locale loader
minimap.lua                    → Minimap handling

server/server.lua              → Server logic
server/version.lua             → Version checking
server/console.lua             → Console output
server/logging.lua             → External logging

html/                          → NUI files
locales/                       → Translations
stream/                        → Minimap textures
```

## Troubleshooting

### HUD Not Showing

* Ensure bl\_lib is running
* Ensure no conflicting HUD resources are active

### Stats Not Updating

* Verify framework detection
* Manually configure Config.Framework

### No Notifications

* Verify notify system detection
* Ensure notify resource is started

### Incorrect Fuel System

* Verify fuel detection
* Manually configure Config.Fuel.provider

### Broken Circle Minimap

Verify:

```
stream/circlemap.ytd
```

Enable:

```lua
Config.Minimap.debugShape = true
```

### Logs Not Appearing

* Ensure provider Enabled = true
* Verify API keys and webhooks
* Check MinLevel filtering
* Verify outbound HTTP requests are allowed
* Ensure fmsdk starts before bl\_hud\_v1 when using SDK mode

### ESX Stress Not Working

Ensure:

```
esx_status
```

includes a stress status.

## Purchase Information

This script is free. To get it, please visit our official store.

## Support

Contact our support team on Discord for updates, help, or customization options.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bl-scripts-1.gitbook.io/bl-scripts-docs/bl-hud-v1.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.