Installation Guide

This guide walks you through installing ARS Hud V3 on your FiveM server. It covers prerequisite resources, file placement, framework configuration, and server.cfg setup.

Prerequisites

• ox_lib — required for locale, keybinds, callbacks, and data loading
• xsound — required for the built-in music player
• A supported framework: QBCore, QBX (Qbox), or ESX

Optional Resources

Install these if you want the related HUD features to work:

Resource	Feature
pma-voice or SaltyChat	Voice range and radio channel display
ox_fuel, LegacyFuel, cdn-fuel, or ps-fuel	Accurate fuel level reading
ars_chat_bridge	Command suggestions for built-in chat (download from cfx.re)

Installation Steps

1. Download and Place Resource

Download ARS Hud V3 from your Tebex or CFX portal and place it in your resources directory:

server-data/resources/[folder]/ars_hud/

2. Configure Framework

Open ars_hud/config.lua and set the framework. By default it auto-detects:

Config.Framework = 'auto'

If auto-detection fails or you want to force a specific framework, set it explicitly:

Config.Framework = 'qb'   -- QBCore
Config.Framework = 'qbx'  -- QBX (Qbox)
Config.Framework = 'esx'  -- ESX

3. Configure HUD Settings

While you have config.lua open, review these common settings:

Config.LuaHudSettings.vehicle_info.kmH = true    -- true for km/h, false for MPH
Config.LuaHudSettings.client_info.server_info.name = 'Your Server Name'
Config.LuaHudSettings.client_info.server_info.image = 'logo.png'
Config.LuaHudSettings.client_info.extra_currency.active = false

See the Configuration page for every available setting.

4. Switch to Production Mode

Open fxmanifest.lua and change the ui_page from the dev server to the built files:

-- Comment out or remove the dev line:
-- ui_page 'http://localhost:5173/'

-- Uncomment the production line:
ui_page 'html/index.html'

5. Add to Server Config

Add these lines to your server.cfg. Dependencies must start before the HUD:

ensure ox_lib
ensure xsound
ensure ars_hud

If you use optional resources, ensure they start before the HUD as well:

ensure ox_lib
ensure xsound
ensure pma-voice
ensure ox_fuel
ensure ars_chat_bridge
ensure ars_hud

Note: ars_chat_bridge must be placed at the top of your server.cfg (before other chat-related resources) so it can cache command suggestions from all resources before the HUD starts.

6. Set Admin Permissions

Admin commands use ACE permissions. Add the permission to your server.cfg or admin ACL:

add_ace group.admin admin allow

The admin ACE permission is the default. You can change it in config.lua:

Config.AdminCommands.announce.acePermission = 'admin'
Config.AdminCommands.eventnotify.acePermission = 'admin'

7. Configure Built-in Chat (Optional)

If using the built-in chat (Config.EnableBuiltInChat = true):

1. Remove or comment out ensure chat from your server.cfg — ARS Hud V3 stops the default FiveM chat resource automatically, but ensure chat in your config will restart it
2. Download and install ars_chat_bridge from portal.cfx.re — it caches command suggestions from other resources and forwards them to the built-in chat
3. Add ars_chat_bridge to the top of your server.cfg so it can cache command suggestions from all resources before the HUD starts
4. Add the ACE permission so ars_hud can stop the default chat resource

# --- ARS Chat Bridge (must load first) ---
ensure ars_chat_bridge

# --- Other resources ---
ensure ox_lib
ensure xsound

# --- ACE Permissions ---
add_ace resource.ars_hud command.stop allow

# --- ARS HUD ---
ensure ars_hud

Note: If you switch back to the default FiveM chat later by setting Config.EnableBuiltInChat = false, remember to add ensure chat back to your server.cfg.

8. Configure Nitro Refill Item (Optional)

If you enable the nitro system (Config.Nitro.active = true) and want players to refill NOS using an inventory item, you must add the nos_refill item to your inventory. The default item name is nos_refill — change it in config.lua if needed:

Config.Nitro.refillItem = 'nos_refill'

ox_inventory

Add the item to ox_inventory/data/items.lua:

['nos_refill'] = {
    label = 'NOS Refill',
    weight = 100,
    stack = true,
    close = true,
    description = 'Refills your vehicle NOS to 100%.'
}

qb-inventory

Add the item to qb-core/shared/items.lua:

nos_refill = {
    name = 'nos_refill',
    label = 'NOS Refill',
    weight = 100,
    type = 'item',
    image = 'nos_refill.png',
    unique = false,
    useable = true,
    shouldClose = true,
    description = 'Refills your vehicle NOS to 100%.'
}

Note: qs-inventory and ps-inventory use the same format as qb-inventory. Adjust the file path to your inventory’s config location.

Note: Admins can bypass the item requirement by using the /refillnos command, which instantly refills NOS to 100%.

Verification

1. Start your server and join with a character
2. The HUD should appear with status bars, minimap, and compass
3. Press I to open the settings menu and verify all panels load
4. Enter a vehicle and check that speed, fuel, and vehicle controls appear
5. Try /announce test as an admin to verify admin commands work

Updating

1. Back up your config.lua file — it is the only user-editable file and may be overwritten
2. Replace the resource files with the new version
3. Restore your config.lua and compare it against the new default for any new settings
4. Restart your server or the ars_hud resource

Troubleshooting

HUD does not appear

• Verify ui_page is set to 'html/index.html' in fxmanifest.lua
• Ensure ox_lib and xsound are started before ars_hud
• Check the server console for errors

Framework not detected

• Set Config.Framework explicitly to 'qb', 'qbx', or 'esx'
• Ensure your framework resource (qb-core, qbx_core, or es_extended) is started

Fuel always shows 100%

• Install a supported fuel resource (ox_fuel, LegacyFuel, cdn-fuel, or ps-fuel)
• The HUD falls back to the native GetVehicleFuelLevel which may not be accurate

Built-in chat does not work

• Set Config.EnableBuiltInChat = true in config.lua
• Remove or comment out ensure chat from your server.cfg — the default FiveM chat resource is automatically stopped, but ensure chat will restart it
• Verify add_ace resource.ars_hud command.stop allow is in your server.cfg — without this ACE permission, ars_hud cannot stop the default chat resource
• Download and install ars_chat_bridge from portal.cfx.re and place it at the top of your server.cfg for command suggestions from other resources

Admin commands say no permission

• Verify the player has the ACE permission set in Config.AdminCommands.announce.acePermission
• Check that the framework also recognizes the player as admin

---

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.