API overview#

koja-dispatcher exposes five integration surfaces:

The examples page has complete, copy-paste recipes.

Getting started#

1. Start order#

   Start your resource after koja-dispatcher (and its dependencies oxmysql and koja-lib).
   server.cfg

   ensure oxmysql
   ensure koja-lib
   ensure koja-dispatcher
   ensure my-robberies

2. Call an export#

   The resource folder must be named koja-dispatcher: the folder name is the export namespace.
   server.lua

   local dispatch = exports['koja-dispatcher']
   print(('%d dispatcher(s) on shift'):format(dispatch:GetDispatcherCount()))

3. Handle the result#

   Exports that create something return id, route on success and nil, errorCode on failure. Always check the first value.
   server.lua

   local id, route = exports['koja-dispatcher']:CreateCall({
       coords = vector3(24.5, -1347.3, 29.5),
       caller = 'Store alarm',
       message = 'Silent alarm at the 24/7 on Innocence Blvd',
   })
   if not id then
       print('911 call failed: ' .. tostring(route)) -- route holds the error code
   end

Concepts#

Call lifecycle#

Player calls also end on their own when nobody touched them for 3 times calls.playerReplyWindow. Within calls.playerReplyWindow a second /911 from the same player is added to the open call instead of creating a new one.

Call ids start at 1 and count up per server start.

Incident lifecycle#

Ended incidents stay in GetIncidents() for 20 seconds (Config.Incidents.lifetimeAfterEnd), then disappear. Incident ids start at 1001.

An incident whose caller did not give the location yet is located = false: it sits at an approximate point (up to Config.Calls.approximateRadius = 300 m off). Units that arrive there first search (searching) before they find the scene.

Incidents created from a player (/911 fallback, follow field) follow that player until the first unit is on scene.

Unit lifecycle and statuses#

AI units follow the road graph; air units fly straight. Player units are real players and their position is read from their ped.

Unit purposes (the purpose field): incident, move (staging point), home, hospital, handover, patrol.

Dispatcher lifecycle#

A dispatcher starts a shift at a console (shiftStart hook, then shiftStarted), works calls and incidents, and ends it (shiftEnded) with a summary: minutes, stats, a 1 to 5 star rating and pay. Leaving the server ends the shift without pay. A player on shift is never a field unit at the same time.

The call router#

CreateCall, /911, phone calls, the client SendAlert export and dispatch-script alerts in call mode all go through one router:

If a callCreate hook blocks the call in step 1, the router returns nil and the hook's reason (cancelled when the hook gave none). If an incidentCreate hook blocks the incident in step 2, the router returns nil, 'cancelled'.

Admins switch modes in game with /dispatchadmin. Defaults live in Config.Modes (calls = 'mixed', units = 'mixed', noDispatcher = 'reject').

Data formats#

Coordinates#

Every coords parameter accepts:

x and y must be within ±9000, otherwise the export returns nil, 'invalid'. CreateCall and CreateIncident also take source = serverId instead of coords to use that player's position.

Needs#

need is how many units of each department an incident requires:

need = { police = 2, ems = 1, fire = 0 }

Only police, ems and fire are read. Values are floored and capped at 8 per department; zero and negative values are dropped. An incident with an empty need gets { police = 1 }. Unit types have a power (Config.UnitTypes): SWAT and ladder trucks count as 2.

An incident has two needs: need (the truth) and known (what the dispatcher knows). Exports set both to the same value; generated calls reveal the rest through questions or on scene.

Categories#

robbery, burglary, assault, shooting, domestic, disturbance, suspicious, medical, overdose, fire, traffic, rescue, hostage, pursuit, officer_down, hazmat.

The list is Scenarios.Categories in shared/scenarios.lua. An unknown category is ignored by CreateCall and UpdateIncident and becomes suspicious in CreateIncident.

Priority#

1 (highest) to 3. Values are clamped. Priority 1 incidents are announced as alerts on the radio.

Unit references#

Unit exports take a unit reference:

Unit ids depend on the fleet configuration, so look them up with GetUnits() (for example by callsign) instead of hard-coding them.

Return conventions#

Returned tables are copies: changing them does not change the dispatcher. Exports never throw on bad input.

route is 'call' (rings at the console), 'incident' (created as an incident), 'mdt' (sent to koja-mdt; the id is the MDT call id) or, for player calls added to an open line, 'update'.

Error codes#

Hooks and events#

Every lifecycle point is published twice:

1. As a hook: RegisterHook(name, fn). before hooks (callCreate, incidentCreate, unitAssign, shiftStart) run first and can block the action (with an optional reason) or, for incidentCreate, change it. after hooks run when it happened.
2. As a server-local event: koja-dispatcher:<name> for every after hook, fired right after the hook functions, with the same payload. Listen with AddEventHandler.

Use a hook when you need to block or rewrite something, or want automatic cleanup when your resource stops. Use the event for simple listeners. See Hooks and Events.

Server and client rules#

Own code inside the resource#

If you need to change koja-dispatcher itself, put your own files in server/custom/*.lua and client/custom/*.lua. Both folders are loaded automatically, after all built-in modules, so KOJA.Server.* / KOJA.Client.* are ready when your file runs. Do not add files to server/features/: the manifest lists those files one by one, so a new file there is not loaded. Keep a copy of your custom files when you update.

Versioning#

On start the server prints a banner and, when Config.VersionCheck.enabled is on and koja-lib is started, asks koja-lib for the release status: up to date, development build, update available or critical update (with the first changelog lines and a download link).

Feature-detect from your own resource instead of assuming a version:

local state = GetResourceState('koja-dispatcher')
local version = GetResourceMetadata('koja-dispatcher', 'version', 0)
if state == 'started' then
    print(('koja-dispatcher %s is running'):format(version))
end

-- an export that may not exist in older versions
local ok, id = pcall(function() return exports['koja-dispatcher']:CreateBolo(data) end)

/dispatchcheck (server console or admins) runs a health check: koja-lib, oxmysql, framework, database tables, dispatcher jobs, AI fleet, web build, AI keys, settings, stations and the koja-mdt link.