Requirements

Installation Steps

1. Download and extract the resource.
2. Make sure the folder is named exactly JR_Hud.
3. Copy the folder into your server's resources directory.
4. Add the following line to server.cfg:

ensure JR_Hud

1. Start JR HUD after your framework and any optional resources you want to integrate.

QBCore example:

ensure qb-core
ensure pma-voice
ensure JR_Hud

ESX example:

ensure es_extended
ensure esx_status
ensure pma-voice
ensure JR_Hud

1. Restart the server or run restart JR_Hud from the server console.

After installation, load a character and test the HUD both on foot and inside a vehicle.

Updating

Before installing a new version, keep a copy of your config.lua and any custom images. Replace the complete resource and then reapply only your custom configuration.

If you use the Cfx Asset Escrow processed version, do not remove the .fxap file.

Usage

Display Modes

Players can select one of two display modes from /hud:

The oxygen indicator tracks the player's remaining underwater time. In automatic mode it appears while diving. In always-visible mode, it can remain on screen when enabled by the player.

Customization Menu

Run /hud to open the customization menu. While the menu is open, all HUD sections are temporarily displayed so they can be configured even when the player has no armor, weapon, or vehicle.

The menu allows players to change:

• Visible elements.
• Individual color of every status card.
• Weapon HUD color.
• Main CarHUD color.
• Global interface scale.
• Status card and CarHUD size.
• Opacity and fill intensity.
• Spacing between status cards.
• Compact, normal, and large presets.
• Position or reset state of every HUD section.

Changes are previewed immediately. Select Save Changes to keep them. Closing the menu without saving restores the previous configuration.

Position Editor

Use /hudedit or press F6 to move HUD elements directly with the mouse. Every available section is displayed while editing.

Save the layout when finished. Positions are stored locally for that player.

CarHUD

The CarHUD appears when the player enters a vehicle and displays:

• Current speed and gear.
• Fuel level and engine condition.
• Seatbelt state.
• Headlights and high beams.
• Handbrake state.
• Engine on or off.
• Speed limiter state.
• Current street.

The speedometer arc fills progressively according to the vehicle's actual speed.

Cinematic Mode

Use /cinematico or press F10 to toggle cinematic letterbox bars. Cinematic mode does not hide the HUD and is intended for roleplay scenes, videos, and screenshots.

Configuration

The main configuration is located in config.lua. Most visual settings are handled through /hud and saved separately for each player.

Framework

Config.Framework = 'auto'

Available values:

• auto: automatically detects QBCore or ESX.
• qbcore: forces QBCore.
• esx: forces ESX.
• standalone: runs without a framework.

Server Logo

Config.Logo = {
    enabled = true,
    image = 'img/logo.png',
    width = 92,
    opacity = 1.0,
}

You can use a local image from html/img or a public HTTPS URL. To replace the included logo, replace html/img/logo.png while keeping the same filename, or set a different path in Config.Logo.image.

Minimap

Config.Minimap = {
    onlyInVehicle = true,
    lockCompact = true,
    hideDefaultHealthArmor = true,
    moveUpForStatus = true,
    yOffset = 0.065,
}

• onlyInVehicle: hides the minimap while the player is on foot.
• lockCompact: prevents the radar from expanding into the large map mode.
• hideDefaultHealthArmor: hides GTA's original health and armor bars.
• yOffset: adjusts the minimap's vertical position.

CarHUD

Config.CarHud.unit = 'kmh' -- kmh or mph
Config.CarHud.maxSpeed = 240
Config.CarHud.fuelSystem = 'auto'

The auto fuel mode searches for a supported fuel resource. If none is found, JR HUD uses the vehicle's native fuel level.

Seatbelt and Speed Limiter

Config.Seatbelt controls exit blocking and collision ejection. Config.SpeedLimiter defines the minimum activation speed and supported vehicle classes.

Integrations

All integrations are optional. JR HUD continues to work when they are not installed.

Frameworks

Fuel Systems

Automatic detection supports:

• lc_fuel
• LegacyFuel
• legacyfuel
• ox_fuel
• ps-fuel
• cdn-fuel

JR HUD only reads the fuel level. It never changes the value managed by the fuel resource.

For a different fuel system:

Config.CarHud.fuelSystem = 'custom'
Config.CarHud.customFuel = {
    resource = 'my_fuel',
    export = 'GetFuel',
    multiplier = 1.0,
    callback = nil,
}

Use multiplier = 100.0 when the export returns a value between 0.0 and 1.0.

Voice and Radio

When pma-voice is installed, the voice indicator automatically represents the configured proximity range. During radio transmission, it switches to the color configured in Config.Voice.radioColor.

Other voice or radio systems can update the state through the exports or events listed in the API section.

Gym or Stamina Systems

JR HUD does not add a separate gym progress card. An external skill can improve native stamina duration, and the result is displayed through the existing stamina indicator.

Example for vms_gym:

Config.StaminaIntegration.enabled = true
Config.StaminaIntegration.provider = 'export'
Config.StaminaIntegration.export = {
    resource = 'vms_gym',
    name = 'getSkill',
    argument = 'value',
    argumentValue = 'condition',
}

This integration only reads the skill value. It does not add or remove points from the external gym system.

Custom Weapons

JR HUD includes local images for 72 original weapons. For an addon weapon, place its image inside html/img and register the path:

Config.WeaponHud.customImages = {
    ['WEAPON_MY_WEAPON'] = 'img/my_weapon.png',
}

Commands and API

Commands

Command names and default keys can be changed in Config.Commands and Config.Keys. Players can also change their key bindings from GTA Settings → Key Bindings → FiveM.

Client Exports

Radio State

exports['JR_Hud']:SetRadioState(true, 7)
exports['JR_Hud']:SetRadioState(false, nil)

Weapon Fire Mode

exports['JR_Hud']:SetWeaponFireMode('BURST')
exports['JR_Hud']:SetWeaponFireMode(nil)

Stamina Skill

exports['JR_Hud']:SetStaminaSkill(72)
exports['JR_Hud']:SetStaminaSkill(nil)

The stamina skill value must be between 0 and 100. Sending nil returns control to the configured provider.

Client Events

TriggerEvent('JR_Hud:client:setRadioState', true, 7)
TriggerEvent('JR_Hud:client:setWeaponFireMode', 'BURST')
TriggerEvent('JR_Hud:client:setStaminaSkill', 72)

These exports and events must be called from client-side code.

Common Errors

The HUD Does Not Appear

• Confirm that the resource folder is named JR_Hud.
• Check that ensure JR_Hud exists in server.cfg.
• Start the HUD after your framework.
• Check both the F8 console and the server console.
• Make sure a character has been fully selected and loaded.

Hunger or Thirst Does Not Appear

• On QBCore, confirm that your framework updates metadata.hunger and metadata.thirst.
• On ESX, start esx_status before JR HUD.
• A custom needs system may require an adjustment in the editable bridge.

The Minimap Appears While on Foot

Confirm that Config.Minimap.onlyInVehicle = true, then restart the resource. If it still appears, another resource may be continuously calling DisplayRadar(true).

The Fuel Level Is Incorrect

• Verify the exact name of the fuel resource.
• Try selecting the provider directly in Config.CarHud.fuelSystem.
• For a custom resource, configure customFuel and check whether its export returns 0-100 or 0.0-1.0.

The Logo Does Not Appear

• Confirm that the image exists inside html/img.
• Use a path such as img/logo.png, not an absolute Windows path.
• Remote images must use a publicly accessible HTTPS URL.
• Check that Config.Logo.enabled = true.

The Keys Do Not Match the Config

FiveM key bindings can be changed by each player. Check GTA Settings → Key Bindings → FiveM. Changing Config.Keys updates the default binding but does not overwrite a binding already saved by the player.

The Menu Does Not Save Changes

Select Save Changes before closing the menu. Preferences are stored through the player's local KVP data and do not require SQL.

The HUD Appears During Character Selection

JR HUD waits for the framework to report that the player has loaded. Confirm that your multicharacter resource triggers the standard QBCore or ESX load and unload events.

The Problem Continues

Restart the resource, load a character again, and read the errors from the beginning. When requesting support, include:

• Framework and version.
• Voice and fuel resources in use.
• A screenshot or video of the issue.
• Complete F8 and server-console errors.
• Exact steps required to reproduce the problem.