Jobs and services
Police alerts, prison, MDT records, medics, revive and heal, stress, hunger and thirst, job and gang definitions, prime time.
import { jobs, dispatch, prison, mdt, ems, medical, stress, needs, definitions, isPrimeTime } from "@aifivem/lib/server";jobs and definitions are ai-core itself: the jobs and gangs of a character, and the job definitions of the server. Everything else here goes through one of ai-core's layers, where the script the server runs for that job (an alert system, a prison, an MDT, a death script, a HUD) answers. Your script keeps working when the owner swaps it. While no such script runs, those calls fail quietly (false, 0, null).
jobs
jobs is a loaded player's own jobs and gangs through ai-core: a character may hold several jobs, is on duty in at most one, and acts for one gang at a time. Reading many players at once is the lib's mirror online; changing a character who is not connected is characters.
jobs.current
The job other scripts see as "the" job of a player: the one they are on duty in, else the last one they were on duty in, else the first they hold, else the unemployed job.
Side: Server · Waits: no
jobs.current(source: number): JobMembership | nulllocal current = aiLib.jobs.current(source)Returns
A JobMembership ({ job, grade }), or null when the player has no loaded character.
Example
import { jobs } from "@aifivem/lib/server";
export function isOfficer(source: number): boolean {
return jobs.current(source)?.job === "police";
}jobs.list
Every job the player holds.
Side: Server · Waits: no
jobs.list(source: number): JobMembership[]local list = aiLib.jobs.list(source)Returns
An array of JobMembership. Empty when the player has no loaded character or holds nothing.
jobs.duty and jobs.setDuty
Which job the player is on duty in, and going on or off duty. Many scripts check duty rather than membership: an officer off duty is a civilian.
Side: Server · Waits: no
jobs.duty(source: number): string | null
jobs.setDuty(source: number, job: string | null): booleanlocal onDutyIn = aiLib.jobs.duty(source)
local ok = aiLib.jobs.setDuty(source, job)Parameters
Prop
Type
Returns
jobs.duty: the job name, or null when off duty (or no character). jobs.setDuty: true when the change was made, false for a job the player does not hold.
jobs.set
Adds a job to the player, or regrades a job they already hold. The panel's rules apply: how many jobs a character may hold and whether a second one is allowed at all.
Side: Server · Waits: no
jobs.set(source: number, job: string, grade: number): booleanlocal ok = aiLib.jobs.set(source, job, grade)Parameters
Prop
Type
Returns
boolean: true when the player holds the job at that grade afterwards. false for no loaded character, an unknown job, an unknown grade, or the panel's job limit.
Example
import { jobs, notify } from "@aifivem/lib/server";
export function hire(source: number, job: string): void {
if (!jobs.set(source, job, 0)) return notify(source, "Could not hire you", "error");
notify(source, `Welcome to ${job}`, "success");
}jobs.remove
Takes a job away. A character with no jobs left counts as unemployed: the unemployed job itself is never stored.
Side: Server · Waits: no
jobs.remove(source: number, job: string): booleanlocal ok = aiLib.jobs.remove(source, job)Returns
boolean: true when the job was taken away, false when the player did not hold it (or has no loaded character).
jobs.unemployed
The job name a character without a job has, as set in the panel. Never assume "unemployed": a server can call it anything.
Side: Server · Waits: no
jobs.unemployed(): stringlocal name = aiLib.jobs.unemployed()Returns
string: the job name from the panel.
jobs.onDutyCount
How many players are on duty in a job right now - the number a dispatch or a job gate usually wants.
Side: Server · Waits: no
jobs.onDutyCount(job: string): numberlocal count = aiLib.jobs.onDutyCount(job)Returns
number: how many connected players are on duty in that job, 0 when nobody is.
jobs.gangs
Every gang the player is in.
Side: Server · Waits: no
jobs.gangs(source: number): GangMembership[]local list = aiLib.jobs.gangs(source)Returns
An array of GangMembership, empty when the player is in none.
jobs.activeGang and jobs.setActiveGang
A character may be in several gangs but acts for one at a time: that is the active gang, and it is the one a turf or a drug script should read.
Side: Server · Waits: no
jobs.activeGang(source: number): string | null
jobs.setActiveGang(source: number, gang: string | null): booleanlocal active = aiLib.jobs.activeGang(source)
local ok = aiLib.jobs.setActiveGang(source, gang)Returns
jobs.activeGang: the gang name, or null when none is active. jobs.setActiveGang: true when the change was made, false for a gang the player is not in (null clears it).
jobs.setGang and jobs.removeGang
Adds, regrades or removes a gang of the player.
Side: Server · Waits: no
jobs.setGang(source: number, gang: string, grade: number): boolean
jobs.removeGang(source: number, gang: string): booleanlocal ok = aiLib.jobs.setGang(source, gang, grade)
local ok = aiLib.jobs.removeGang(source, gang)Returns
boolean, like the job calls: false for no loaded character, an unknown gang or an unknown grade.
dispatch
dispatch.alert
Sends a police (or other job) alert. The alert system shows it to the on-duty members of jobs, default the police jobs.
Side: Server · Waits: no
dispatch.alert(alert: DispatchAlert): booleanlocal ok = aiLib.dispatch.alert(alert)DispatchAlert
Prop
Type
The type is DispatchAlert.
Returns
boolean: true when sent. false when no alert system runs or the alert is invalid.
Example
import { dispatch, coordsOf, createLocale } from "@aifivem/lib/server";
const Locale = createLocale();
function storeRobbed(source: number, store: string) {
dispatch.alert({
code: "10-90",
title: Locale("ALERT_STORE_ROBBERY"),
message: store,
coords: coordsOf(source),
source,
icon: "store",
priority: "high",
});
}prison
Jail sentences through ai-core, whatever prison script runs.
prison.jail
Sends a loaded player to prison.
Side: Server · Waits: no
prison.jail(source: number, minutes: number, by?: number): booleanlocal ok = aiLib.prison.jail(source, minutes, by)Prop
Type
Returns true when jailed, false while no prison runs.
if (!prison.jail(target, 15, officer)) return fail("NO_PRISON");prison.release
Lets a jailed player out.
Side: Server · Waits: no
prison.release(source: number): booleanlocal ok = aiLib.prison.release(source)Returns true when released, false when not jailed or no prison runs.
prison.release(target);prison.timeLeft
Side: Server · Waits: no
prison.timeLeft(source: number): numberlocal minutes = aiLib.prison.timeLeft(source)Returns the minutes of sentence left, 0 when free.
if (prison.timeLeft(source) > 0) return fail("IN_PRISON");mdt
Police MDT records (fines, warrants, arrests, jail) through ai-core's MDT layer. Nothing is written while no MDT runs.
mdt.record
Writes a record into the police MDT.
Side: Server · Waits: no
mdt.record(record: MdtRecord): booleanlocal ok = aiLib.mdt.record(record)MdtRecord
Prop
Type
The type is MdtRecord.
Returns true when written, false when no MDT runs or it takes no such record.
if (prison.jail(target, 20, officer)) mdt.record({ kind: "jail", target, by: officer, title: "Armed robbery", minutes: 20 });mdt.provider
Side: Server · Waits: no
mdt.provider(): string | nulllocal name = aiLib.mdt.provider()Returns the MDT that records go to, or null.
if (!mdt.provider()) console.log("no MDT: records are skipped");ems
Medics through ai-core's EMS layer: an EMS script's own count and distress calls, else ai-core's duty counts and alerts.
ems.available
How many medics are free to take a call.
Side: Server · Waits: no
ems.available(jobs: string[]): numberlocal count = aiLib.ems.available(jobs)Prop
Type
Returns the number of medics on duty in jobs, leaving out busy ones when a dispatch script knows them.
// Let players respawn at the hospital only when no medic can come.
const canRespawn = ems.available(["ambulance"]) === 0;ems.distress
Sends a distress call for a player to the medics of call.jobs.
Side: Server · Waits: no
ems.distress(source: number, call: DistressCall): booleanlocal ok = aiLib.ems.distress(source, call)Prop
Type
The type is DistressCall.
Returns true when something took the call, false otherwise.
if (!ems.distress(source, { jobs: ["ambulance"], message: "Unconscious" })) return fail("NO_MEDICS");ems.provider
Side: Server · Waits: no
ems.provider(): string | nulllocal name = aiLib.ems.provider()Returns the EMS source the layer uses, "ai-core" for its own duty counts.
console.log(`medics through ${ems.provider()}`);medical
Revive, heal and the down state through ai-core's medical layer, whatever death or ambulance script runs. No Lua twin: call ai-core's exports RevivePlayer, HealPlayer, IsPlayerDead.
medical.revive
Gets a downed player up where they lie.
Side: Server · Waits: no
medical.revive(source: number): booleanReturns true when revived, false when not down or no death script runs.
if (!medical.revive(target)) return fail("NOT_DOWN");medical.heal
Gives full health to a player who is not down.
Side: Server · Waits: no
medical.heal(source: number): booleanReturns true when healed, false when no death script runs.
medical.heal(source);medical.isDead
Whether the player is down.
Side: Server · Waits: no
medical.isDead(source: number): booleanReturns true when down; false without a death script. Use it instead of reading the ped's health.
if (medical.isDead(source)) return fail("YOU_ARE_DOWN");medical.provider
Side: Server · Waits: no
medical.provider(): string | nullReturns the death script that answers (ai-death...), or null when none runs.
console.log(`deaths through ${medical.provider() ?? "nothing"}`);stress
Players' stress (0 to 100) through ai-core's stress layer, whatever HUD keeps it.
stress.gain
Adds stress points.
Side: Server · Waits: no
stress.gain(source: number, amount: number): booleanlocal ok = aiLib.stress.gain(source, amount)Prop
Type
Returns true when added, false when no HUD with stress runs.
stress.gain(source, 5); // after a shootoutstress.relieve
Takes stress points away.
Side: Server · Waits: no
stress.relieve(source: number, amount: number): booleanlocal ok = aiLib.stress.relieve(source, amount)Returns true when taken, false when no HUD with stress runs or amount is 0 or less.
inventory.registerUsableItem("cigarette", (source) => {
stress.relieve(source, 10);
});stress.provider
Side: Server · Waits: no
stress.provider(): string | nulllocal name = aiLib.stress.provider()Returns the HUD that keeps stress, or null.
if (!stress.provider()) console.log("no HUD keeps stress");needs
needs.refill
Fills hunger and thirst to full (admin revive, hospital), through the HUD that keeps them, or ai-core's character metadata without one.
Side: Server · Waits: no
needs.refill(source: number): booleanNo Lua twin: call ai-core's export RefillNeeds(source).
Returns true when refilled, false when the player has no character.
if (medical.revive(target)) needs.refill(target);Job and gang definitions
definitions.job
A job's definition as set in ai-core's panel. Each one is read once from ai-core and kept until the panel changes it, so a read is a memory lookup.
Side: Server · Waits: no
definitions.job(name: string): JobDefinition | nulllocal definition = aiLib.definitions.job(name)Returns JobDefinition (label, type, defaultDuty, listed?, grades), or null when no such job exists.
const label = definitions.job("police")?.label ?? "police";definitions.gang
Side: Server · Waits: no
definitions.gang(name: string): GangDefinition | nulllocal definition = aiLib.definitions.gang(name)Returns GangDefinition (label, grades), or null.
const gang = definitions.gang("ballas");
if (!gang) return fail("UNKNOWN_GANG");definitions.registerJob and definitions.removeJob
A job your script brings with it, without the owner adding it in the panel: a job of the calling resource, gone when the resource stops and never written to the panel's file.
Side: Server · Waits: no
definitions.registerJob(name: string, definition: JobDefinition): CharacterResult
definitions.removeJob(name: string): booleanlocal result = aiLib.definitions.registerJob(name, definition)
local ok = aiLib.definitions.removeJob(name)Parameters
Prop
Type
Returns
registerJob answers ActionResult: { ok: true }, or { ok: false, error } with a lang key when the panel already has a job of that name or another resource registered it - the owner's panel always wins. removeJob answers true only for a job this resource registered.
Example
import { definitions } from "@aifivem/lib/server";
// Once at start: the job exists while this resource runs.
const result = definitions.registerJob("garbage", {
label: "Garbage",
type: "job",
defaultDuty: true,
grades: [{ label: "Driver", salary: 60, boss: false }],
});
if (!result.ok) console.log(`job not registered: ${result.error}`);A job the server owner should be able to edit belongs in the panel, not here. Register one when the job is part of your script and means nothing without it.
definitions.registerGang and definitions.removeGang
The same for gangs.
Side: Server · Waits: no
definitions.registerGang(name: string, definition: GangDefinition): CharacterResult
definitions.removeGang(name: string): booleanlocal result = aiLib.definitions.registerGang(name, definition)
local ok = aiLib.definitions.removeGang(name)Returns
As with jobs: ActionResult for the registration, boolean for the removal.
Prime time
isPrimeTime
Whether it is prime time for a job, from ai-core's prime time setting. The hours come from tgiann-policealert while it runs, else from the hours set in ai-core's panel.
Side: Server · Waits: no
isPrimeTime(job?: string): booleanNo Lua twin: call ai-core's export IsPrimeTime(job).
Prop
Type
Returns true during prime time.
if (!isPrimeTime("police")) return fail("BANK_CLOSED_FOR_HEISTS");