beyond_hud

Configuration Guide

Beyond HUD offers extensive configuration options through multiple configuration files. This guide explains all available settings and their purpose.

Configuration Files

Beyond HUD uses two main configuration files:

  • config/_config.lua - Main HUD configuration and features
  • config/config.chat.lua - Chat system configuration

Main Configuration (_config.lua)

Basic Settings

beyond_hud/config/_config.lua
Config = {}
Config.ReinstallDatabase = false  -- Set to true to reinstall database tables
Config.Keymaps = {
    Settings = 'O',         -- Key to open settings menu
    ShowCityID = 'F10',     -- Key to show city ID
}

Options:

  • ReinstallDatabase - Recreates database tables on resource start
  • Keymaps.Settings - Key to open the HUD settings menu
  • Keymaps.ShowCityID - Key to display player coordinates

Hotkeys Display

Configure which hotkeys are shown in the HUD:

beyond_hud/config/_config.lua
Config.Hotkeys = {
    { key = Config.Keymaps.Settings, label = 'Settings' },
    { key = '`',                     label = 'Talk Range' },
    { key = 'T',                     label = 'Chat' },
    { key = 'M',                     label = 'Phone' },
}

Options:

  • key - The key to display
  • label - The description shown next to the key

Hide HUD Function

Custom logic to hide the HUD when needed:

beyond_hud/config/_config.lua
Config.ShouldHideHUD = function()
    -- Add custom logic here
    -- Example: return exports.randol_freecam:Active()
    return false
end

Purpose: Called every 500ms to determine if the HUD should be hidden. Use this for integrations with screenshot tools, freecam, or other resources.

Feature Configuration

Player Features

beyond_hud/config/_config.lua
Config.Features.Player = {
    Enabled = true,  -- Show player status (health, armor, etc.)
    Options = {
        TextUI3D = true,  -- Enable 3D text UI interactions
        ShowCompassForEmergencyServicesOnly = true,  -- Compass only for emergency services
        EmergencyServices = {
            'police',
            'ambulance',
        },
    },
}

Options:

  • Enabled - Toggle all player-related HUD elements
  • TextUI3D - Enable 3D text interactions in the world
  • ShowCompassForEmergencyServicesOnly - Restrict compass to emergency services jobs
  • EmergencyServices - List of job names considered emergency services

Voice System

beyond_hud/config/_config.lua
Config.Features.Player.Voice = {
    Custom = false,  -- Use custom voice system integration
    IsCustomRadioOn = function()
        -- Return true if radio is on
    end,
    GetCustomRadioChannel = function(pid)
        -- Return radio channel for player
    end,
    IsCustomRadioMuted = function()
        -- Return true if radio is muted
    end,
    GetCustomRadioPlayersInChannel = function(channel)
        -- Return players in radio channel
    end
}

Options:

  • Custom - Enable custom voice system integration
  • IsCustomRadioOn - Function to check if radio is active
  • GetCustomRadioChannel - Function to get player’s radio channel
  • IsCustomRadioMuted - Function to check if radio is muted
  • GetCustomRadioPlayersInChannel - Function to get players in channel

Vehicle Features

beyond_hud/config/_config.lua
Config.Features.Vehicle = {
    Enabled = true,  -- Show vehicle HUD when in vehicle
    FuelResource = false,  -- Name of fuel resource or false for built-in
    OwnedVehicleNames = false,  -- Show owned vehicle names
}

Options:

  • Enabled - Toggle all vehicle-related HUD elements
  • FuelResource - Name of fuel resource ('LegacyFuel', 'qb-fuel', etc.) or false for built-in
  • OwnedVehicleNames - Display custom names for owned vehicles

Electric Vehicles

Define which vehicles are electric:

beyond_hud/config/_config.lua
Config.Features.Vehicle.ElectricVehicles = {
    [`buffalo5`] = true,
    [`tezeract`] = true,
    [`surge`] = true,
    [`voltic`] = true,
    [`raiden`] = true,
    [`cyclone`] = true,
}

Purpose: Electric vehicles display battery percentage instead of fuel level.

Emergency Vehicles

Configure emergency vehicle detection:

beyond_hud/config/_config.lua
Config.Features.Vehicle.EmergencyVehicles = {
    POLICE = {
        [`police`] = true,
        [`police2`] = true,
        [`sheriff`] = true,
    },
    EMS = {
        [`ambulance`] = true,
        [`firetruk`] = true,
    }
}

Purpose: Emergency vehicles display additional information and features.

Custom Vehicle Integrations

beyond_hud/config/_config.lua
Config.Features.Vehicle.CustomSeatbelt = false
Config.Features.Vehicle.Seatbelt = function()
    -- Return seatbelt status
end
 
Config.Features.Vehicle.CustomNitrous = false
Config.Features.Vehicle.Nitrous = function()
    -- Return { level = 0, hasNitrous = false }
end
 
Config.Features.Vehicle.CustomCruise = false
Config.Features.Vehicle.Cruise = function()
    -- Return cruise control status
end

Options:

  • CustomSeatbelt - Enable custom seatbelt integration
  • Seatbelt - Function to get seatbelt status
  • CustomNitrous - Enable custom nitrous integration
  • Nitrous - Function to get nitrous level and availability
  • CustomCruise - Enable custom cruise control integration
  • Cruise - Function to get cruise control status

Notification System

beyond_hud/config/_config.lua
Config.Features.Notifications = {
Enabled = true,            -- Enable notifications
Type = 'default',          -- 'default', 'framework', or 'custom'
Announcements = 'default', -- 'default' or 'custom'
 
-- Custom notification handlers
CustomNotify = function(title, text, type, duration, position, style)
    -- Custom notification implementation
end,
CustomAnnounce = function(title, text, duration)
    -- Custom announcement implementation
end,
 
}

Options:

  • Enabled - Toggle notification system
  • Type - Notification handler type
    • 'default' - Built-in notifications
    • 'framework' - Use framework notifications
    • 'custom' - Use custom notification functions
  • Announcements - Announcement handler type
  • CustomNotify - Custom notification function
  • CustomAnnounce - Custom announcement function

Progress Bars

beyond_hud/config/_config.lua
Config.Features.ProgressBar = {
    Enabled = true,     -- Enable progress bars
    useRadial = false,  -- Use radial progress bars
}

Options:

  • Enabled - Toggle progress bar system
  • useRadial - Use circular progress bars instead of linear

Chat Features

beyond_hud/config/_config.lua
Config.Features.Chat = {
    Enabled = true,  -- Enable chat system
}

Options:

  • Enabled - Toggle chat system entirely

Chat Configuration (config.chat.lua)

Chat Types

beyond_hud/config/config.chat.lua
Config.Chats = {
    Type = 'Default', -- 'Default', 'Command-Only', or 'Modes'
}

Chat Types:

  • 'Default' - Standard proximity chat
  • 'Command-Only' - Only slash commands work
  • 'Modes' - Channel-based chat with job channels

Chat Ranges

beyond_hud/config/config.chat.lua
Config.Chats = {
    DefaultRange = 20.0,    -- Default chat range
    ShoutRange = 40.0,      -- Shout command range
    WhisperRange = 5.0,     -- Whisper command range
    EveryoneRange = -1,     -- Everyone command range (-1 = server-wide)
}

Options:

  • DefaultRange - Default chat distance in units
  • ShoutRange - /shout command distance
  • WhisperRange - /whisper command distance
  • EveryoneRange - /everyone command distance (-1 for server-wide)

Chat Display

beyond_hud/config/config.chat.lua
Config.Chats = {
    ShowServerMessages = true,  -- Show server messages
    ShowTimestamp = true,       -- Show message timestamps
    ShowPlayerCount = true,     -- Show player count
    MaxMessages = 100,          -- Maximum messages to keep
    FadeTimeout = 5000,         -- Message fade timeout (ms)
    EnableAnimations = true,    -- Enable chat animations
    EnableSounds = true,        -- Enable chat sounds
}

Chat Features

beyond_hud/config/config.chat.lua
Config.Chats = {
    EnableEmojis = true,     -- Enable emoji support
    EnableMentions = true,   -- Enable @mentions
    EnableLinks = true,      -- Enable clickable links
    EnableMarkdown = false,  -- Enable markdown formatting
    EnableRichText = false,  -- Enable rich text formatting
}

Spam Protection

beyond_hud/config/config.chat.lua
Config.SpamProtection = {
    Enabled = true,
    MaxMessages = 5,              -- Messages per timeframe
    TimeFrame = 10000,            -- Timeframe in milliseconds
    PunishmentDuration = 30000,   -- Punishment duration
    PunishmentMessage = 'You are being rate limited!',
}

Word Filter

beyond_hud/config/config.chat.lua
Config.WordFilter = {
    Enabled = false,
    Words = {},           -- List of filtered words
    Replacement = '***',  -- Replacement text
    BlockMessage = false, -- Block entire message if word found
}

Channel System

beyond_hud/config/config.chat.lua
Config.Channels = {
    {
        Name = 'police',
        DisplayName = 'Police',
        Icon = 'fas fa-shield-alt',
        Color = '#3b82f6',
        Jobs = { 'police' },
        OnDutyOnly = true,
        AdminLogging = true,
    },
}

Channel Options:

  • Name - Internal channel name
  • DisplayName - Display name for players
  • Icon - FontAwesome icon class
  • Color - Channel color (hex)
  • Jobs - Jobs that can access channel
  • OnDutyOnly - Require on-duty status
  • AdminLogging - Log messages to admin logs

Next Steps

Need full configuration examples? → Configuration Examples

Want to understand specific features? → Features Guide

Looking for API functions? → Exports Reference

PreviousInstallation
NextDefaults