beyond_hud

Installation Guide

This guide will walk you through installing Beyond HUD on your FiveM server. Beyond HUD requires Beyond Lib as a dependency.

Prerequisites

  • FiveM Server: Latest recommended version
  • Database: MySQL/MariaDB with oxmysql
  • Framework: ESX or QB-Core
  • Admin Access: Server file system access

Step 1: Install Beyond Lib

Beyond HUD requires Beyond Lib as a dependency. Install it first:

➡️ Install Beyond Lib

Step 2: Download Beyond HUD

  1. Download Beyond HUD from your purchase location
  2. Extract the files to get the beyond_hud folder

Step 3: Install Files

  1. Copy the beyond_hud folder to your server’s resources directory:

    Server Directory
    resources/
├── beyond_lib/     # Must be installed first
├── beyond_hud/     # Your new HUD resource
└── ... other resources

  2. Add to server.cfg (must be after beyond_lib):

    server.cfg
    ensure oxmysql
ensure es_extended    # OR qb-core
ensure beyond_lib     # Should already be installed
ensure beyond_hud

Step 4: Configure Modules

Beyond HUD automatically loads the core modules for Player, Chat and Vehicles, but you can disable them if you do not want to use them in the config. The same goes for the Notifications, Progress Bar and Chat modules. While these optional modules are not required to use Beyond HUD, they are enabled by default and require minor setup to use.

Below are setup guides for the framework scripts, for guides on how to set up optional modules for partner resources, check out the Compatibility Guide.

 

Notifications

QB-Core

In your server, head to the qb-core resource folder and open the functions.lua file in the client folder.

On line 155, there is a function called QBCore.Functions.Notify that is used to display notifications, let’s implement Beyond’s Notification event here with a fallback to the framework.

qb-core/client/functions.lua
function QBCore.Functions.Notify(text, texttype, length, icon)
    if GetResourceState('beyond_hud') == 'started' then
        --[[
            The notifications can be disabled in the HUD config.
            This enabled local variable allows us to disable it without needing to change this code later.
            Allowing this function to fallback to the default notification where necessary.
        --]]
        local enabled = exports['beyond_hud']:HUD().notify({ 
            title = '', 
            text = text, 
            type = texttype, 
            duration = length, 
            icon = icon
        }) 
        if enabled then
            return
        end
    end
 
    local message = {
        action = 'notify',
        type = texttype or 'primary',
        length = length or 5000,
    }
 
    if type(text) == 'table' then
        message.text = text.text or 'Placeholder'
        message.caption = text.caption or 'Placeholder'
    else
        message.text = text
    end
 
    if icon then
        message.icon = icon
    end
 
    SendNUIMessage(message)
end

ESX

In your server, head to the esx_notify resource folder in the [core] directory and open the Notify.lua file.

On line 6, there is a function called Notify that is used to display notifications, let’s implement Beyond’s Notification event here with a fallback to the framework.

esx_notify/Notify.lua
---@param notificatonType string the notification type
---@param length number the length of the notification
---@param message any the message :D
local function Notify(notificatonType, length, message)
    if GetResourceState('beyond_hud') == 'started' then
        local enabled = exports.beyond_hud:HUD().notify({ 
            title = '', 
            text = message, 
            type = notificatonType, 
            duration = length, 
        }) 
        if enabled then
            return
        end
    end
 
    if Debug then
        print(("1 %s"):format(tostring(notificatonType)))
        print(("2 %s"):format(tostring(length)))
        print(("3 %s"):format(message))
    end
 
    if type(notificatonType) ~= "string" then
        notificatonType = "info"
    end
 
    if type(length) ~= "number" then
        length = 3000
    end
 
    if Debug then
        print(("4 %s"):format(tostring(notificatonType)))
        print(("5 %s"):format(tostring(length)))
        print(("6 %s"):format(message))
    end
 
    SendNuiMessage(json.encode({
        type = notificatonType,
        length = length,
        message = message or "ESX-Notify",
    }))
end

 

 

Progress Bar

QB-Core

In your server, head to the qb-core resource folder and open the functions.lua file in the client folder.

On line 182, there is a function called QBCore.Functions.Progressbar that is used to display progress bars, let’s implement Beyond’s Progress Bar event here with a fallback to the framework.

qb-core/client/functions.lua
function QBCore.Functions.Progressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop,
                                      propTwo, onFinish, onCancel)
    if GetResourceState('beyond_hud') == 'started' then
        --[[
            The progress bar can be disabled in the HUD config.
            This enabled local variable allows us to disable it without needing to change this code later.
            Allowing this function to fallback to the default progressbar where necessary.
        --]]
        local enabled = exports['beyond_hud']:HUD().progressBar({ 
            label = label, 
            duration = duration, 
            type = 'radial', -- 'bar' | 'radial' --
            cancellable = canCancel, 
            disabled = disableControls, 
            animate = { 
                dict = animation.animDict, 
                anim = animation.task or animation.anim, 
                flags = animation.flags, 
                props = { prop, propTwo }, 
                useTask = animation.task ~= nil, 
            }, 
            onComplete = function()
                if onFinish then
                    onFinish() 
                end
            end, 
            onCancel = function()
                if onCancel then
                    onCancel() 
                end
            end
        }) 
        if enabled then
            return
        end
    end
 
    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

ESX

In your server, head to the esx_progressbar resource folder in the [core] directory and open the Progress.lua file.

On line 35, there is a function called Progressbar that is used to display progress bars, let’s implement Beyond’s Progress Bar export here with a fallback to the framework.

esx_progressbar/Progress.lua
---@param message string
---@param length? number Timeout in milliseconds
---@param Options? ProgressBarOptions
---@return boolean Success
local function Progressbar(message, length, Options)
    if GetResourceState('beyond_hud') == 'started' then
        local animation = Options and Options.animation or nil
        local onFinish = Options and Options.onFinish or nil
        local data = { 
            label = message, 
            duration = length, 
            type = 'bar', 
        } 
        if animation then
            if animation.dict then
                data.animate.dict = animation.dict 
            end
            if animation.lib then
                data.animate.anim = animation.lib 
            end
        end
        if onFinish then
            data.onComplete = function()
                if onFinish then
                    onFinish() 
                end
            end
        end
        local enabled = exports['beyond_hud']:HUD().progressBar(data) 
        if enabled then
            return true
        end
    end
 
    if CurrentProgress then
        return false
    end
    CurrentProgress = Options or {}
    if CurrentProgress.animation then
        if CurrentProgress.animation.type == "anim" then
            ESX.Streaming.RequestAnimDict(CurrentProgress.animation.dict, function()
                TaskPlayAnim(ESX.PlayerData.ped, CurrentProgress.animation.dict, CurrentProgress.animation.lib, 1.0, 1.0,
                    length, 1, 1.0, false, false, false)
                RemoveAnimDict(CurrentProgress.animation.dict)
            end)
        elseif CurrentProgress.animation.type == "Scenario" then
            TaskStartScenarioInPlace(ESX.PlayerData.ped, CurrentProgress.animation.Scenario, 0, true)
        end
    end
    if CurrentProgress.FreezePlayer then
        FreezeEntityPosition(ESX.PlayerData.ped, CurrentProgress.FreezePlayer)
    end
    SendNUIMessage({
        type = "Progressbar",
        length = length or 3000,
        message = message or "ESX-Framework",
    })
    CurrentProgress.length = length or 3000
    CreateThread(startProcessing);
    return true;
end

Below the function above, on line 99, there is a function called CancelProgressbar that is used to cancel the progress bar, let’s implement Beyond’s Cancel Progress Bar export here with a fallback to the framework.

esx_progressbar/Progress.lua
local function CancelProgressbar()
    if GetResourceState('beyond_hud') == 'started' then
        exports['beyond_hud']:HUD().cancelProgressBar() 
        return
    end
 
    if not CurrentProgress then
        return
    end
    SendNUIMessage({
        type = "Close",
    })
    ClearPedTasks(ESX.PlayerData.ped)
    if CurrentProgress.FreezePlayer then
        FreezeEntityPosition(ESX.PlayerData.ped, false)
    end
    if CurrentProgress.onCancel then
        CurrentProgress.onCancel()
    end
    CurrentProgress.canceled = true
    CurrentProgress.length = 0
    CurrentProgress = nil
end

Step 5: Verify Installation

  1. Start your FiveM server
  2. Check console for startup messages

Check Console

Look for these success messages:

FiveM Console
[beyond_lib] Successfully initialized for [ESX/QB-Core]
[beyond_hud] HUD system initialized successfully
[beyond_hud] Chat system loaded

  1. Join your server to test:

    • Health and other information such as hunger, thirst, and such should appear when neccessary.
    • Chat should work with Beyond HUD’s theming and chat system.
    • Press O to open settings menu.
    • Top Right corner of the screen should show the city ID and current server logo or Beyond Logo if you have not changed it yet.

Beyond HUD is now installed and ready to use, it’s core modules for player, chat and vehicles are ready to use.

Common Issues

Here are some common issues that you may encounter when installing Beyond HUD if you missed a step or tried insstalling on your own.

Resource Won’t Start

Problem: beyond_hud fails to start

Solutions:

  • Ensure beyond_lib is installed and started first
  • Check oxmysql is running
  • Verify file permissions are correct

Database Errors

Problem: Database connection errors

Solutions:

  • Verify oxmysql is configured correctly
  • Check database credentials in your framework
  • Ensure MySQL/MariaDB is running
  • Ensure beyond_lib is installed and started first

Framework Not Detected

Problem: Framework not recognized

Solutions:

  • Ensure your framework (ESX/QB-Core/Qbox) is properly installed and supported
  • Check Beyond Lib installation
  • Verify framework resource names in server.cfg

Next Steps

Installation complete! Now that we know the HUD is working, let’s configure Beyond HUD for your server:

➡️ Configuration Guide

Need help with a specific feature? Check the Features Guide

PreviousGetting Started
NextGuide