🔧Installation

Follow the steps on this page in detail to get the HUD working correctly on your server, let's go through the steps!

First of all we want you to know that our script only supports the versions of the three most used frameworks, in previous versions it can be usable but we do not provide support since the development is focused on the updated versions of the ESX, QBOX and QBCore frameworks.

1. Resource Installation

The installation of the script is very simple. First of all, you will make sure you have the dependencies installed on your server.

⚠️Dependencies

Secondly, you are going to download the Key Master FiveM file and then unzip it. Next, you are going to drag the file to your server. When you have completed the process, you are going to go to the server.cfg file and make the following changes:

ESX

server.cfg

ensure oxmysql
ensure es_extended
ensure ox_lib
ensure pma-voice

ensure jgs-hud

QBCore

server.cfg

ensure oxmysql
ensure qb-core
ensure ox_lib
ensure pma-voice

ensure jgs-hud

Then, you must go to the Settings section to customize the hud to your liking. After that, you should remove the old hud scripts such as esx_notify, esx_hud, speedometer or qb-hud.

Notification System: You will have to replace some functions of your framework main script (es_extended or qb-core)

ESX

es_extended/client/functions.lua

function ESX.ShowHelpNotification(text, customKey)
    local key, textAfter = text:match('[~rgbycfnztopqsmld]*%[?([%a%d])%]?~?[~rgbycfnztopqsmld]*%s*(.*)$')
    return exports['jgs-hud']:ShowHelp(customKey or key, textAfter ~= '' and textAfter or text)
end

function ESX.ShowNotification(...)
    return exports['jgs-hud']:AddNotify(...)
end

local helpNotifications = {}

function ESX.HideUI()
    for text, key in pairs(helpNotifications) do
        exports['jgs-hud']:RemoveHelp(key)
        helpNotifications[text] = nil
    end
end

function ESX.TextUI(message)
    if helpNotifications[text] then return end
    local key, textAfter = text:match('[~rgbycfnztopqsmld]*%[?([%a%d])%]?~?[~rgbycfnztopqsmld]*%s*(.*)$')
    helpNotifications[text] = exports['jgs-hud']:CreateHelp(key or '', textAfter ~= '' and textAfter or text)
    return helpNotifications[text]
end

function ESX.ShowAdvancedNotification(sender, subject, msg, textureDict, iconType, flash, saveToBrief, hudColorIndex)
    local __type = textureDict and textureDict == 'CHAR_BANK_MAZE' and 'bank' or 'info'
    TriggerEvent('jgs:notification', msg, __type, sender, iconType, saveToBrief, flash, hudColorIndex)
end

QBCore

qb-core/client/functions.lua

function QBCore.Functions.Notify(...) 
    return exports['jgs-hud']:ShowNotification(...) 
end

qb-core/client/drawtext.lua

-- Replace: 
local function hideText()
    SendNUIMessage({
        action = 'HIDE_TEXT',
    })
end

local function drawText(text, position)
    if type(position) ~= 'string' then position = 'left' end

    SendNUIMessage({
        action = 'DRAW_TEXT',
        data = {
            text = text,
            position = position
        }
    })
end

-- By:
local helpNotifications = {}

local function hideText()
    for text, key in pairs(helpNotifications) do
        exports['jgs-hud']:RemoveHelp(key)
        helpNotifications[text] = nil
    end
end

local function drawText(text)
    if helpNotifications[text] then return end
    local key, textAfter = text:match('[~rgbycfnztopqsmld]*%[?([%a%d])%]?~?[~rgbycfnztopqsmld]*%s*(.*)$')
    helpNotifications[text] = exports['jgs-hud']:CreateHelp(key or '', textAfter ~= '' and textAfter or text)
    return helpNotifications[text]
end

qb-core/server/functions.lua

function QBCore.Functions.Notify(source, ...) 
    return exports['jgs-hud']:ShowNotification(source, ...) 
end

2. Progress System Installation

QBCore

If you are using the jgs-hud resource and want to ensure compatibility with both jgs-hud and the default progressbar, you need to replace the factory QBCore.Functions.Progressbar function with the updated version below.

1. Factory Function

This is the original QBCore.Functions.Progressbar function provided by default:

qb-core/client/functions.lua

function QBCore.Functions.Progressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop, propTwo, onFinish, onCancel)
    if GetResourceState('progressbar') ~= 'started' then error('progressbar needs to be started in order for QBCore.Functions.Progressbar to work') end
    exports['progressbar']:Progress({
        name = name:lower(),
        duration = duration,
        label = label,
        useWhileDead = useWhileDead,
        canCancel = canCancel,
        controlDisables = disableControls,
        animation = animation,
        prop = prop,
        propTwo = propTwo,
    }, function(cancelled)
        if not cancelled then
            if onFinish then
                onFinish()
            end
        else
            if onCancel then
                onCancel()
            end
        end
    end)
end

2. Updated Function

Replace the above function with the following code. This updated function supports both progressbar and jgs-hud resources:

qb-core/client/functions.lua

local DEFAULT_PROGRESS_TYPE = 'bar' -- | 'circle'

local function validateResource(resourceName, callback)
    if GetResourceState(resourceName):match('start') then
        return callback()
    end
    return error(string.format("%s needs to be started for QBCore.Functions.Progressbar to work", resourceName))
end

local function executeCallback(callback, ...)
    if not callback then return end
    callback(...)
end

function QBCore.Functions.Progressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop, propTwo, onFinish, onCancel)
    validateResource('jgs-hud', function()
        exports['jgs-hud']:addProgress(DEFAULT_PROGRESS_TYPE, label, duration, function(cancelled)
            executeCallback(cancelled and onCancel or onFinish)
        end)
    end)

    validateResource('progressbar', function()    
        exports['progressbar']:Progress({
            name = name:lower(),
            duration = duration,
            label = label,
            useWhileDead = useWhileDead,
            canCancel = canCancel,
            controlDisables = disableControls,
            animation = animation,
            prop = prop,
            propTwo = propTwo,
        }, function(cancelled)
            executeCallback(cancelled and onCancel or onFinish)
        end)
    end)
end

3. Explanation

1. Dual Compatibility: The updated function first checks if jgs-hud is started and uses it if available. If not, it defaults to progressbar.

2. Validation: The validateResource helper function ensures the required resources (jgs-hud or progressbar) are running before executing their respective logic.

3. Callbacks: The executeCallback function simplifies the handling of onFinish and onCancel logic.

4. Customization: The DEFAULT_PROGRESS_TYPE variable allows you to switch between progress types (e.g., bar or circle) when using jgs-hud.

4. Steps to Replace

1. Open the file where the original QBCore.Functions.Progressbar is defined.

2. Replace the original function with the updated function provided above.

3. Ensure both progressbar and jgs-hud are properly installed and configured in your server resources.

By making this change, your server will seamlessly support progress bars from both jgs-hud and progressbar resources!

ESX

1. Factory Function (ESX)

This is the original ESX.Progressbar function provided by default:

es_extended/client/functions.lua

---@param message string
---@param length? number Timeout in milliseconds
---@param options? ProgressBarOptions
---@return boolean Success Whether the progress bar was successfully created or not
function ESX.Progressbar(message, length, options)
    return IsResourceFound('esx_progressbar') and exports['esx_progressbar']:Progressbar(message, length, options)
end

2. Updated Function (ESX)

Replace the above function with the following code. This updated function supports both jgs-hud and esx_progressbar resources:

es_extended/client/functions.lua

local DEFAULT_PROGRESS_TYPE = 'bar' -- | 'circle'

local function validateResource(resourceName, callback)
    if GetResourceState(resourceName):match('start') then
        return callback()
    end
    return error(string.format("%s needs to be started for ESX.Progressbar to work", resourceName))
end

function ESX.Progressbar(message, length, options)
    local success = false

    validateResource('jgs-hud', function()
        exports['jgs-hud']:addProgress(DEFAULT_PROGRESS_TYPE, message, length, function()
            success = true
        end)
    end)

    validateResource('esx_progressbar', function()
        success = exports['esx_progressbar']:Progressbar(message, length, options)
    end)

    return success
end

3. Explanation

1. Dual Compatibility: The updated functions first check if jgs-hud is started and use it if available. If not, they default to progressbar or esx_progressbar.

2. Validation: The validateResource helper function ensures the required resources are running before executing their respective logic.

3. Customization: The DEFAULT_PROGRESS_TYPE variable allows you to switch between progress types (e.g., bar or circle) when using jgs-hud.

4. Steps to Replace

1. Open the file where the original QBCore.Functions.Progressbar or ESX.Progressbar is defined.

2. Replace the original function with the updated function provided above.

3. Ensure all relevant resources (jgs-hud, progressbar, or esx_progressbar) are properly installed and configured in your server resources.

By making these changes, your server will seamlessly support progress bars from jgs-hud, progressbar, and esx_progressbar resources!