Configuration

This page documents every setting in config.lua. This is the only file you need to edit to configure ARS Hud V3 for your server.

Framework Selection

Config.Framework = 'auto'

Controls which framework bridge to use. 'auto' detects in order: QBX, then QBCore, then ESX. Override if detection fails.

Value	Framework
'auto'	Auto-detect (default)
'qb'	QBCore
'qbx'	QBX (Qbox)
'esx'	ESX

HUD Display Settings

Config.LuaHudSettings = {
    client_info = {
        server_info = {
            showOnlinePlayers = true,
            name = '',
            image = 'logo.png',
        },
        extra_currency = {
            active = false,
        },
    },
    vehicle_info = {
        kmH = true,
    },
}

Setting	Type	Default	Description
client_info.server_info.showOnlinePlayers	boolean	true	Show player count on the HUD
client_info.server_info.name	string	''	Server name displayed on the HUD
client_info.server_info.image	string	'logo.png'	Server logo image filename
client_info.extra_currency.active	boolean	false	Show a second currency (black money, etc.)
vehicle_info.kmH	boolean	true	true for km/h, false for MPH

Money Settings

Config.MoneySettings = {
    isMoneyItem = false,
    itemName = 'cash',
    extra_currency = {
        type = 'item',
        name = 'black_money',
    },
}

Setting	Type	Default	Description
isMoneyItem	boolean	false	Treat cash as an inventory item instead of a bank account
itemName	string	'cash'	Item name when isMoneyItem is true
extra_currency.type	string	'item'	Extra currency source: 'item' or 'account'
extra_currency.name	string	'black_money'	Item or account name for the extra currency

Settings Menu

Config.ToggleSettingsMenu = {
    active = true,
    key = 'I',
    command = 'hudsettings',
}

Setting	Type	Default	Description
active	boolean	true	Enable the HUD settings menu
key	string|nil	'I'	Keybind to open settings. Set to nil to disable the keybind
command	string	'hudsettings'	Chat command to open settings

Seatbelt

Config.ToggleSeatBelt = {
    active = true,
    useBuiltin = false,
    key = 'B',
    ejectSpeed = 160,
    warning = true,
    warningChime = true,
    warningChimeInterval = 3.0,
}

Setting	Type	Default	Description
active	boolean	true	Enable the seatbelt system
useBuiltin	boolean	false	true reads seatbelt state from your framework only. false runs ARS HUD’s own seatbelt logic with ejection, warnings, and sounds
key	string	'B'	Keybind to toggle seatbelt
ejectSpeed	number	160	Speed threshold (in km/h or MPH) above which there is a chance to be ejected from the vehicle during a collision. Interpreted as km/h when vehicle_info.kmH is true, otherwise MPH
warning	boolean	true	Show a periodic reminder (every 30 seconds) when seatbelt is not worn
warningChime	boolean	true	Play a repeating audio chime while driving without a seatbelt
warningChimeInterval	number	3.0	Seconds between warning chime repetitions when not wearing a seatbelt

Note: The seatbelt system does not activate on motorcycles (class 8), bicycles (class 13), or boats (class 14). Ejection requires a collision with sufficient force and sudden deceleration. The chance of ejection increases with speed above the threshold.

Important: If you are using another seatbelt script (such as from your framework or a separate resource), you must disable either ARS HUD’s seatbelt or the other script to avoid conflicts. To disable ARS HUD’s seatbelt, set Config.ToggleSeatBelt.active = false in config.lua. To use ARS HUD’s seatbelt with framework integration, set Config.ToggleSeatBelt.useBuiltin = true (this makes ARS HUD read the seatbelt state from your framework instead of running its own logic).

Vehicle Engine Toggle

Config.ToggleVehicleEngine = {
    active = true,
    key = 'G',
}

Setting	Type	Default	Description
active	boolean	true	Enable the engine toggle keybind
key	string	'G'	Keybind to toggle the vehicle engine

Cinematic Mode

Config.ToggleCinematicMode = {
    active = true,
    key = nil,
    command = 'cinematic',
}

Setting	Type	Default	Description
active	boolean	true	Enable cinematic mode
key	string|nil	nil	Keybind for cinematic mode (none by default)
command	string	'cinematic'	Chat command to toggle cinematic mode

Crosshair and Hitmarker

Config.Crosshair = true
Config.Hitmarker = true

Setting	Type	Default	Description
Crosshair	boolean	true	Enable the crosshair customization feature
Hitmarker	boolean	true	Enable the hitmarker feedback feature

Built-in Chat

Config.EnableBuiltInChat = true

Setting	Type	Default	Description
EnableBuiltInChat	boolean	true	Use the custom built-in chat. When true, the default FiveM chat resource is stopped automatically

Key Hints

Config.Keys = {
    active = true,
    keys = {
        { key = 'M',  label = 'Phone',       icon = 'phone' },
        { key = 'F2', label = 'Inventory',    icon = 'apps' },
        { key = '`',  label = 'Voice Mode',   icon = 'microphone' },
        { key = 'T',  label = 'Chat',         icon = 'chat' },
        { key = 'F4', label = 'Emote Menu',   icon = 'emote' },
        { key = 'X',  label = 'Hands Up',     icon = 'handsup' },
    },
}

Setting	Type	Default	Description
active	boolean	true	Show key hints on the HUD
keys	table[]	(see above)	Array of key hint entries

Each key hint entry:

Field	Type	Description
key	string	Key label to display
label	string	Action label
icon	string	Icon type

Available icon types: 'phone', 'microphone', 'apps', 'question', 'chat', 'emote', 'handsup'

Reset HUD Positions

Config.ResetHudPositions = {
    active = true,
    command = 'resethudpos',
}

Setting	Type	Default	Description
active	boolean	true	Enable the reset command
command	string	'resethudpos'	Chat command to reset HUD positions

Advanced Display Settings

Config.HideGTAHudComponents = false
Config.HavePostalMap = false

Setting	Type	Default	Description
HideGTAHudComponents	boolean	false	Hide native GTA HUD components for a cleaner look. Increases resource monitor usage
HavePostalMap	boolean	false	Set to true if your server uses a postal map. Used with HideGTAHudComponents to fix minimap zoom behavior

Refresh Times

Config.RefreshTimes = {
    hud = 200,
    vehicle = 100,
    requestPlayerCount = 30000,
}

Setting	Type	Default	Description
hud	number	200	Main HUD data refresh interval in milliseconds
vehicle	number	100	Vehicle data refresh interval in milliseconds (only active when in a vehicle)
requestPlayerCount	number	30000	Player count polling interval in milliseconds

Electric Vehicles

Config.ElectricVehicles = {
    'Imorgon', 'Neon', 'Raiden', 'Cyclone', 'Voltic', 'Voltic2',
    'Tezeract', 'Dilettante', 'Dilettante2', 'Airtug', 'Caddy',
    'Caddy2', 'Caddy3', 'Surge', 'Khamelion', 'RCBandito',
}

Add or remove GTA vehicle model names to control which vehicles display as electric on the fuel gauge. Electric vehicles show a battery icon instead of a fuel pump.

Nitro (NOS)

Config.Nitro = {
    active = true,
    boostKey = 'LSHIFT',
    purgeKey = 'LMENU',
    requireTurbo = true,
    blockedClasses = { [8] = true, [13] = true, [14] = true, [15] = true, [16] = true, [19] = true },
    drainRate = 5.0,
    refillRate = 1.5,
    refillMinSpeed = 60,
    cooldown = 3.0,
    screenEffects = true,
    screenEffectIntensity = 0.5,
    cameraShakeType = 'SKY_DIVING_SHAKE',
    cameraShakeIntensity = 0.25,
    useRaceTurboFlash = true,
    refillItem = 'nos_refill',
    refillAmount = 100,
    refillDuration = 5000,
    persistence = true,
    refillCommand = {
        enabled = true,
        command = 'refillnos',
    },
}

Setting	Type	Default	Description
active	boolean	true	Enable the nitro system
boostKey	string	'LSHIFT'	Keybind for nitro boost
purgeKey	string	'LMENU'	Keybind for nitro purge
requireTurbo	boolean	true	Require turbo mod (slot 18) for NOS to work
blockedClasses	table	motorcycles, cycles, boats, helicopters, planes, military	GTA vehicle classes that cannot use NOS
drainRate	number	5.0	NOS drained per second while boosting
refillRate	number	1.5	NOS auto-refilled per second while driving (not boosting)
refillMinSpeed	number	60	Minimum speed for auto-refill (set to 0 for any speed)
cooldown	number	3.0	Seconds after boosting before you can boost again (0 to disable)
screenEffects	boolean	true	Enable motion blur and camera shake during boost
screenEffectIntensity	number	0.5	Motion blur strength (0.0 to 1.0)
cameraShakeType	string	'SKY_DIVING_SHAKE'	Camera shake type
cameraShakeIntensity	number	0.25	Camera shake strength (0.0 to 1.0)
useRaceTurboFlash	boolean	true	Flash effect on boost start
refillItem	string	'nos_refill'	Inventory item name for NOS refill
refillAmount	number	100	How much NOS the refill item restores (0 to 100)
refillDuration	number	5000	Refill progress bar duration in milliseconds
persistence	boolean	true	Save NOS level per plate across server restarts
refillCommand.enabled	boolean	true	Enable the /refillnos admin command
refillCommand.command	string	'refillnos'	Admin command name

Note: NOS persistence uses server ResourceKVP storage. Only vehicles with a turbo upgrade will have their NOS level saved. The nos_refill item must exist in your inventory system if you want players to refill NOS manually.

Admin Commands

Config.AdminCommands = {
    announce = {
        enabled = true,
        command = 'announce',
        acePermission = 'admin',
    },
    eventnotify = {
        enabled = true,
        command = 'eventnotify',
        acePermission = 'admin',
    },
}

Setting	Type	Default	Description
announce.enabled	boolean	true	Enable the /announce command
announce.command	string	'announce'	Command name
announce.acePermission	string	'admin'	ACE permission required
eventnotify.enabled	boolean	true	Enable the /eventnotify command
eventnotify.command	string	'eventnotify'	Command name
eventnotify.acePermission	string	'admin'	ACE permission required

Theme Sounds

Config.ThemeSounds = {
    enabled = true,
    announcementVolume = 0.7,
    eventVolume = 0.6,
}

Setting	Type	Default	Description
enabled	boolean	true	Enable themed sound effects for announcements and events
announcementVolume	number	0.7	Announcement sound volume (0.0 to 1.0)
eventVolume	number	0.6	Event notification sound volume (0.0 to 1.0)

---

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.