Administrator Guide

This guide covers the admin-facing features of ARS Hud V3, including announcements, event notifications, built-in chat channels, and permission setup.

---

Table of Contents

1. Permissions Setup
2. Server Announcements
3. Event Notifications
4. Built-in Chat Channels
5. Player Count Display
6. Troubleshooting

---

1. Permissions Setup

ARS Hud V3 admin commands use ACE permissions combined with framework admin checks.

Configure the ACE Permission

Add the following to your server.cfg or admin ACL configuration:

add_ace group.admin admin allow

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

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

How Admin Detection Works

The HUD checks admin status in two ways:

1. ACE permission — the player must have the configured permission string
2. Framework check — the framework must also recognize the player as admin (e.g., QBCore group admin, superadmin, or god; ESX group admin or superadmin)

Both checks must pass for admin commands to work.

Tip: If your framework uses a different group name, update acePermission in the config to match.

2. Server Announcements

Announcements display a styled banner across all players’ screens.

Send an Announcement

Use the /announce command in chat:

/announce

This opens an input dialog with the following fields:

Field	Description
Type	Choose Success, Warning, or Error
Title	Announcement title
Message	Announcement body text
Duration (ms)	How long the banner stays visible (in milliseconds)

Send from a Script

You can also trigger announcements from server-side code:

TriggerClientEvent('ars_hud:showAnnouncement', -1, 'Server Update', 'New features added!', 'success', 10000)

Or from client-side:

exports['ars_hud']:ShowAnnouncement('Restart', 'Server restarting in 5 minutes', 'warning', 10000)

Configure Announcement Sounds

Announcements can play themed sounds when they appear. Control this in config.lua:

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

3. Event Notifications

Event notifications show a card with a countdown timer and optional image.

Send an Event Notification

Use the /eventnotify command in chat:

/eventnotify

This opens an input dialog:

Field	Description
Title	Event title
Message	Event description
Timer (seconds)	Countdown timer duration
Image URL (optional)	URL for an event image

Send from a Script

From server-side:

TriggerClientEvent('ars_hud:showEventNotification', -1, 'Airdrop', 'Supply drop incoming!', 60, 'https://example.com/image.png')

From client-side:

exports['ars_hud']:ShowEventNotification('Airdrop', 'Supply drop incoming!', 60, 'https://example.com/image.png')

4. Built-in Chat Channels

When Config.EnableBuiltInChat is true, the HUD replaces the default FiveM chat with a custom system that supports multiple channels.

Chat Commands

Command	Channel	Range	Description
/ooc	All	Server-wide	Out-of-character message
/me	Proximity	20 meters	Action message
/do	Proximity	20 meters	Description message
/try	Proximity	20 meters	Action with random success or fail
/jobmsg	Job	Same job only	Message to coworkers
/staffmsg	Admin	Admins only	Staff communication
/twt	Twitter	Server-wide	Post a tweet (140 char max)

Disable Built-in Chat

If you prefer the default FiveM chat or a third-party chat resource:

Config.EnableBuiltInChat = false

Warning: If you disable the built-in chat, remember to add ensure chat back to your server.cfg so the default FiveM chat resource starts.

Chat Setup Checklist

When using the built-in chat, make sure your server.cfg is configured correctly:

1. Remove or comment out ensure chat — ARS Hud V3 stops the default FiveM chat automatically, but ensure chat will restart it
2. Download and install ars_chat_bridge from portal.cfx.re — this caches command suggestions from other resources (like /dispatch, /ticket, etc.) and forwards them to the built-in chat. Without it, only the HUD’s own commands will show suggestions
3. Add ars_chat_bridge at the top of your server.cfg so it caches suggestions 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

5. Player Count Display

The HUD can show the current online player count and max player limit.

Configure

Config.LuaHudSettings.client_info.server_info.showOnlinePlayers = true
Config.LuaHudSettings.client_info.server_info.name = 'Your Server Name'

The player count is polled at the interval set in:

Config.RefreshTimes.requestPlayerCount = 30000

Tip: The max player count reads from the sv_maxclients convar automatically.

6. Troubleshooting

Admin commands say “no permission”

• Check that the player has the ACE permission configured in Config.AdminCommands
• Verify the framework recognizes the player as admin
• Both ACE and framework checks must pass

Announcements do not appear

• Ensure Config.AdminCommands.announce.enabled = true
• Check that theme sounds are not causing errors if Config.ThemeSounds.enabled = true
• Verify the xsound resource is running

Built-in chat not showing messages

• Confirm Config.EnableBuiltInChat = true in config.lua
• Check that ensure chat is removed from your server.cfg — the default chat resource will conflict if it restarts
• 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
• Proximity messages (/me, /do, /try) only work within 20 meters

Player count not updating

• Set Config.LuaHudSettings.client_info.server_info.showOnlinePlayers = true
• Lower the refresh interval if needed: Config.RefreshTimes.requestPlayerCount = 15000

NOS not working

• Verify Config.Nitro.active = true in config.lua
• Check that the vehicle has a turbo upgrade (slot 18) if Config.Nitro.requireTurbo = true
• Ensure the vehicle class is not in Config.Nitro.blockedClasses (motorcycles, boats, etc.)
• Use /refillnos to test — the command requires the player to be in a vehicle as driver

---

Quick Reference

Command	Description
/announce	Send a server-wide announcement
/eventnotify	Send an event notification with timer
/refillnos	Instantly refill NOS to 100%
/hudsettings	Open HUD settings
/resethudpos	Reset all HUD positions
/cinematic	Toggle cinematic mode

---

Need Help?

1. Check the Configuration page for all available settings
2. Check the Exports page for scripting integration
3. Verify all required dependencies are running before ars_hud

---

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.