AI Core

Integrating your own script

How your own resource works with AI Core - loading the lib, the layers it calls instead of other scripts, what it must never touch, and the checklist before release.

Your script does not have to be an ai-* script to work with AI Core. What you have to do depends on what you are writing:

What you haveWhat to do
A script written for ESX, QBCore, Qbox or vRPNothing. AI Core provides es_extended, qb-core, qbx_core and vrp and answers their API, so the script runs unchanged. See Compatibility.
Your own new resource (Lua, TypeScript or plain JavaScript)Load the lib and call AI Core through it. That is this page.
A script that provides something other scripts need (an inventory, a phone, a key system, a garage, a fuel script...)The same as above, plus an adapter in that layer so the rest of the server reaches it. See Recommended scripts.

The goal is one sentence: everything your script shares with another script goes through the lib or ai-core, never through that script's own exports. The owner can then replace the inventory, the key system or the phone and your script keeps working.

Load the lib

Lua

fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

dependency 'ai-lib'
shared_script '@ai-lib/init.lua'

client_script 'client.lua'
server_script 'server.lua'

aiLib.<name> is then available in every file of your resource. The full setup, which calls wait, and how Lua tables and vectors cross into TypeScript: Lib for Lua.

TypeScript

server.ts
import { inventory, onClientCallback } from "@aifivem/lib/server";

@aifivem/lib comes from npm, so a resource outside the AI Core workspace installs it with bun install @aifivem/lib @aifivem/shared. A plain JavaScript resource without a build step loads @ai-lib/dist/server.js and uses the same global aiLib.

Start order

ai-core and ai-lib start before your resource:

server.cfg
ensure ai-core
ensure ai-lib
ensure my-resource

Call AI Core, not the other script

Every shared job has one door. The lib call and the ai-core export do the same thing; use whichever fits your language.

What you needLuaTypeScriptReference
Give, take, count itemsaiLib.inventory.addIteminventory.addItemItems, ai-core items
A usable itemaiLib.inventory.registerUsableIteminventory.registerUsableItemregisterUsableItem
A stash or a shopaiLib.inventory.registerStashinventory.registerStashItems
Vehicle keysaiLib.vehicleKeys.give / .hasvehicleKeys.give / .hasVehicles
Spawn a vehicle (plate, fuel, look, keys, seats in one call)aiLib.spawnVehiclespawnVehiclespawnVehicle
Park or impound a vehicleaiLib.garages.storegarages.storegarages.store
Money of a playerexports['ai-core']:AddMoney(src, 'cash', 50, 'reason')core.AddMoney(...)Money
Money between two accounts, in one transactionaiLib.money.transfermoney.transfermoney.transfer
Jobs, gangs, dutyexports['ai-core']:SetJob(src, 'police', 2)core.SetJob(...)Jobs and gangs
Who is online, their name, their jobaiLib.online.nameonline.namePlayers
A police alertaiLib.dispatch.alertdispatch.alertdispatch.alert
JailaiLib.prison.jailprison.jailprison.jail
An MDT recordaiLib.mdt.recordmdt.recordmdt.record
Revive, heal, "is dead"aiLib.medical.revivemedical.revivemedical.revive
The phone (number, mail, message, notification)aiLib.phone.numberphone.numberPhone
A look, an outfitaiLib.appearance.applyappearance.applyappearance.apply
Weather and timeaiLib.world.setWeatherworld.setWeatherWorld
Lock a dooraiLib.doors.setLockeddoors.setLockeddoors.setLocked
Notifications, progress bars, menus, input dialogsaiLib.notify, aiLib.progress, aiLib.menu.shownotify, progress, menuShared UI
A radial menu entryaiLib.radial.addradial.addradial.add
A command (listed in the admin panel, ACE checked)aiLib.addCommandaddCommandaddCommand
A log line in the owner's channelsaiLib.aiLogaiLogaiLog

Which script answers each of these on this server, and the list of adapters: Layers and the bridge. Every function with its signature, parameters and return: API reference.

Never query AI Core's tables. ai_core_characters, ai_core_accounts, ai_core_character_jobs, ai_vehicles_owned and the other ai_* tables are internal: characters, money, jobs and vehicles live in memory and are written on ai-core's own schedule, so a direct SELECT can be stale, and a column may change in any release. Ask ai-core instead - it answers for a loaded player and for a stored character alike (characters, money, jobs). The same goes for another ai-* script's data files (data/*.json of its admin panel): they are the panel's content, not an interface.

A citizenid is not a character id. Two ids exist: the character id (charId, a number) and the citizenid (text) other frameworks' scripts use. Never convert one into the other yourself - ask ai-core (GetCharIdByCitizenId, GetSourceByCitizenId, GetSourceByCharId): Characters.

Detecting AI Core

Lua
local onAiCore = GetResourceState('ai-core') == 'started'

In TypeScript the lib does it for you: isResourceStarted("ai-core"), or optionalExport("ai-core"), which is null while the resource is stopped (exports).

A script that supports several frameworks finds qbx_core, qb-core and es_extended started as well, because ai-core provides them. That path works, but it only reaches what those APIs can say. Check ai-core before the framework names and take the AI Core path when it is there; keep the framework code as the fallback for other servers.

The rules your script is judged by

These are the same rules every ai-* script follows (Overview), and what a review looks at:

The server decides

Every client request goes through the lib's gate: a rate limit, one call at a time (lock), an ace check, and in TypeScript also guards (admin, has a character, near a point) and an argument parser. Money, items and permissions never change on the client, and a client value is never used as it arrives - in Lua you check every argument yourself.

server.lua
aiLib.onClientCallback('myshop:buy', function(source, item)
    if type(item) ~= 'string' or #item > 32 then return aiLib.fail('CORE_ERR_ARGS') end
    if not aiLib.inventory.canCarryItem(source, item, 1) then return aiLib.fail('INVENTORY_FULL') end
    -- take the money and give the item here, on the server
    return { ok = true }
end, { rate = { count = 5, windowMs = 10000 }, lock = true })

Client input, the strict readers TypeScript has (readText, oneArg) and refusals (fail, ActionResult).

Snapshot, then deltas

Live data goes to a client once in full, then only what changed, and only to the players who need it. No polling, no "something changed, fetch it again" signal, no per-tick traffic. State bags for per-entity and per-player values, AreaStream for world objects, state bags for the rest.

Settings in the admin panel

A server owner should not edit Lua. Your script's own settings screen gets a card on ai-core's panel dashboard with one call, so the owner finds every script's settings in one place:

server.lua
exports['ai-core']:RegisterExternalPanel({
    label = 'My script',
    icon = 'gear',
    description = 'Shops, prices and rewards',
    command = 'myscriptconfig',
})

A script you cannot change is listed with ai_admin_label / ai_admin_command lines in its fxmanifest.lua instead: RegisterExternalPanel. Commands registered with aiLib.addCommand and keybinds made with aiLib.Keybind show up in the panel's command and key lists on their own.

Your own data is yours

Tables of your own resource are your business: name them after your resource (myscript_*) and create them at start. Lua resources use ai-mysql, which stands in for oxmysql, mysql-async and ghmattimysql (MySQL.query.await, MySQL.single.await), so the queries you already have keep working. A resource that reads the connection string itself also needs one line in env.cfg:

env.cfg
add_convar_permission my-resource read mysql_connection_string

See The database.

Before you release

  • ai-lib (or @aifivem/lib) loaded, dependency 'ai-lib' in the manifest.
  • No other script's exports for items, keys, money, jobs, the phone, alerts, clothing, fuel, doors, garages or the prison.
  • No query against an ai_* table of AI Core, and no reading of another script's data/*.json.
  • Every client request rate limited and checked on the server.
  • Live data as snapshot and deltas.
  • Settings in the panel, texts in your own locale files (locale).
  • Tested with the ai-* scripts the feature touches, and with the server's own choice replaced (another inventory, another key system) where a layer is involved.

On this page