API Reference & Exports

Beyond HUD provides a comprehensive API for developers to integrate with other resources. This documentation covers all available exports and their usage.

Basic Usage

Beyond HUD can be accessed by any resource that has access to the beyond_hud resource. You can access it by using its exports to cache the HUD object and use it in your resource or access a feature directly.

lua
-- Get the HUD API
local HUD = exports['beyond_hud']:HUD()
 
-- Use any HUD function
HUD.notify({
    title = "Success",
    text = "Action completed successfully!",
    type = "success"
})

HUD Visibility

HUD.visible(visible)

Control the overall visibility of the HUD.

lua
-- Hide the HUD
HUD.visible(false)
 
-- Show the HUD
HUD.visible(true)

Parameters:

• visible (boolean): Whether the HUD should be visible

Export: exports['beyond_hud']:Visible(visible)

Notifications

HUD.notify(notification)

Display a notification to the player.

lua
HUD.notify({
    title = "Bank Robbery",
    text = "A bank robbery is in progress at Fleeca Bank",
    type = "error",
    duration = 5000,
    icon = "bank",
    style = "background-color: red;"
})

Parameters:

• notification (table):
  • title (string): Notification title
  • text (string): Notification message
  • type (string, optional): Notification type (success, error, warning, info)
  • duration (number, optional): Display duration in milliseconds
  • icon (string, optional): Icon name or URL
  • style (string, optional): Custom CSS styling

Export: exports['beyond_hud']:Notify(notification)

Announcements

HUD.announce(announcement)

Display a server-wide announcement.

lua
HUD.announce({
    title = "Server Restart",
    text = "The server will restart in 5 minutes",
    duration = 10000
})

Parameters:

• announcement (table):
  • title (string): Announcement title
  • text (string): Announcement message
  • duration (number): Display duration in milliseconds

Export: exports['beyond_hud']:Announce(announcement)

Request Notifications

HUD.sendRequestNotify(requestNotification, callback)

Display an interactive request notification.

lua
HUD.sendRequestNotify({
    title = "Job Offer",
    text = "Would you like to accept this job?"
}, function(response)
    if response then
        print("Player accepted the job")
    else
        print("Player declined the job")
    end
end)

Parameters:

• requestNotification (table):
  • title (string): Request title
  • text (string): Request message
• callback (function): Function called with response (true/false)

Progress Bar

HUD.progressBar(data)

Display a progress bar with optional animations.

lua
HUD.progressBar({
    label = "Picking Lock",
    duration = 5000,
    type = "bar", -- or "radial"
    cancellable = true,
    disabled = {
        car = true,
        move = true,
        combat = true
    },
    onComplete = function()
        print("Lock picked successfully!")
    end,
    onCancel = function()
        print("Lock picking cancelled")
    end,
    animate = {
        dict = "mini@safe_cracking",
        anim = "dial_turn_anti_fast_1",
        props = {
            {
                model = "prop_tool_screwdriver",
                bone = 28422,
                offset = vector3(0.05, 0.0, 0.0),
                rotation = vector3(0.0, 0.0, 0.0)
            }
        }
    }
})

Parameters:

• data (table):
  • label (string): Progress bar label
  • duration (number): Duration in milliseconds
  • type (string): “bar” or “radial”
  • cancellable (boolean, optional): Whether the progress can be cancelled
  • disabled (table, optional): Controls to disable during progress
  • onComplete (function, optional): Function called on completion
  • onCancel (function, optional): Function called on cancellation
  • animate (table, optional): Animation configuration

Export: exports['beyond_hud']:Progress(data)

Cancel Progress Bar

HUD.cancelProgressBar()

Cancel any active progress bar.

lua
HUD.cancelProgressBar()

Export: exports['beyond_hud']:CancelProgress()

Text UI

HUD.textUI(data, options)

Display interactive text UI elements.

lua
-- Simple text UI
HUD.textUI("Press [E] to interact")
 
-- Advanced text UI with multiple options
HUD.textUI({
    {
        key = "E",
        label = "Open Door"
    },
    {
        key = "G",
        label = "Lock Door"
    }
}, {
    position = "center",
    style = "modern"
})

Parameters:

• data (string or table): Text content or interaction options
• options (table, optional): Display options and styling

Export: exports['beyond_hud']:showTextUI(data, options)

HUD.hideTextUI()

Hide the currently displayed text UI.

lua
HUD.hideTextUI()

Export: exports['beyond_hud']:hideTextUI()

HUD.isTextUIOpen()

Check if text UI is currently displayed.

lua
local isOpen = HUD.isTextUIOpen()
if isOpen then
    print("Text UI is currently displayed")
end

Returns: boolean - Whether text UI is open

Export: exports['beyond_hud']:isTextUIOpen()

Alert System

Timer Alert

HUD.timerAlert(text, color, textColor, seconds)

Display a timer alert with countdown.

lua
HUD.timerAlert("Server restart in:", "#ff0000", "#ffffff", 300)

Parameters:

• text (string): Alert text
• color (string): Background color
• textColor (string): Text color
• seconds (number): Countdown duration

Error Handling

Best Practices

lua
-- Always check if exports are available
if GetResourceState('beyond_hud') == 'started' then
    local success, result = pcall(function()
        return exports['beyond_hud']:HUD()
    end)
 
    if success then
        result.notify({
            title = "Success",
            text = "Beyond HUD is available"
        })
    else
        print("Error accessing Beyond HUD:", result)
    end
else
    print("Beyond HUD is not started")
end

Common Issues

Resource Not Found

lua
-- Check if resource exists
if GetResourceState('beyond_hud') ~= 'started' then
    print("Beyond HUD is not running")
    return
end

Export Not Available

lua
-- Verify export exists
local success, hud = pcall(function()
    return exports['beyond_hud']:HUD()
end)
 
if not success then
    print("Failed to get HUD export:", hud)
    return
end

Performance Considerations

Efficient Usage

lua
-- Cache the HUD object
local HUD = exports['beyond_hud']:HUD()
 
-- Use in loops efficiently
for i = 1, 10 do
    -- Good: Use cached object
    HUD.notify({
        title = "Item " .. i,
        text = "Processing item " .. i
    })
end

Avoid Spam

lua
-- Debounce notifications
local lastNotification = 0
local debounceTime = 1000 -- 1 second
 
CreateThread(function()
    while true do
        local currentTime = GetGameTimer()
        if currentTime - lastNotification > debounceTime then
            HUD.notify({
                title = "Update",
                text = "Regular update message"
            })
            lastNotification = currentTime
        end
        Wait(100)
    end
end)