Configuration

Reference for every config file shipped with oxide-dispatch. All config files live under shared/ and are listed in escrow_ignore so they remain editable.

shared/config.lua

Global runtime settings — broadcast policy, popup behavior, auto-expiry, and the heatmap cache.

Config.AutoExpire = {
    enabled = true,
    defaultMinutes = 15,
    sweepIntervalSec = 30,
}

Config.Broadcast = {
    onDutyOnly = true,
    maxJobsPerAlert = 12,
    rateLimitMs = 5000,
}

Config.DispatchHub = {
    RadialEnabled = true,
}

Config.Popup = {
    durationMs = 20000,
    maxStacked = 3,
    mapZoom = 3,
    soundEffect = 'Lose_1st',
    soundSet = 'GTAO_FM_Events_Soundset',
}

Config.Heatmap = {
    enabled       = true,
    defaultWindow = '30d',
    cacheSeconds  = 60,
    maxPoints     = 5000,
}

shared/config/alerts.lua

The dispatch code catalog. Producers supply a code field on every alert; this catalog supplies the defaults (title, priority, icon, blip) for any field the producer does not explicitly populate. Per-alert sound overrides are also supported via data.soundEffect / data.soundSet.

Config.Codes

A mapping of code → { title, priority, icon, blip }. Each entry's blip is { sprite, color, scale }. Priority 1 is highest.

Config.GetCodeDefaults(code)

Helper used by the alert pipeline. Returns the catalog entry for the code, or a generic fallback (title = code, priority = 3, icon = 'fas fa-triangle-exclamation', generic blip) when the code is not in the catalog.

local defaults = Config.GetCodeDefaults('10-71')
-- { title = 'Shots Fired', priority = 1, icon = 'fas fa-gun', blip = {...} }

To add a new code, drop a new entry into Config.Codes:

Config.Codes['10-100'] = {
    title    = 'Burglary in Progress',
    priority = 2,
    icon     = 'fas fa-house-lock',
    blip     = { sprite = 161, color = 1, scale = 1.1 },
    -- optional per-code sound override:
    -- soundEffect = '...', soundSet = '...',
}

shared/config/jobs.lua

Maps responder group keys (police, ems, fire) to framework job names plus the UI metadata used by the Dispatch radial menu and panic title resolver.

Config.ResponderGroups

Each entry defines:

Config.ResponderGroups = {
    police = {
        jobs  = { 'police', 'lspd', 'bcso', 'sasp', 'sheriff', 'statetrooper',
                  'LSPD', 'BCSO', 'SASP' },
        label = 'Officer',
        icon  = 'shield-halved',
    },
    ems = {
        jobs  = { 'ambulance', 'ems', 'EMS' },
        label = 'Paramedic',
        icon  = 'truck-medical',
    },
    fire = {
        jobs  = { 'fire', 'FIRE' },
        label = 'Firefighter',
        icon  = 'fire',
    },
}

A radialId field from older configs is ignored — all groups now share the single Dispatch radial menu. You can safely delete the field.

Job-name matching is case-sensitive. Include every casing your framework actually uses.

Only jobs is required per group — label and icon are optional and are auto-filled from the group key when omitted. The older config shape where a group was just a plain list of job names (police = { 'police', 'lspd' }) is auto-migrated at load, so configs edited before the metadata fields existed keep working.

Config.ResolveJobsDefault

Fallback used when a producer omits jobs. nil (the default) means an alert with no jobs reaches no recipients and a one-time warning is logged. Set to a group key (e.g. 'police') to opt back into the legacy silent-fallback behavior.

Config.ResolveJobsDefault = nil    -- or 'police' to silently default

Config.ResolveJobs(input)

Normalizes producer inputs into a flat job-name array.

Config.GetGroupForJob(jobName)

Reverse lookup. Returns the group key ('police', 'ems', 'fire') that owns a given raw job name, or nil if it isn't grouped. Used by the broadcast layer, panic subsystem, and per-group status broadcasts.

Adding a new responder group

To add a new responder group (for example coastguard):

1. Add the group key + jobs to Config.ResponderGroups here.
2. Add a status list under the same key in Config.ResponderStatuses (or rely on _default).
3. (Optional) Add a titles / messages entry for the group in Config.Panic so panic alerts read naturally.

Full recipes (add a job, rename a job, build a new group) live in the Jobs & Responder Groups guide.

shared/config/statuses.lua

Per-session responder status states. Each responder group has its own status list so police-coded labels (Code-4, 10-7) don't leak into EMS/Fire UIs. Status changes broadcast to colleagues in the SAME group.

Config.ResponderStatuses

Each entry is a list of { id, label, color, icon } rows.

Config.ResponderStatusDefault

Helpers

Config.ResponderCallsign

Config.ResponderCallsign = {
    maxLength = 16,
    pattern   = '^[%w%-]+$',     -- alphanumerics + hyphen
    -- pattern = '^[%w%-%.]+$',  -- alphanumerics + hyphen + dot ('A-12.5')
    -- pattern = '^[%w%-/%.]+$', -- alphanumerics + hyphen + slash + dot ('EMS/01')
}

shared/config/detection.lua

Toggles the automatic crime detection module. Each detector funnels into the standard alert pipeline (rate limiting + duty filter + persistence apply normally).

Config.Detection

Every detector accepts a jobs field for recipient routing. It takes the same input as Config.ResolveJobs: a responder-group key ('police'), a raw job name ('lspd'), or an array of either.

Every detector also accepts chance (number, default 1.0) — the 0.0–1.0 probability that a qualifying event is reported (0.0 disables it, like enabled = false). For the cooldown-gated detectors the roll happens once per cooldown window; Death rolls once per death.

Config.Detection.WeaponBlacklist

Weapons that should never trigger an automatic alert (less-lethal, training weapons, fists). Each key is a weapon, each value is true. Write the weapon name inside backticks (e.g. `WEAPON_PISTOL`) — the game converts the backticked name into the weapon hash it uses internally.

Config.Detection.WeaponBlacklist = {
    [`WEAPON_UNARMED`] = true,
    [`WEAPON_STUNGUN`] = true,
    [`WEAPON_FLAREGUN`] = true,
}

Config.Detection.ZoneBlacklist

Geographic exclusion zones — shooting/explosion in these areas won't alert. Each entry: { coords = vector3, radius = number, label = string }.

Config.Detection.ZoneBlacklist = {
    -- { coords = vector3(450.0, -980.0, 30.0), radius = 60.0, label = 'Mission Row PD' },
    -- { coords = vector3(842.0, -1290.0, 28.0), radius = 80.0, label = 'PD Range' },
}

Config.Detection.JobBlacklist

Jobs whose holders should never trip an auto-detect alert. Keys are framework job names and must exactly match the job name as your framework spells it (case-sensitive); values true. Use this to stop on-duty responders from dispatching themselves whenever they fire their service weapon, commandeer a vehicle in pursuit, or take a melee hit on the job. Manual paths (911, panic, MDT-issued alerts) ignore this list.

Config.Detection.JobBlacklist = {
    -- ['police']       = true,
    -- ['lspd']         = true,
    -- ['bcso']         = true,
    -- ['sasp']         = true,
    -- ['sheriff']      = true,
    -- ['statetrooper'] = true,
    -- ['ambulance']    = true,
    -- ['ems']          = true,
    -- ['fire']         = true,
}

shared/config/panic.lua

Two distinct subsystems live in this file: the panic / responder-needs-backup alert (separate from the panic dispatch code) and the civilian 911/311 category catalog.

Config.Panic

Config.Panic = {
    cooldownSec = 60,
    broadcastOffDuty = true,
    autoWaypoint = true,
    soundEffect = nil,
    soundSet = nil,
    titles = {
        police   = 'OFFICER NEEDS BACKUP',
        ems      = 'MEDIC NEEDS BACKUP',
        fire     = 'FIREFIGHTER NEEDS BACKUP',
        _default = 'RESPONDER NEEDS BACKUP',
    },
    messages = {
        police   = 'Officer panic alert',
        ems      = 'Medic panic alert',
        fire     = 'Firefighter panic alert',
        _default = 'Responder panic alert',
    },
}

Config.Civilian

Configures the citizen 911 / 311 menu (radial + chat commands).

Each category entry is { id, label, code, jobs, icon? }. jobs accepts the same input Config.ResolveJobs does (group key, raw job, or array).

Config.Civilian = {
    anonymousDefault = true,
    maxMessageLength = 240,

    Categories911 = {
        { id = 'crime',    label = 'Crime in Progress',   code = '10-31', jobs = 'police' },
        { id = 'medical',  label = 'Medical Emergency',   code = '10-52', jobs = 'ems' },
        { id = 'injury',   label = 'Person Injured',      code = '10-56', jobs = 'ems' },
        { id = 'overdose', label = 'Overdose',            code = '10-58', jobs = 'ems' },
        { id = 'fire',     label = 'Structure Fire',      code = '10-70', jobs = 'fire' },
        { id = 'vfire',    label = 'Vehicle Fire',        code = '10-73', jobs = 'fire' },
        { id = 'hazmat',   label = 'Hazmat / Spill',      code = '10-75', jobs = 'fire' },
        { id = 'shooting', label = 'Shots Fired',         code = '10-71', jobs = 'police' },
        { id = 'accident', label = 'Vehicle Accident',    code = '10-50', jobs = { 'police', 'ems' } },
        { id = 'other',    label = 'Other Emergency',     code = '911',   jobs = { 'police', 'ems', 'fire' } },
    },

    Categories311 = {
        { id = 'tip',         label = 'Anonymous Tip',       code = '311',   jobs = 'police' },
        { id = 'noise',       label = 'Noise Complaint',     code = '311',   jobs = 'police' },
        { id = 'suspicious',  label = 'Suspicious Person',   code = '10-66', jobs = 'police' },
        { id = 'medical_q',   label = 'Medical Question',    code = '311',   jobs = 'ems' },
        { id = 'fire_safety', label = 'Fire / Safety Issue', code = '311',   jobs = 'fire' },
        { id = 'other',       label = 'Other Non-Emergency', code = '311',   jobs = 'police' },
    },
}

shared/config/compat.lua

Per-framework toggles for the legacy police-alert shims. The shims forward old QB/ESX events into the modern Alerts.Create pipeline so existing scripts keep working without edits.

Top-level toggles

Config.Compatibility['qb-core']

When Config.Detection.Death.enabled AND ambulanceAlert are both on, the shared rateLimitMs absorbs the duplicate alert that fires when a player dies. If you set rateLimitMs = 0, disable one of the two to avoid duplicates.

Config.Compatibility['qb-core'] = {
    enabled = true,
    serverPoliceAlert = true,
    clientPoliceAlert = false,
    ambulanceAlert = true,
    emergencyAlert = true,
    clientAmbulanceAlert = false,
    emsJobs = 'ems',
    emsCode = '10-52',
    jobs = 'police',
    defaultCode = '10-31',
    rateLimitMs = 5000,
    mirrorQbPhone = false,
    keywordCodes = {
        { pattern = 'drug',       code = '10-99' },
        { pattern = 'narcotic',   code = '10-99' },
        { pattern = 'store',      code = '10-91' },
        { pattern = 'bank',       code = '10-90' },
        { pattern = 'jewel',      code = '10-90' },
        { pattern = 'suspicious', code = '10-66' },
        { pattern = 'suspicous',  code = '10-66' },  -- common misspelling
        { pattern = 'vehicle',    code = '10-80' },
        { pattern = 'robbery',    code = '10-31' },
    },
}

Config.Compatibility['es_extended']

Config.Compatibility['es_extended'] = {
    enabled = true,
    serverPoliceAlert = true,
    clientPoliceAlert = false,
    esxPhoneSend = true,
    outlawAlert = true,
    distressAlert = true,
    esxPhoneEms = true,
    emsJobs = 'ems',
    emsCode = '10-52',
    jobs = 'police',
    defaultCode = '10-31',
    rateLimitMs = 5000,
    keywordCodes = {
        { pattern = 'drug',       code = '10-99' },
        { pattern = 'narcotic',   code = '10-99' },
        { pattern = 'store',      code = '10-91' },
        { pattern = 'bank',       code = '10-90' },
        { pattern = 'jewel',      code = '10-90' },
        { pattern = 'suspicious', code = '10-66' },
        { pattern = 'suspicous',  code = '10-66' },
        { pattern = 'vehicle',    code = '10-80' },
        { pattern = 'robbery',    code = '10-31' },
        { pattern = 'shot',       code = '10-71' },
        { pattern = 'gun',        code = '10-32' },
    },
}

QBX

QBX uses the same police:server:policeAlert event names QBCore does (verified across qbx_bankrobbery, qbx_truckrobbery, qbx_houserobbery, qbx_jewelery, qbx_storerobbery, qbx_vehiclekeys, and the legacy qbx_police). The qb-core shim above handles QBX traffic — there is no separate qbx_core block. See the QBX Setup page for QBX-specific notes.

shared/config/ai_dispatch.lua

Configuration for the optional AI Radio Dispatcher feature — provider selection, radio channels (one per department job), idle timeout, identifier whitelist, integration toggles, model and voice choices.

Each of the four blocks above (Realtime, Chained.STT, Chained.LLM, Chained.TTS) also accepts a BaseUrl (the address of the service, needed only for 'custom' or a non-default port) and an ApiKey (used instead of the provider's convar). Both are unset by default.

Channel entry fields (Config.AIDispatch.Channels[N])

Three channels ship enabled by default: 911 → job 'police' (voice ash), 921 → 'ambulance' (voice shimmer), and 931 → 'fire' (voice sage). Channels 912 (BCSO) and 913 (SASP) are included as commented-out examples.

Important: each channel's job must match a job name that actually exists on your server, spelled exactly as your framework has it (usually lowercase). If your police job isn't called police (e.g. lspd), change channel 911's job value — otherwise no player will pass the channel's job check.

Config.AIDispatch.RadioFX

The radio-static filter applied to the AI dispatcher's voice — band-limiting, light distortion, and a faint background hiss make it sound like a real comms radio instead of a clean synthesized stream.

API key

The OpenAI API key is not stored in this file. Set it as a server convar (a server-side variable, set in server.cfg or the live console):

set oxide:ai-dispatch:openai_key sk-...your-key-here...

Use set, not setr — setr replicates the value to every connected player and would leak your key.

Each provider reads its own line, named after the provider — so a step set to Provider = 'groq' looks for oxide:ai-dispatch:groq_key:

set oxide:ai-dispatch:groq_key       gsk-...
set oxide:ai-dispatch:openrouter_key sk-or-...
set oxide:ai-dispatch:lemonfox_key   ...
set oxide:ai-dispatch:custom_key     ...

Providers that run on your own machine (ollama, lmstudio, kokoro, speaches) need no key — leave the line out entirely. On startup the server log lists every step, the provider it resolved to, and the address it will use, so you can confirm what's actually configured.

Full feature documentation, cost notes, voice options, identifier-whitelist usage, and privacy disclosure templates live in the AI Radio Dispatcher guide.

shared/config/ai_dispatch_acks.lua

Spoken acknowledgements for the AI dispatcher. When the dispatcher decides to look something up (a plate, a person's records, a BOLO), the chained pipeline can take a few seconds to answer. To avoid dead silence on the radio while that happens, a short pre-rendered acknowledgement plays the moment the lookup starts — "Running that plate.", "Pulling those records.", and so on.

Config.AIDispatch.Acks

The audio clips are generated automatically on first server startup using each channel's text-to-speech voice and cached on disk under <resource>/cache/acks/<voice>/. You can add or edit phrases freely — changed phrases are re-rendered on the next boot while unchanged ones are reused from the cache.

Shipped phrase lists cover the core dispatch tools (create_dispatch_alert, cancel_dispatch_alert, attach_responder, detach_responder, set_responder_status, set_officer_status, trigger_panic, list_active_alerts, update_dispatch_alert) and the police MDT tools (lookup_plate, lookup_person, get_person_profile, create_bolo, list_active_bolos, clear_bolo, list_on_duty_officers, check_custody).

shared/config/ai_dispatch_prompt.lua

The dispatcher's system prompt — the behavior contract the AI follows. Built per session by Config.BuildAIDispatchPrompt(job, hasPoliceTools) and used by both the realtime and chained providers.

Structure:

• JOB_BLOCKS — per-job lookup of { name, flavor }. name is how the dispatcher introduces itself ("LSPD", "BCSO", "EMS", etc.); flavor selects which routing-rules block applies ('police', 'ems', 'fire', or nil for generic). Add a key for any custom job you want to tune.
• FLAVOR_ROUTING — three blocks of natural-language routing guidance keyed by flavor.
• BASE_PROMPT, CORE_TOOL_RULES, POLICE_TOOL_RULES, RADIO_AWARENESS — structural sections spliced together by BuildAIDispatchPrompt. Police MDT guidance is only included when the channel's job qualifies for those tools.

Jobs that aren't in JOB_BLOCKS get a generic uppercase fallback (e.g. 'amr_paramedic' → "AMR_PARAMEDIC dispatch"). If you customize the prompt, keep the structural sections intact — the model relies on them to use the tools correctly.

Next Steps