AI Core

Jobs and services

Police alerts, prison, MDT records, medics, revive and heal, stress, hunger and thirst, job and gang definitions, prime time.

TypeScript
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

Signature
jobs.current(source: number): JobMembership | null
Lua
local 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

Signature
jobs.list(source: number): JobMembership[]
Lua
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

Signature
jobs.duty(source: number): string | null
jobs.setDuty(source: number, job: string | null): boolean
Lua
local 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

Signature
jobs.set(source: number, job: string, grade: number): boolean
Lua
local 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

Signature
jobs.remove(source: number, job: string): boolean
Lua
local 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

Signature
jobs.unemployed(): string
Lua
local 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

Signature
jobs.onDutyCount(job: string): number
Lua
local 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

Signature
jobs.gangs(source: number): GangMembership[]
Lua
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

Signature
jobs.activeGang(source: number): string | null
jobs.setActiveGang(source: number, gang: string | null): boolean
Lua
local 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

Signature
jobs.setGang(source: number, gang: string, grade: number): boolean
jobs.removeGang(source: number, gang: string): boolean
Lua
local 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

Signature
dispatch.alert(alert: DispatchAlert): boolean
Lua
local 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

Signature
prison.jail(source: number, minutes: number, by?: number): boolean
Lua
local 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

Signature
prison.release(source: number): boolean
Lua
local 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

Signature
prison.timeLeft(source: number): number
Lua
local 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

Signature
mdt.record(record: MdtRecord): boolean
Lua
local 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

Signature
mdt.provider(): string | null
Lua
local 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

Signature
ems.available(jobs: string[]): number
Lua
local 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

Signature
ems.distress(source: number, call: DistressCall): boolean
Lua
local 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

Signature
ems.provider(): string | null
Lua
local 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

Signature
medical.revive(source: number): boolean

Returns 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

Signature
medical.heal(source: number): boolean

Returns true when healed, false when no death script runs.

medical.heal(source);

medical.isDead

Whether the player is down.

Side: Server · Waits: no

Signature
medical.isDead(source: number): boolean

Returns 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

Signature
medical.provider(): string | null

Returns 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

Signature
stress.gain(source: number, amount: number): boolean
Lua
local 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 shootout

stress.relieve

Takes stress points away.

Side: Server · Waits: no

Signature
stress.relieve(source: number, amount: number): boolean
Lua
local 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

Signature
stress.provider(): string | null
Lua
local 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

Signature
needs.refill(source: number): boolean

No 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

Signature
definitions.job(name: string): JobDefinition | null
Lua
local 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

Signature
definitions.gang(name: string): GangDefinition | null
Lua
local 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

Signature
definitions.registerJob(name: string, definition: JobDefinition): CharacterResult
definitions.removeJob(name: string): boolean
Lua
local 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

Signature
definitions.registerGang(name: string, definition: GangDefinition): CharacterResult
definitions.removeGang(name: string): boolean
Lua
local 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

Signature
isPrimeTime(job?: string): boolean

No 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");

On this page