Dispatch // ~/vipex/docs

The dispatch system is a built-in subsystem of vx_mdt with its own set of server exports, event hooks, and a compatibility layer for third-party dispatch resources.

Dispatch exports are controlled by a separate dispatch.exportAllowlist in config (independent from the core exportAllowlist).

Lifecycle

createDispatchCall(data)

Create a new dispatch call. When coords are provided, a map blip is automatically created for on-duty officers.

---@param data { dep_type: string, call_type: string, title: string, description?: string, location_text?: string, priority?: number, metadata?: table, coords?: vector3, radio_frequency?: number, author_name?: string, author_identifier?: string, blip?: table|false, fields?: table[] }
---@return { id: number }|{ error: string }
local result = exports.vx_mdt:createDispatchCall({
    dep_type = "law",
    call_type = "10-31",
    title = "Robbery in Progress",
    description = "Armed robbery at Fleeca Bank",
    location_text = "Fleeca Bank, Route 68",
    priority = 1,
    coords = vector3(311.6, -278.6, 54.2),
    blip = {
        sprite = 161,     -- GTA blip sprite (default from config)
        colour = 1,       -- GTA blip colour (default from config)
        scale = 0.8,      -- blip scale (default from config)
        duration = 60,    -- seconds before auto-removing (0 = until call ends)
        flash = true,     -- flash the blip (default: auto for P0/P1)
        text = "Robbery", -- blip label (default: call title)
    },
    fields = {
        { type = "plate", value = "ABC123" },
        { type = "vehicle", value = "Sultan", data = "ABC123" },
        { type = "color", value = "Red", data = "27" },
        { type = "speed", value = "142" },
        { type = "person", value = "John Smith", data = "ABC12345" },
        { label = "WEAPON", value = "AK-47" },
    },
})

The blip parameter is optional:

Omit — uses config defaults, blip appears at call coords
Table — override specific blip properties (all fields optional)
false — suppress the blip for this call entirely

The fields parameter adds structured data fields visible on the dispatch notification and in the MDT call detail. Each field entry can use a pre-defined type (with auto-populated label/icon and interactive behavior) or a custom label+value pair.

Pre-defined types:

Type	Label	Behavior
`plate`	PLATE	Clickable in MDT — opens vehicle record
`vehicle`	VEHICLE	Clickable if `data` contains the plate
`color`	COLOR	Renders a hex color swatch (set `data` to the GTA color index)
`person`	SUSPECT	Clickable if `data` contains the citizen identifier
`speed`	SPEED	Color-coded by threshold, appends "km/h"

Custom fields use label + value directly: { label = "WEAPON", value = "AK-47" }

All fields support an optional icon (Iconify name) and data (navigation target or color index).

updateDispatchCall(callId, data)

Update fields on an active dispatch call.

---@param callId number Dispatch call ID
---@param data table Fields to update
exports.vx_mdt:updateDispatchCall(callId, {
    priority = 2,
    description = "Suspects fleeing on foot",
})

completeDispatchCall(callId)

Mark a dispatch call as completed.

---@param callId number Dispatch call ID
exports.vx_mdt:completeDispatchCall(callId)

cancelDispatchCall(callId)

Cancel a dispatch call.

---@param callId number Dispatch call ID
exports.vx_mdt:cancelDispatchCall(callId)

Assignment

attachDispatchCall(callId, source)

Attach an officer to a dispatch call.

---@param callId number Dispatch call ID
---@param source number Player server ID
exports.vx_mdt:attachDispatchCall(callId, source)

detachDispatchCall(callId, source)

Detach an officer from a dispatch call.

---@param callId number Dispatch call ID
---@param source number Player server ID
exports.vx_mdt:detachDispatchCall(callId, source)

addDispatchCallUpdate(callId, content, author)

Add a status update to a dispatch call.

---@param callId number Dispatch call ID
---@param content string Update text
---@param author string Author name
exports.vx_mdt:addDispatchCallUpdate(callId, "Suspects in custody", "Officer Smith")

Query

getDispatchCall(callId)

Get a dispatch call by ID.

---@param callId number Dispatch call ID
---@return table|nil Dispatch call or nil
local call = exports.vx_mdt:getDispatchCall(callId)

getActiveDispatchCalls(depType?)

Get all active dispatch calls, optionally filtered by department type.

---@param depType? string Optional: "law", "ems", or "judge"
---@return table[] Array of active dispatch calls
local calls = exports.vx_mdt:getActiveDispatchCalls("law")

Hooks

Subscribe to dispatch events for real-time integrations.

onDispatch(event, handler)

---@param event "created"|"updated"|"deleted"|"attached"|"detached"|"completed"|"cancelled"
---@param handler function Callback receiving event data
---@return number Listener ID
local listenerId = exports.vx_mdt:onDispatch("created", function(call)
    print("New dispatch call:", call.title)
end)

offDispatch(listenerId)

Unregister a dispatch event listener.

---@param listenerId number Listener ID from onDispatch
exports.vx_mdt:offDispatch(listenerId)

Auto-Detection

Auto-detection listens for GTA game events and automatically creates dispatch calls — no third-party dispatch resource required. Disabled by default; set dispatch.autoDetection.enabled = true to opt in.

config/shared/global.lua

dispatch = {
    autoDetection = {
        enabled = true,
        events = {
            gunshot = { enabled = true, cooldown = 15, priority = 2 },
            fight = { enabled = true, cooldown = 30, priority = 3 },
            carjacking = { enabled = true, cooldown = 20, priority = 1 },
            vehicleTheft = { enabled = true, cooldown = 30, priority = 2 },
            explosion = { enabled = true, cooldown = 20, priority = 1 },
            speeding = { enabled = true, cooldown = 45, speedThreshold = 130, priority = 3 },
        },
        fields = {
            plate = true,
            vehicleColor = true,
            speed = true,
            heading = true,
            suspect = true,
            owner = true,
        },
    },
},

Structured Fields

Auto-detected calls attach structured data fields to the notification card and MDT detail view. Each field can be individually toggled via autoDetection.fields:

Field	Description
`plate`	Vehicle plate number
`vehicleColor`	Vehicle color with hex swatch (uses GTA color index)
`speed`	Vehicle speed in km/h (speeding events only)
`heading`	Compass heading (N, NE, E, SE, etc.)
`suspect`	Suspect sex description
`owner`	Registered vehicle owner name (looked up from the database by plate, cached for 120 seconds)

When owner is enabled and the vehicle plate matches a registered vehicle, the owner's name is automatically resolved and displayed as a clickable link to their profile in the MDT.

Detected Events

Event	Game Trigger	Title	Default Priority
`gunshot`	CEventGunShot	Shots Fired / Drive-By Shooting	2
`fight`	CEventShockingSeenMeleeAction	Fight In Progress	3
`carjacking`	CEventPedJackingMyVehicle	Carjacking In Progress	1
`vehicleTheft`	CEventShockingCarAlarm	Vehicle Theft	2
`explosion`	CEventExplosionHeard	Explosion Reported	1
`speeding`	Multiple driving events	Speeding Vehicle	3

Each event can be individually enabled/disabled and has its own cooldown. The speeding event has an additional speedThreshold (km/h) — only vehicles exceeding this speed trigger a call.

On-duty LEO/EMS players are automatically exempt and will never trigger auto-detected calls. Silenced weapons, aircraft, and unarmed hits are filtered out. Server-side rate limiting prevents abuse (max 5 events per 15 seconds per player).

Compatibility Mode

Set dispatch.dispatchCompat in config to the name of your third-party dispatch resource to intercept its calls and route them into vx_mdt automatically.

Supported values: "cd_dispatch", "cd_dispatch3d", "ps-dispatch", "rcore_dispatch", "fd_dispatch", or "" (disabled).

dispatch = {
    dispatchCompat = "cd_dispatch",
},

When compatibility mode is enabled, you do not need to remove the third-party dispatch resource. vx_mdt intercepts its events and exports transparently.

Dispatch

On this page