ai-core server exports

Typed as AiCoreServerExports in @aicore-fivem/shared (exports.ts). In TypeScript take one handle per file; in Lua call exports['ai-core'] directly.

TypeScript

import { resourceExport } from "@aicore-fivem/lib/server";
const core = resourceExport("ai-core");

Types used below: CharacterInfo, AiPlayerData, JobMembership ({ job, grade }), GangMembership ({ gang, grade }), InventoryRef (a player's server id or another inventory's id: stash name, plate), KeyPurpose (purchase, garage, job, rental, temporary), all in @aicore-fivem/shared.

Characters and players

Export	What
`GetPlayerData(src: number): AiPlayerData \| null`	Everything ai-core keeps for a loaded player: character, money, jobs, duty, gangs, metadata.
`GetCharacter(src: number): CharacterInfo \| null`	The loaded character (id, citizenid, names, birthdate, sex, nationality).
`GetSourceByCharId(charId: number): number \| null`	Server id of the player playing that character.
`GetSourceByCitizenId(citizenid: string): number \| null`	The same by citizen id.
`GetLoadedSources(): number[]`	Server ids of every player with a loaded character.
`GetFivemId(src: number): string \| null`	The player's FiveM identifier.
`SwitchCharacter(src: number): boolean`	Sends the player back to the character screen.
`SetOfflinePosition(charId: number, position: { x, y, z, heading? }): boolean`	Moves a stored (not loaded) character's spawn point; false while it is loaded.
`GetPlayersInScope(source: number): number[]`	Players in a player's OneSync scope (about 424 m).

TypeScript

const character = core.GetCharacter(source);
if (character) console.log(character.firstname, character.lastname);

Lua

local character = exports['ai-core']:GetCharacter(source)
if character then print(character.firstname, character.lastname) end

Money

Accounts are the ones in the panel's Accounts list (cash, bank by default). reason goes into the ledger.

Export	What
`GetMoney(src: number, account: string): number \| null`	A player's balance.
`AddMoney(src: number, account: string, amount: number, reason?: string): boolean`	Adds money.
`RemoveMoney(src: number, account: string, amount: number, reason?: string): boolean`	Takes money; false when the account cannot pay.
`SetMoney(src: number, account: string, amount: number, reason?: string): boolean`	Sets a balance.
`GetSharedMoney(ownerType: "job" \| "gang", ownerId: string, account: string): number \| null`	A job's or gang's shared account.
`AddSharedMoney(ownerType, ownerId, account, amount: number, reason?: string): boolean`	Adds to a shared account.
`RemoveSharedMoney(ownerType, ownerId, account, amount: number, reason?: string): boolean`	Takes from a shared account.
`TransferMoney(from: MoneyRef, to: MoneyRef, amount: number, reason?: string, fee?: number): boolean`	Moves money between two accounts in one transaction with both ledger rows; `from` also pays `fee`.
`GetAccountTypes(): Record<string, AccountTypeDefinition>`	The account list (`label`, `start`, `allowNegative`).

MoneyRef is { source, account } for a loaded player or { owner: "job" \| "gang", id, account } for a shared account.

TypeScript

if (core.RemoveMoney(source, "bank", 500, "fine")) {
  core.AddSharedMoney("job", "police", "bank", 500, "fine");
}

Lua

if exports['ai-core']:RemoveMoney(source, 'bank', 500, 'fine') then
  exports['ai-core']:AddSharedMoney('job', 'police', 'bank', 500, 'fine')
end

Jobs and gangs

A character can hold several jobs and gangs, with at most one on-duty job and one active gang.

Export	What
`GetJobs(src: number): JobMembership[] \| null`	Every job membership.
`GetCurrentJob(src: number): JobMembership \| null`	The job other scripts see as "the" job: on duty, else last on duty, else the first.
`GetDutyJob(src: number): string \| null`	The job the player is on duty for.
`SetDuty(src: number, job: string \| null): boolean`	Puts the player on duty for a job, or off duty (`null`).
`SetJob(src: number, job: string, grade: number): boolean`	Adds a job or changes its grade.
`RemoveJob(src: number, job: string): boolean`	Removes a job membership.
`GetOnDutyCount(job: string): number`	How many players are on duty in a job.
`IsPrimeTime(job?: string): boolean`	Prime time for a job (tgiann-policealert's hours while it runs, else the panel's hours).
`GetGangs(src: number): GangMembership[] \| null`	Every gang membership.
`GetActiveGang(src: number): string \| null`	The active gang.
`SetGang(src: number, gang: string, grade: number): boolean`	Adds a gang or changes its grade.
`RemoveGang(src: number, gang: string): boolean`	Removes a gang membership.
`SetActiveGang(src: number, gang: string \| null): boolean`	Picks the active gang.
`GetJobDefinitions(): Record<string, JobDefinition>`	Every job definition (a copy: for rare reads).
`GetJobDefinition(job: string): JobDefinition \| null`	One job: `label`, `type`, `defaultDuty`, `listed?`, `grades` (`label`, `salary`, `boss`).
`GetGangDefinitions(): Record<string, GangDefinition>`	Every gang definition.
`GetGangDefinition(gang: string): GangDefinition \| null`	One gang: `label`, `grades`.

TypeScript

if (core.GetDutyJob(source) === "police") {
  const officers = core.GetOnDutyCount("police");
}

Lua

if exports['ai-core']:GetDutyJob(source) == 'police' then
  local officers = exports['ai-core']:GetOnDutyCount('police')
end

Metadata and server settings

Export	What
`GetMeta(src: number, key: string): unknown`	One value of the character's metadata bag.
`SetMeta(src: number, key: string, value: unknown): boolean`	Sets a metadata value.
`GetBranding(): Branding`	The server's name, subtitle, taglines and background from the panel's General settings.
`GetUpdates(): UpdateInfo[]`	Scripts with a newer GitHub release than the running version.

Items

ai-core's inventory layer: the active inventory answers (false, 0 or empty while none runs).

Export	What
`AddItem(inv: InventoryRef, item: string, count?: number, metadata?: ItemMetadata, slot?: number): boolean`	Adds items.
`RemoveItem(inv: InventoryRef, item: string, count?: number, metadata?: ItemMetadata, slot?: number): boolean`	Removes items.
`GetItemCount(inv: InventoryRef, item: string, metadata?: ItemMetadata): number`	How many of an item.
`HasItem(inv: InventoryRef, item: string, count?: number): boolean`	Whether the inventory holds at least `count`.
`CanCarryItem(inv: InventoryRef, item: string, count?: number, metadata?: ItemMetadata): boolean`	Whether the items fit.
`GetItems(inv: InventoryRef): InventoryStack[]`	Every stack (`name`, `label`, `count`, `slot`, `metadata`).
`ClearInventory(inv: InventoryRef): void`	Empties an inventory.
`RegisterStash(name: string, label: string, slots: number, maxWeight: number, jobs?: string[]): void`	A stash; kept and registered again with every inventory that becomes active.
`OpenInventory(source: number, inv: InventoryRef): boolean`	Opens a stash or another inventory on the player's screen.
`RegisterUsableItem(name: string, handler: UsableItemHandler): void`	`handler(source, item)` runs on use; returning false keeps the item. Kept across inventory restarts.
`GetItemDefinition(name: string): ItemDefinition \| null`	One item (`name`, `label`, `weight`, `unique`, `close`, `description`, `image?`).
`GetItemDefinitions(): Record<string, ItemDefinition>`	Every item.
`UseItem(source: number, name: string, item?: unknown): unknown`	Runs the registered handler (the bridge calls it).
`IsUsableItem(name: string): boolean`	Whether a handler is registered.

TypeScript

core.RegisterUsableItem("bandage", (source, item) => {
  // heal, then let the inventory take the item
});
if (core.CanCarryItem(source, "water", 2)) core.AddItem(source, "water", 2);

Lua

exports['ai-core']:RegisterUsableItem('bandage', function(source, item)
  -- heal, then let the inventory take the item
end)
if exports['ai-core']:CanCarryItem(source, 'water', 2) then
  exports['ai-core']:AddItem(source, 'water', 2)
end

Vehicle keys

A vehicle is a server entity handle or a plate; purpose defaults to temporary.

Export	What
`GiveVehicleKeys(source: number, vehicle: number \| string, purpose?: KeyPurpose): void`	Gives keys through the active key system.
`RemoveVehicleKeys(source: number, vehicle: number \| string): void`	Takes keys away.
`HasVehicleKeys(source: number, vehicle: number \| string): boolean`	Whether the player has the keys.

Lua

exports['ai-core']:GiveVehicleKeys(source, 'AB12CDE', 'rental')

Medical

Export	What
`GetMedicalSystem(): string \| null`	The death script ai-core forwards to.
`RevivePlayer(source: number): boolean`	Gets a downed player up where they lie; false when not down or no death script runs.
`HealPlayer(source: number): boolean`	Full health for a player who is not down.
`IsPlayerDead(source: number): boolean`	Whether the player is down.

Appearance

Export	What
`GetAppearanceSystem(): string \| null`	The clothing script ai-core reads looks from.
`GetCharacterAppearance(charId: number, done: (look: CharacterAppearance \| null) => void): void`	A character's stored look (loaded or not); `done` gets `{ model, data }` or null.

Lua

exports['ai-core']:GetCharacterAppearance(charId, function(look)
  if look then TriggerClientEvent('myscript:dress', source, look) end
end)

Phone

Whatever phone script runs answers (none: null or false).

Export	What
`GetPhoneNumber(source: number): string \| null`	The player's number.
`GetSourceByPhone(number: string): number \| null`	The player with that number.
`HasPhone(source: number): boolean`	Whether the player has a phone.
`SendPhoneMail(to: number \| string, mail: PhoneMail): boolean`	A mail (`sender`, `subject`, `message`) to a player or number.
`SendPhoneMessage(from: string, to: number \| string, text: string): boolean`	A text message.
`PhoneNotify(source: number, notification: PhoneNotification): boolean`	A phone notification (`title`, `message`, `app?`).

Dispatch

Export	What
`SendDispatchAlert(alert: DispatchAlert): boolean`	Shows an alert to on-duty members of `jobs` through the active alert system; false when none runs.

DispatchAlert: title, and optional code, message, coords, jobs, source (the suspect), blip (sprite, color?, scale?), duration (seconds), icon, priority (normal or high). Texts are already translated.

TypeScript

core.SendDispatchAlert({
  code: "10-90",
  title: "Store robbery",
  jobs: ["police"],
  source,
  priority: "high",
});

Lua

exports['ai-core']:SendDispatchAlert({
  code = '10-90', title = 'Store robbery', jobs = { 'police' }, source = source, priority = 'high',
})

Prison

Export	What
`JailPlayer(source: number, minutes: number, by?: number): boolean`	Jails a player through the running prison script.
`ReleasePlayer(source: number): boolean`	Releases a player.
`GetJailTime(source: number): number`	Minutes left.

Time and weather

The qb-weathersync contract of whatever weather script runs (null or false while none runs).

Export	What
`GetWeather(): string \| null`	The current weather type.
`SetWeather(type: string): boolean`	Sets the weather (`EXTRASUNNY`, `RAIN`...).
`GetTime(): { hour, minute } \| null`	The game time.
`SetTime(hour: number, minute?: number): boolean`	Sets the game time.
`SetBlackout(on: boolean): boolean`	Blackout on or off.
`FreezeTime(on: boolean): boolean`	Freezes or unfreezes the clock.

Routing buckets

Export	What
`AcquireBucket(tag: string): number`	A free routing bucket for the calling resource (no population, strict lockdown); freed when it stops.
`ReleaseBucket(id: number): boolean`	Gives a bucket back (only the resource that took it); move its players out first.

Logs

Export	What
`Log(channel: string, message: string, options?: LogOptions): void`	Sends a log of the calling resource to every provider turned on (Discord, Fivemanage, FiveM Stats, console). `options`: `level`, `source`, `target`, `metadata`.
`LogChannels(channels: Record<string, LogChannel>): void`	Describes the calling resource's channels (`dataset`, `active`); call once at start.

Lua

exports['ai-core']:Log('sales', 'Sold a car', { source = source, metadata = { price = 25000 } })

Connection

Export	What
`AddConnectionCheck(id: string, check: (source, identifiers) => string \| null \| undefined): void`	A check every connecting player passes: return a refusal text, or null to let them in.
`RegisterReplacement(remove: string \| string[], keep?: string): void`	Declares that `keep` (default: the caller) makes `remove` unneeded: a console warning, joins refused while both run.
`GetConflicts(): { keep, remove, running, from }[]`	Scripts installed next to the one that replaces them.

Admin panel and commands

Export	What
`RegisterAdminPanel(resource: string): void`	A resource with a panel announces itself (the lib's `AdminPanel` does it).
`AdminPanelChanged(delta: AdminDelta): void`	A panel resource changed a record; ai-core forwards it to admins with the panel open.
`RegisterCommands(resource: string, commands: CommandInfo[]): void`	The lib's `addCommand` lists a resource's commands in the Commands tab.
`GetLookupValues(source: LookupSource): string[]`	Values of a lookup list (`item`, `job`, `gang`, `account`...) for panel validation.
`RegisterExternalPanel(panel: { id?, label, icon?, description?, command?, url? }): void`	Lists another script's own settings screen on the dashboard (opened by `command` or embedded `url`).

Lua

exports['ai-core']:RegisterExternalPanel({
  label = 'My script', icon = 'gear', description = 'Its own settings', command = 'myscriptconfig',
})

Characters and playersCopy Anchor Link

MoneyCopy Anchor Link

Jobs and gangsCopy Anchor Link

Metadata and server settingsCopy Anchor Link

ItemsCopy Anchor Link

Vehicle keysCopy Anchor Link

MedicalCopy Anchor Link

AppearanceCopy Anchor Link

PhoneCopy Anchor Link

DispatchCopy Anchor Link

PrisonCopy Anchor Link

Time and weatherCopy Anchor Link

Routing bucketsCopy Anchor Link

LogsCopy Anchor Link

ConnectionCopy Anchor Link

Admin panel and commandsCopy Anchor Link

On this page

Characters and players

Money

Jobs and gangs

Metadata and server settings

Items

Vehicle keys

Medical

Appearance

Phone

Dispatch

Prison

Time and weather

Routing buckets

Logs

Connection

Admin panel and commands