# Dispatch System

{% embed url="<https://www.youtube.com/watch?v=wNeDd112zAA>" %}

\
\
This page explains how to configure and use the Dispatch System.

***

## 📋 Configuration Files

**cfg\_main.lua**\
Main system settings, UI defaults, and feature toggles.

**cfg\_alerts.lua**\
Alert types, grouping rules, and automatic event detection.

**cfg\_utils.lua**\
Postal zones and custom utility functions.

***

### ⚙️ Main Configuration

#### 🌐 Language Settings

**Config.Locale**\
Sets the default language for the dispatch system.

```lua
Config.Locale = 'en'
```

**Supported Languages:**

* `'en'` — English
* `'tr'` — Turkish
* `'de'` — German
* `'fr'` — French
* `'es'` — Spanish
* `'pl'` — Polish
* `'pt'` — Portuguese
* `'cz'` — Czech

💡 Add more languages by creating locale files in the `/locales/` folder.

***

#### 🧑‍✈️ Unit Display Format

**Config.UnitDisplay.mode**\
Determines how officer names and callsigns appear in alerts.

```lua
Config.UnitDisplay = {
    mode = 'name'
}
```

**Options:**

* `'name'` — Show only officer name/initials
  * Example: `J.Doe`
* `'callsign'` — Show only callsign (falls back to name if no callsign)
* `'callsign_name'` — Show both
  * Example: `23A | J.Doe`

***

#### 🧑‍✈️ Custom Callsigns (Server Export)

External scripts can assign a **custom callsign** per player, overriding the default callsign from player metadata.

**🔧 Export Syntax**

```lua
exports['glxs-dispatch']:SetCustomCallsign(source, callsign)
```

**Parameters:**

* `source` *(number)*\
  The server ID of the player.
* `callsign` *(string | nil)*
  * Pass a **string** to set a custom callsign.
  * Pass **nil** to clear/reset and revert to the default callsign.

**💻 Example: `/callsign` Command (Server-Side)**

Add this to any **server-side** script:

```lua
RegisterCommand('callsign', function(source, args)
    local callsign = args[1]

    if not callsign then
        return
    end

    -- Set the custom callsign for the player
    exports['glxs-dispatch']:SetCustomCallsign(source, callsign)
end, false)
```

Usage in-game:

```
/callsign 23A
```

This sets the player’s callsign to `23A` in the dispatch UI.

To reset back to default:

```lua
exports['glxs-dispatch']:SetCustomCallsign(source, nil)
```

***

#### 🚨 Job Restrictions

**Config.TargetJobs**\
Limit dispatch alerts to specific jobs only.

```lua
Config.TargetJobs = {
    enabled = false,
    jobs = { 'police', 'sheriff', 'lspd', 'bcso', 'ems' }
}
```

✅ **Allowed Jobs Examples:**

* `police`, `sheriff`, `lspd`, `bcso`
* `ems`, `ambulance`, `fire`

💡 Set `enabled = true` to activate job filtering.

***

#### 🚗 License Plate Obfuscation

**Config.PlateObfuscation**\
Partially hide license plates in vehicle-related alerts.

```lua
Config.PlateObfuscation = {
    enabled = true,
    chanceToHideChar = 0.5
}
```

**How it works:**

* Each character in the plate has a **50% chance** of being replaced with `*`.
* Example:
  * `ABC123` → `A*C1*3`

💡 Set `chanceToHideChar = 0.0` for full plates, `1.0` for fully hidden plates.

***

#### 🔇 Smart Mute

**Config.SmartMute**\
Automatically mute alerts during combat/shooting.

```lua
Config.SmartMute = {
    enabled = false,
    duration = 10000,
    checkInterval = 1000
}
```

* `duration` — Keep muted for **X milliseconds** after combat ends.
* `checkInterval` — How often to check combat state (ms).

⚠️ Recommended: Keep **disabled on production** servers to prevent missed alerts.

***

#### 🔊 Sound Cooldown

**Config.SoundCooldown**\
Prevents the same alert sound from repeating too quickly.

```lua
Config.SoundCooldown = {
    enabled = true,
    duration = 60000
}
```

💡 `60000` = **60 seconds** minimum between identical sounds.

***

#### 🎯 Detection Mode *(NEW in v1.0.3)*

**Config.DetectionMode**\
Controls how sensitive alert detection is for automatic events.

```lua
Config.DetectionMode = {
    mode = 'easy'  -- 'easy' or 'hard'
}
```

**Modes:**

* `'easy'` — Alerts trigger more easily (**recommended**)
  * ✅ Gunshot alerts: **No witness** check required – triggers immediately
  * ✅ Reckless driving: Manual speed check every 2 seconds – **100% reliable**
* `'hard'` — More realistic detection (requires witnesses)
  * ⚠️ Gunshot alerts: **Requires witnesses** to trigger
  * ⚠️ Reckless driving: Uses native GTA events – **less reliable** but more realistic

💡 Recommended: Use `'easy'` mode for **consistent** alert detection.

***

#### 📍 Location Display Format

**Config.LocationFormat**\
Controls how locations appear in alerts.

```lua
Config.LocationFormat = 1
```

**Options:**

1. Street name only
   * Example: `Power St`
2. Area/District only
   * Example: `Vespucci`
3. Both street and area
   * Example: `Power St, Vespucci`

***

#### 💡 Alert Suggestions

**Config.Suggest**\
Recommends nearby alerts to units.

```lua
Config.Suggest = {
    enabled = true,
    radius = 50.0,
    cooldownSec = 15,
    pulseUI = true
}
```

* `radius` — Maximum distance (meters) to suggest alerts
* `cooldownSec` — Wait X seconds before re-suggesting the same alert
* `pulseUI` — Highlight the **"Attach"** button for suggested alerts

***

#### ⏱️ Dispatch Settings

**Config.Dispatch**\
Alert timing and weapon filtering.

```lua
Config.Dispatch = {
    DefaultDelaySec = 5,
    WeaponIgnore = { 'WEAPON_STUNGUN', 'WEAPON_FIREEXTINGUISHER' }
}
```

* `DefaultDelaySec` — Delay (seconds) before alerts are sent
* `WeaponIgnore` — Weapons that **won't** trigger shooting alerts

***

### 🚨 Alert Configuration

#### 📊 Alert Grouping

**Config.AlertGrouping**\
Prevents spam by grouping similar alerts.

```lua
Config.AlertGrouping = {
    enabled = true,
    radius = 50.0,
    timeout = 30000,
    activeThreshold = 10,
    excludedCodes = { '10-99' }
}
```

**How it works:**

* Alerts within **50.0 meters** are grouped together
* Group expires after **30000 ms (30 seconds)**
* Shows **"ACTIVE"** badge after **10 grouped alerts**
* Critical codes like `'10-99'` (Officer Down) **bypass** grouping

***

#### 🎯 Automatic Event Detection

**Config.Events**\
Auto-trigger alerts when certain events occur.

```lua
Config.Events = {
    Shooting        = { enabled = true,  type = 'shooting',          cooldown = 8000 },
    VehicleShooting = { enabled = true,  type = 'vehicle_shooting',  cooldown = 8000 },
    RecklessDriving = { 
        enabled = true,  
        type = 'reckless_driving', 
        thresholdKmh = { 180.0, 200.0 },
        speedUnit = 'kmh',  -- NEW in v1.0.3: 'kmh' or 'mph'
        cooldown = 15000 
    },
    VehicleTheft    = { enabled = true,  type = 'vehicle_theft',     cooldown = 10000 },
    Fight           = { enabled = true,  type = 'fight',             cooldown = 15000 },
    Explosion       = { enabled = true,  type = 'explosion',         cooldown = 10000 },
    PlayerDown      = { enabled = false, type = 'player_down',       cooldown = 5000 },
    OfficerDown     = { enabled = false, type = 'officer_down',      cooldown = 5000 },
    EmsDown         = { enabled = false, type = 'ems_down',          cooldown = 5000 }
}
```

⚠️ **Note:** Officer/EMS/Civilian down alerts should be triggered **manually** by scripts for accuracy.

***

#### 🚗 Reckless Driving Speed Unit *(NEW in v1.0.3)*

**speedUnit**\
Choose between **KM/H** or **MPH** for speed thresholds.

**KM/H example:**

```lua
RecklessDriving = { 
    thresholdKmh = { 180.0, 200.0 },
    speedUnit = 'kmh'
}
```

**MPH example:**

```lua
RecklessDriving = { 
    thresholdKmh = { 112.0, 124.0 },  -- 112 mph ≈ 180 km/h
    speedUnit = 'mph'
}
```

💡 The system automatically converts **MPH to KM/H** internally.

***

### 🔧 Exported Functions

All exports are **client-side** (except the custom callsign export which is server-side) and automatically collect alert data such as location, vehicle, weapon, etc.

#### 📞 Standard Exports

**🔫 Shooting Alerts**

```lua
exports['glxs-dispatch']:Shooting()
exports['glxs-dispatch']:VehicleShooting()
```

**🚗 Traffic & Vehicle**

```lua
exports['glxs-dispatch']:RecklessDriving()
exports['glxs-dispatch']:VehicleTheft()
exports['glxs-dispatch']:Carjacking()
exports['glxs-dispatch']:CarBoosting()
exports['glxs-dispatch']:StreetRacing()
```

**🕵️ Criminal Activity**

```lua
exports['glxs-dispatch']:Fight()
exports['glxs-dispatch']:SuspiciousActivity(message)
exports['glxs-dispatch']:DrugSale()
exports['glxs-dispatch']:Explosion()
```

**💰 Robberies**

```lua
exports['glxs-dispatch']:StoreRobbery()
exports['glxs-dispatch']:HouseRobbery()
exports['glxs-dispatch']:BankRobbery(message)
exports['glxs-dispatch']:PacificBankRobbery()
exports['glxs-dispatch']:PaletoBankRobbery()
exports['glxs-dispatch']:BobcatRobbery()
exports['glxs-dispatch']:ArtGalleryRobbery()
exports['glxs-dispatch']:HumaneLabsRobbery()
exports['glxs-dispatch']:UnionRobbery()
exports['glxs-dispatch']:VangelicoRobbery()
exports['glxs-dispatch']:YachtRobbery()
exports['glxs-dispatch']:TrainRobbery()
exports['glxs-dispatch']:VanRobbery()
exports['glxs-dispatch']:UndergroundRobbery()
exports['glxs-dispatch']:DrugBoatRobbery()
exports['glxs-dispatch']:SignRobbery()
```

**🚑 Emergency Services**

```lua
exports['glxs-dispatch']:OfficerDown()
exports['glxs-dispatch']:OfficerBackup()
exports['glxs-dispatch']:OfficerDistress()
exports['glxs-dispatch']:EmsDown()
exports['glxs-dispatch']:PlayerDown()
exports['glxs-dispatch']:CivilianDead()
```

**☎️ 911/311 Calls**

```lua
exports['glxs-dispatch']:Call911()
exports['glxs-dispatch']:Call911Anonymous()
exports['glxs-dispatch']:Call311()
```

***

### 💻 Usage Examples

#### Example 1: Trigger Store Robbery

```lua
-- In your robbery script (client-side)
RegisterNetEvent('myStore:startRobbery', function()
    exports['glxs-dispatch']:StoreRobbery()
end)
```

***

#### Example 2: Bank Robbery with Custom Message

```lua
-- Pacific Bank with custom description
RegisterNetEvent('pacificBank:alarm', function()
    exports['glxs-dispatch']:BankRobbery("Vault breach detected - Multiple suspects")
end)
```

***

#### Example 3: Officer Down Alert

```lua
-- When officer health drops below threshold
CreateThread(function()
    while true do
        Wait(1000)
        if IsPedDeadOrDying(PlayerPedId()) and isPoliceJob then
            exports['glxs-dispatch']:OfficerDown()
            break
        end
    end
end)
```

***

#### Example 4: Suspicious Activity with Custom Message

```lua
-- Report suspicious behavior
RegisterCommand('report', function()
    exports['glxs-dispatch']:SuspiciousActivity("Suspicious individual near ATM")
end)
```

***

### 🛠️ Custom Alerts

Create your own alert types in **3 simple steps**.

#### Step 1: Define Alert Type in Config

Add your alert to `config/cfg_alerts.lua`:

```lua
Config.AlertTypes = {
    ['my_custom_robbery'] = {
        code = '10-99',                       -- Radio code (shown in UI)
        title = 'Custom Alert',               -- Alert title
        message = 'Custom event reported',    -- Default message
        icon = 'fas fa-exclamation-triangle', -- FontAwesome icon
        priority = 1,                         -- 1=Critical, 2=High, 3=Normal
        soundFile = 'dp_generic.ogg',         -- Sound file from /web/sounds/
        fields = { 
            'location',
            'gender',
            'name',
            'weapon',
            'vehicle',
            'plate',
            'color',
            'vehicleClass',
            'doorCount',
            'heading',
            'message'
        },
        targetJobs = { 'police' },
        locationAccuracy = {
            enabled = false,       -- Location uncertainty enabled
            chanceForExact = 0.0,  -- Chance for exact location (0.0-1.0)
            offsetRange = 50.0,    -- Random offset +/- X meters
            radiusSize = 75.0      -- Radius circle size (meters)
        },    
        blip = {
            sprite = 161,          -- Blip icon ID
            color = 1,             -- 1=Red, 2=Green, 3=Blue, 5=Yellow...
            scale = 1.0,           -- Size (0.5-2.0)
            duration = 60000,      -- Duration on map (ms)
            flash = true,          -- Flash effect
            showRadius = true,     -- Show radius circle
        }
    }
}
```

***

#### Step 2: Create Export Function

Open `client/cl_exports.lua` and scroll to the bottom where you'll find templates.

**Simple Alert (No Parameters):**

```lua
local function MyCustomRobbery()
    local galaxis = CollectAlertContext()
    TriggerServerEvent('glxs-dispatch:server:SendAlert', 'my_custom_robbery', galaxis.coords, galaxis)
end

exports('MyCustomRobbery', MyCustomRobbery)
```

**Alert with Message:**

```lua
local function MyCustomRobbery(message)
    local galaxis = CollectAlertContext()
    galaxis.message = message
    TriggerServerEvent('glxs-dispatch:server:SendAlert', 'my_custom_robbery', galaxis.coords, galaxis)
end

exports('MyCustomRobbery', MyCustomRobbery)
```

***

#### Step 3: Use Your Export

```lua
-- In your script
exports['glxs-dispatch']:MyCustomRobbery("Vault breach in progress!")
```

***

#### 📋 Available Templates in `cl_exports.lua`

The file includes ready-to-use templates:

* **EXAMPLE 1:** Simple alert (no parameters)
* **EXAMPLE 2:** Alert with message parameter
* **EXAMPLE 3:** Alert with extra custom data

Simply **uncomment and modify** the template that fits your needs!

***

### 📊 Available Alert Data

All exports automatically collect:

* `coords` — Player coordinates (automatic)
* `vehicle` — Vehicle model name (automatic, if in vehicle)
* `plate` — License plate (automatic, if in vehicle)
* `color` — Vehicle color (automatic, if in vehicle)
* `weapon` — Current weapon name (automatic, if equipped)
* `message` — Custom description (parameter)
* `gender` — Player gender (server-side, automatic)
* `name` — Player name (server-side, automatic)
* `location` — Street / Area name (server-side, automatic)

💡 Use the `fields` array in each alert config to control **which data displays** in the UI.

***

### 📊 Discord Webhook Logging

Automatically log dispatch alerts to Discord with detailed player and alert information.

#### Setup

Get your Discord webhook URL and add to `config/cfg_main.lua`:

```lua
Config.Logging = {
    enabled = true,
    webhook = 'YOUR_WEBHOOK_URL_HERE',
    
    -- Choose which alert types to log
    alertTypes = {
        ['shooting']         = true,  -- Gunfire/Shots Fired
        ['shooting_vehicle'] = true,  -- Shots from Vehicle
        ['vehicle_theft']    = true,  -- Vehicle Theft
        ['reckless_driving'] = false, -- Speeding/Reckless Driving
        ['explosion']        = true,  -- Explosions
        ['911']              = true,  -- 911 Emergency Calls
        ['911a']             = true,  -- 311 Non-Emergency Calls (alias)
        ['311']              = true,
    },
    
    -- Privacy settings
    includePlayerName   = true,
    includePlayerId     = true,
    includeSteamId      = true,
    includeDiscordId    = true,
    includeLicense      = true,
    includeIP           = false, -- Recommended: false
    includeCoords       = true,
    includeAlertData    = true,
    
    -- Appearance
    embedColor = 15158332,       -- Decimal color code
    embedFooter = 'GLXS Dispatch',
}
```

**Logged Information:**

* Player identifiers (Steam, Discord, License)
* Alert type, message, and coordinates
* Vehicle info, weapons, caller data
* Timestamp

***

### 🧭 Quick Reference

#### Main Settings

| Key                               | Description                | Default  |
| --------------------------------- | -------------------------- | -------- |
| `Config.Locale`                   | Language                   | `'en'`   |
| `Config.UnitDisplay.mode`         | Name / callsign format     | `'name'` |
| `Config.TargetJobs.enabled`       | Job filtering              | `true`   |
| `Config.PlateObfuscation.enabled` | Hide plate characters      | `true`   |
| `Config.SmartMute.enabled`        | Auto-mute in combat        | `false`  |
| `Config.LocationFormat`           | Location display format    | `1`      |
| `Config.DetectionMode.mode`       | Auto-detection sensitivity | `'hard'` |

#### Alert Settings

| Key                               | Description           | Default |
| --------------------------------- | --------------------- | ------- |
| `Config.AlertGrouping.enabled`    | Group similar alerts  | `true`  |
| `Config.AlertGrouping.radius`     | Group radius (meters) | `50.0`  |
| `Config.AlertGrouping.timeout`    | Group timeout (ms)    | `30000` |
| `Config.Dispatch.DefaultDelaySec` | Alert delay (seconds) | `5`     |

***

### 🧰 Troubleshooting

* **Alerts not showing**
  * Check `Config.TargetJobs.enabled` and `jobs` list.
* **Wrong language**
  * Verify `Config.Locale` and locale file in `/locales/`.
* **Too many alerts / spam**
  * Ensure `Config.AlertGrouping.enabled = true`.
* **Duplicate sounds**
  * Enable `Config.SoundCooldown.enabled`.
* **Missing officer names / callsigns**
  * Units might not be attached – use the **“Join Call”** button.
  * For custom codes, verify `SetCustomCallsign` usage.
* **Plates fully visible**
  * Check `Config.PlateObfuscation.enabled` and `chanceToHideChar`.
* **Alerts during combat**
  * Enable `Config.SmartMute` (use with caution).

***

### 📚 Additional Resources

#### Adding New Locale

1. Create `/locales/xx.json` (replace `xx` with language code).
2. Copy structure from `en.json`.
3. Translate all keys.
4. Set `Config.Locale = 'xx'`.

#### Framework Support

* ✅ ESX Legacy (auto-detected)
* ✅ QBCore (auto-detected)
* ✅ QBox (auto-detected)

💡 No manual framework configuration needed.

***

**Version:** `1.0.4`\
**Support:** Discord / Forum Thread


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://galaxis-studios.gitbook.io/galaxis-studios/getting-started/dispatch-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.