⚠️Emergency Alert System (EAS)

---

Overview

XeX EAS (Emergency Alert System) is a premium alert management system for FiveM servers. It allows emergency services (police, sheriff, etc.) to set and change alert levels that are displayed as HUD icons to players within their jurisdiction zones. The system features a modern glassmorphism NUI interface, zone-based jurisdiction, multi-framework support, and Discord webhook logging.

Supported Frameworks

Framework	Version	Status
ESX Legacy	1.6.0+	✅ Full Support
QBCore	Latest	✅ Full Support
QBox (QBx)	Latest	✅ Full Support (requires ox_lib)

---

Features Summary

Category	Feature	Description
Alerts	Multi-Entity	Support for multiple alert entities (police, sheriff, etc.)
Alerts	Zone-Based	Alerts only display when player is within jurisdiction zones
Alerts	Multiple Levels	Configurable alert levels per entity (Code 1-4 by default)
Alerts	Auto-Update	Alert HUD updates automatically when player changes zone
UI	Glassmorphism	Modern dark translucent glass-effect interface
UI	HUD Overlay	Non-intrusive alert icons displayed in-game
UI	Confirm Dialog	Two-step confirmation before changing alert levels
UI	i18n Support	Dynamic language switching via server locales
UI	Hideable	Players can toggle alert HUD visibility via command
Access	Job Restriction	Only specified jobs can change alert levels per entity
Access	Grade Restriction	Minimum job grade required to manipulate alerts
Security	Server Validation	Alert changes validated server-side (name, code, job, grade)
Security	Anti-Exploit	Type checking and permission verification on all inputs
System	Discord Webhooks	Logs alert changes with player info
System	Auto Updater	Version check on resource start
Perf	Optimized	Hash-set zone lookups (O(1)), sleep-based loops (1500ms)
I18n	2 Languages	English, Spanish
System	3 Frameworks	ESX Legacy, QBCore, QBox

---

Installation

Requirements

• FiveM Server

• Framework: ESX Legacy, QBCore, or QBox

• Optional: ox_lib (required for QBox)

• No database required

Quick Start

1

Extract files

Extract to your resources/[xex]/ folder

2

Rename folder

Rename folder to 'xex_eas' if needed

3

Add to server.cfg

Add the following line:

ensure xex_eas

4

Configure

Edit config.lua (framework, alert entities, zones)

5

Restart server

Restart your FiveM server

Recommended Resource Order

# server.cfg — ESX
ensure oxmysql
ensure es_extended
ensure xex_eas

# server.cfg — QBCore
ensure oxmysql
ensure qb-core
ensure xex_eas

# server.cfg — QBox
ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure xex_eas

---

Configuration

General Settings

Config.Language = 'en'              -- 'en' or 'es'
Config.CheckForUpdates = true       -- Auto version check on startup
Config.CanAlertsBeHideable = true   -- Allow players to hide alerts via command
Config.HideAlertsCommand = 'toggleeas'  -- Command to toggle alert visibility

Option	Default	Description
Language	'en'	Controls locale strings, UI text, and NUI language
CheckForUpdates	true	Checks for new versions on resource start
CanAlertsBeHideable	true	Enables the toggle command for hiding/showing HUD alerts
HideAlertsCommand	'toggleeas'	Chat command name to toggle alert visibility

Framework Settings

Config.Framework = 'auto' -- 'auto' | 'esx' | 'qb' | 'qbx'

Value	Framework	Notes
'auto'	Auto-detect: QBox → QBCore → ESX	Default
'esx'	ESX Legacy	Uses esx:getSharedObject
'qb'	QBCore	Uses qb-core exports
'qbx'	QBox	Uses qbx_core exports + ox_lib callbacks

Alert Entities

Each alert entity represents a department/agency with its own alert levels and jurisdiction.

Config.AlertEntities = {
    {
        name = 'policeAlerts',              -- Unique identifier
        jobRestriction = {'police'},        -- Jobs allowed to change this alert
        isHideable = false,                 -- Can users hide this via toggleeas command
        jurisdictionZones = { 'AIRP', 'ALTA', ... },  -- GTA zone names
        defaultAlertOnRestart = 1,          -- Default alert level on server restart
        alerts = {
            {
                image = 'police1.png',      -- Image file in nui/img/
                code = '1',                 -- Alert code label
                minGradeToManipulate = 0,   -- Minimum job grade (0 = any grade)
            },
            -- Additional alert levels...
        },
    },
}

Property	Type	Description
name	string	Unique identifier for the alert entity
jobRestriction	table	Array of job names that can modify this entity
isHideable	boolean	Whether players can hide this entity's alerts
jurisdictionZones	table	Array of GTA zone codes where alerts are displayed
defaultAlertOnRestart	number	Alert level index set on server restart (1-based)
alerts	table	Array of alert level definitions
alerts[].image	string	Image filename in nui/img/ directory
alerts[].code	string	Display code for the alert level
alerts[].minGradeToManipulate	number	Minimum job grade to change to this level (0 = no restriction)

Jurisdiction Zones

Zone names correspond to GTA V map zones. Full list available at: https://gist.github.com/Syping/dc61ef19c6ba902858ce8abe636d745e

Example zones by area:

Area	Zones
City Center	DOWNT, DTVINE, BURTON, HAWICK, ALTA
South LS	DAVIS, RANCHO, CHAMH, STRAW
East LS	LMESA, ELSANT, MURRI, CYPRE
Beach	BEACH, VESP, DELBE, DELPE
County	SANDY, PALETO, GRAPES, ALAMO
Military	ZANCUDO, ARMYB

Discord Webhook

Config.WebhookEnabled = false              -- Enable/disable Discord logging
Config.WebhookServerName = 'My Server'     -- Server name in embeds
Config.Webhook = ''                        -- Discord webhook URL
Config.DateFormat = '%d/%m/%Y [%X]'        -- Timestamp format
Config.IconUrl = 'https://i.imgur.com/w3JYiO0.png'  -- Embed icon
Config.BotName = 'EAS Bot'                 -- Bot display name

Option	Default	Description
WebhookEnabled	false	Enable Discord webhook logging
WebhookServerName	'My Server'	Server name in embed header
Webhook	''	Your Discord webhook URL
DateFormat	'%d/%m/%Y [%X]'	Lua os.date format for timestamps
IconUrl	'...'	Thumbnail URL for webhook embeds
BotName	'EAS Bot'	Bot display name in Discord

Webhook logs include:

• Previous alert level

• New alert level

• Player ID, License identifier, Discord mention

---

How It Works

Complete Flow

1

Server initialization

Server starts → Alert entities initialized with defaultAlertOnRestart

2

Player join

Player joins → Client requests current alert status via callback

3

Client zone detection

Client detects player zone → Shows alert images for matching jurisdictions

4

Zone change

Player changes zone → Alert images update automatically (every 1.5s)

5

Open menu

Authorized player runs /eas → Menu opens with their allowed entities

6

Select new level

Player selects new alert level → Confirm dialog shown

7

Server validation

On confirm → Server validates (name, code, job, grade) → Updates state

8

Broadcast

Server broadcasts to ALL clients → Everyone's HUD updates

9

Webhook

If webhook enabled → Discord embed sent with change details

Zone Detection

The client runs a background thread every 1500ms that checks the player's current zone using GetNameOfZone(). When the zone changes, alert images are recalculated using pre-built hash-set lookups for O(1) performance.

Alert Levels

Each entity has multiple alert levels (e.g., Code 1 through Code 4). The active level is tracked server-side as a simple key-value map:

-- Server state example
alertEntities = {
    policeAlerts = 2,    -- Currently at Code 2
    sheriffAlerts = 1,   -- Currently at Code 1
}

Permission System

Check	Location	Description
Job restriction	Server	Player's job must be in jobRestriction array
Grade restriction	Client + Server	Player's job grade must meet minGradeToManipulate
Entity validation	Server	Alert name must exist in Config
Code validation	Server	Alert number must be within valid range

---

NUI Interface

HUD Alert Display

Alert images are displayed as a non-intrusive HUD overlay in the top-left corner. Only shows alerts for entities whose jurisdiction includes the player's current zone.

Alert Menu

Opened via /eas command. Shows available alert entities with clickable alert level cards. The currently active level is highlighted with an "ACTIVE" badge. Uses glassmorphism design with Inter font and smooth animations.

Confirm Dialog

Before any change, a confirmation dialog appears with animated warning icon. Player can confirm or cancel. ESC key returns to selection view first, then closes menu.

---

Security

Server-Side Validation

All alert changes are validated server-side before being applied:

1. Type checking — alertname must be a string, alertnumber must be a number

2. Name validation — Alert entity must exist in Config.AlertEntities

3. Range validation — Alert number must be between 1 and the total alerts for that entity

4. Job validation — Player's current job must be in the entity's jobRestriction list

5. Player validation — Player object must exist (prevents spoofed source IDs)

Anti-Exploit Measures

• Invalid inputs are logged with player ID and rejected

• All validation happens server-side; client-side checks are convenience only

• Server state is never modified without passing all validation checks

---

Exports & Events

Server Callbacks (ESX)

Callback	Parameters	Returns	Description
xex_eas:getStatus	—	table	Returns current alert entities state

Server Callbacks (QBCore)

Callback	Parameters	Returns	Description
xex_eas:getStatus	—	table	Returns current alert entities state

Server Callbacks (QBox)

Callback	Parameters	Returns	Description
xex_eas:getStatus	—	table	Uses lib.callback.register (ox_lib). Returns current alert entities state

Server Exports

Export	Description
CheckForUpdates	Programmatically trigger update check from another resource

Server Events

Event	Parameters	Description
xex_eas:changeAlert	alertname, alertnumber	Request to change an alert level (validated server-side)

Client Events

Event	Parameters	Description
xex_eas:showMenu	entitiesAllowed	Opens the alert selection menu
xex_eas:reloadStatus	entities	Updates local alert state and refreshes HUD

NUI Callbacks

Callback	Data	Description
closeButton	—	Closes menu and releases NUI focus
changeAlert	{code, key}	Requests alert level change

Commands

Command	Access	Description
/eas	Restricted jobs	Opens the alert management menu
/toggleeas	All players	Toggles alert HUD visibility (configurable)
eas_update	Server console only	Manually trigger update version check

---

Localization

Supported Languages

Code	Language
en	English
es	Spanish (Español)

Locale Keys Reference

Gameplay Keys:

Key	EN	ES
menu_not_loaded	Menu is still loading...	El menú aún no está cargado
need_grade	You don't have enough rank...	No tienes el rango suficiente...
changed_alert	You have modified the alert level	Has modificado el nivel de alerta
forbidden	You can't use this command	No puedes usar este comando
someone_changed_alert	Someone changed the alert level	Alguien cambió el nivel de alerta
latest_level	Latest level:	Último nivel:
new_level	New level:	Nuevo nivel:
ui_confirm_desc	Are you sure you want to change this alert level?	¿Estás seguro de que quieres cambiar este nivel de alerta?

UI Keys (NUI interface):

Key	EN	ES
ui_title	Emergency Alert System	Sistema de Alerta de Emergencia
ui_change_alert	Change Alert Level	Cambiar Nivel de Alerta
ui_confirm	Confirm Change	Confirmar Cambio
ui_yes	Confirm	Confirmar
ui_no	Cancel	Cancelar
ui_current	ACTIVE	ACTIVO

Adding Languages

1. Add a new locale table in locales.lua:

['fr'] = {
    ['menu_not_loaded'] = 'Le menu est en cours de chargement...',
    ['ui_title'] = 'Système d\'Alerte d\'Urgence',
    -- ... add all keys
},

1. Add fallback UI strings in nui/script.js under UIText:

fr: {
    title: 'Système d\'Alerte d\'Urgence',
    // ... add all keys
}

1. Set Config.Language = 'fr' in config.lua.

---

Performance

Metric	Value	Notes
Zone check interval	1500ms	Only checks zone name, no position streaming
Zone lookup	O(1)	Hash-set based, not linear scan
NUI updates	On zone change only	No continuous re-rendering
Server memory	Minimal	Only stores alert level per entity
Network	Low	Broadcasts only on alert change
Idle CPU	~0.00ms	Sleep-based loops with 1500ms interval

---

File Structure

xex_eas/
├── fxmanifest.lua          # Resource manifest
├── config.lua              # All configuration options
├── locales.lua             # Language strings (EN/ES)
├── DOCS.md                 # This documentation
├── readme.md               # Quick readme
├── client/
│   ├── esx.lua             # ESX client logic
│   ├── qb.lua              # QBCore client logic
│   ├── qbx.lua             # QBox client logic (requires ox_lib)
│   └── scrow.lua           # Shared NUI bridge (sendDataToNUI)
├── server/
│   ├── esx.lua             # ESX server logic + webhook
│   ├── qb.lua              # QBCore server logic + webhook
│   ├── qbx.lua             # QBox server logic + webhook (requires ox_lib)
│   └── updater.lua         # Auto update checker + CheckForUpdates export
└── nui/
    ├── index.html           # Modern glassmorphism UI
    ├── script.js            # Unified NUI controller with i18n
    ├── styles.css           # Glassmorphism styles
    └── img/                 # Alert images
        ├── police1.png
        ├── police2.png
        ├── police3.png
        ├── police4.png
        ├── sheriff1.png
        ├── sheriff2.png
        ├── sheriff3.png
        └── sheriff4.png

---

Customization

Adding New Alert Entities

Add a new entry to Config.AlertEntities in config.lua:

{
    name = 'emsAlerts',
    jobRestriction = {'ambulance'},
    isHideable = false,
    jurisdictionZones = { 'AIRP', 'ALTA', 'DAVIS', ... },
    defaultAlertOnRestart = 1,
    alerts = {
        { image = 'ems1.png', code = '1', minGradeToManipulate = 0 },
        { image = 'ems2.png', code = '2', minGradeToManipulate = 0 },
        { image = 'ems3.png', code = '3', minGradeToManipulate = 2 },
    },
},

Then add the corresponding image files to nui/img/.

Customizing Alert Images

• Place PNG images in nui/img/

• Recommended size: 128×128px or 256×256px (displayed at 48-60px)

• Transparent background recommended for HUD overlay

• Reference the filename in Config.AlertEntities[].alerts[].image

Modifying the UI

The NUI uses standard HTML/CSS/JS with jQuery:

• Colors: Edit CSS variables in styles.css (gradients, rgba values)

• Layout: Modify .menu-card max-width, .alert-option sizing

• Animations: Adjust @keyframes in styles.css

• Font: Change the Google Fonts import in index.html

---

Troubleshooting (FAQ)

Alerts not showing on HUD

Check that your current zone is in jurisdictionZones for at least one entity.

/eas says "forbidden"

Your job must be in jobRestriction for at least one entity.

Menu says "still loading"

Wait a few seconds after joining; status loads asynchronously.

Webhook not working

Set Config.WebhookEnabled = true and paste your webhook URL.

Wrong language in UI

Set Config.Language to 'en' or 'es'.

Alert images not loading

Verify image filenames match Config.AlertEntities[].alerts[].image exactly.

"Grade" error when changing

Your job grade must be ≥ minGradeToManipulate for that alert level.

---

Changelog

v1.0.1

• Added QBox (QBx) framework support with ox_lib integration

• Added auto-detect framework (Config.Framework = 'auto')

• Added dedicated server/updater.lua with CheckForUpdates export and eas_update console command

• Bug fixes and stability improvements

v1.0.0

• Initial release

• Multi-entity alert system (police, sheriff)

• Zone-based jurisdiction detection

• Job and grade restriction system

• Modern glassmorphism NUI with i18n

• Server-side validation and anti-exploit

• Discord webhook logging

• ESX + QBCore support

• Performance optimized (O(1) zone lookups, sleep-based loops