Shared types

The API pages write types by name (Vec3, ActionResult, InventoryRef...). This page explains each one once: its fields, what each field means, and an example value.

Where a type comes from:

PositionsCopy Anchor Link

Vec3Copy Anchor Link

A point in the world, in metres. GTA's x is east, y is north, z is up.

const counter: Vec3 = { x: 25.7, y: -1347.3, z: 29.5 };

local counter = vector3(25.7, -1347.3, 29.5) -- or { x = 25.7, y = -1347.3, z = 29.5 }

Vec4Copy Anchor Link

A point with a heading: where a ped stands or a vehicle spawns and which way it faces. Panel vec4 fields and the panel's point tool store this shape.

const spawn: Vec4 = { x: -42.1, y: -1098.4, z: 26.4, heading: 158.0 };

ZoneShapeCopy Anchor Link

An area in the world. Used by client Zones and by server area checks (zone geometry). It is one of three shapes, picked by type.

Sphere (a ball around a point):

Cylinder (a circle on the ground, reaching up and down):

Poly (a ground polygon between two heights):

const yard: ZoneShape = { type: "sphere", center: { x: 440.1, y: -981.2, z: 30.7 }, radius: 25 };
const lot: ZoneShape = {
  type: "poly",
  points: [ { x: 210, y: -810 }, { x: 240, y: -800 }, { x: 230, y: -770 }, { x: 200, y: -780 } ],
  minZ: 28,
  maxZ: 36,
};

ResultsCopy Anchor Link

ActionResultCopy Anchor Link

What every server action answers a client: either success, or a lang key the client shows as the reason. Extra fields can ride on the success branch (ActionResult<{ id: number }>). The new state itself never travels in the reply: it arrives as a delta.

Success:

Refusal:

const done: ActionResult = { ok: true };
const created: ActionResult<{ id: number }> = { ok: true, id: 42 };
const refused: ActionResult = { ok: false, error: "NOT_ENOUGH_MONEY" };

return { ok = true }
return aiLib.fail('NOT_ENOUGH_MONEY') -- { ok = false, error = 'NOT_ENOUGH_MONEY' }

Build refusals with fail; read replies with isActionOk and replyError.

Players and charactersCopy Anchor Link

AiPlayerDataCopy Anchor Link

The player data ai-core pushes to a player's own client: one full snapshot when the character loads, then only the key that changed. Also returned by the GetPlayerData export on both sides. Other pages may call it "player data".

const data: AiPlayerData = {
  character: { id: 12, citizenid: "AB12CD34", slot: 1, firstname: "Jane", lastname: "Doe", birthdate: "1994-05-12", sex: "female", nationality: "American" },
  money: { cash: 500, bank: 5000, black_money: 0, crypto: 0 },
  jobs: [{ job: "police", grade: 2 }],
  duty: "police",
  job: { job: "police", grade: 2 },
  gangs: [],
  activeGang: null,
  metadata: { hunger: 80, thirst: 75 },
};

CharacterInfoCopy Anchor Link

A character as other resources see it (the "character" of GetCharacter, playerLoaded and AiPlayerData.character).

const character: CharacterInfo = {
  id: 12, citizenid: "AB12CD34", slot: 1,
  firstname: "Jane", lastname: "Doe", birthdate: "1994-05-12",
  sex: "female", nationality: "American",
};

JobMembershipCopy Anchor Link

One job a character has.

const membership: JobMembership = { job: "police", grade: 2 };

GangMembershipCopy Anchor Link

One gang a character is in.

const membership: GangMembership = { gang: "ballas", grade: 0 };

SpawnPointCopy Anchor Link

Where and how a loaded character appears in the world (the payload ai-core sends to put the character in the world).

const spawn: SpawnPoint = { x: -1037.6, y: -2737.9, z: 20.2, heading: 330, model: "mp_f_freemode_01", armour: 0, health: 200 };

BrandingCopy Anchor Link

The server's name and look on full-screen menus (panel General settings; export GetBranding).

const branding: Branding = { name: "Los Santos RP", subtitle: "Serious roleplay", tagline: "Welcome", taglineSub: "Pick a character", background: "skyline" };

PlayerCacheCopy Anchor Link

The local player's often read values, kept current by ai-core's one watcher (lib cache on the client). false means "none".

const snapshot: PlayerCache = { ped: 258, playerId: 0, serverId: 7, vehicle: 81922, seat: -1, weapon: false };

UnloadReasonCopy Anchor Link

Why a character was let go.

MoneyCopy Anchor Link

Account namesCopy Anchor Link

Money lives in named accounts. The panel's Accounts list sets which exist; ai-core ships with these:

A server owner can add, rename or remove accounts in the panel, so read the list with the GetAccountTypes export instead of assuming it. When the list is empty, ai-core keeps a single cash account.

core.AddMoney(source, "bank", 250, "Paycheck");

AccountTypeDefinitionCopy Anchor Link

One account type from the panel's Accounts list (GetAccountTypes returns Record<string, AccountTypeDefinition>, keyed by account name).

const bank: AccountTypeDefinition = { label: "Bank", start: 5000, allowNegative: false };

MoneyRefCopy Anchor Link

One side of a money transfer (TransferMoney): a loaded player's account, or a job's or gang's shared account.

const player: MoneyRef = { source: 7, account: "bank" };
const society: MoneyRef = { owner: "job", id: "mechanic", account: "bank" };

Jobs and gangsCopy Anchor Link

GradeDefinitionCopy Anchor Link

One grade of a job or gang (panel content).

const grade: GradeDefinition = { label: "Sergeant", salary: 400, boss: false };

JobDefinitionCopy Anchor Link

One job from the panel's Jobs list (GetJobDefinition). Grade n of a JobMembership is grades[n].

const police: JobDefinition = {
  label: "Police", type: "leo", defaultDuty: false, listed: false,
  grades: [ { label: "Cadet", salary: 200, boss: false }, { label: "Chief", salary: 900, boss: true } ],
};

GangDefinitionCopy Anchor Link

One gang from the panel's Gangs list (GetGangDefinition).

const ballas: GangDefinition = { label: "Ballas", grades: [ { label: "Recruit", salary: 0, boss: false } ] };

AccessRuleCopy Anchor Link

Who may use a place (a shop, a stash, a garage): one of jobs or one of gangs. Both lists empty means everyone. From @aicore-fivem/lib/shared; read it with readAccess.

const armoury: AccessRule = { jobs: ["police"], gangs: [], grades: { police: 2 }, onDuty: true };

InventoryCopy Anchor Link

InventoryRefCopy Anchor Link

Which inventory a call works on.

inventory.addItem(source, "water", 2);          // a player
inventory.addItem("police_evidence", "phone", 1); // a stash

ItemMetadataCopy Anchor Link

Free data stored on one item stack (Record<string, unknown>): a serial number, durability, a note. Each inventory shows some keys itself (label, description, image in most of them).

const metadata: ItemMetadata = { serial: "AB-1029", durability: 100 };

InventoryStackCopy Anchor Link

One stack in an inventory (GetItems returns a list of these).

const stack: InventoryStack = { name: "water", label: "Water", count: 3, slot: 4, metadata: {} };

UsedItemCopy Anchor Link

The stack a usable item handler gets when a player uses an item.

const used: UsedItem = { name: "lockpick", slot: 2, count: 1, metadata: { durability: 80 } };

UsableItemHandlerCopy Anchor Link

(source: number, item: UsedItem) => unknown: runs when a player uses the item. Returning false keeps the item in inventories that take a used item themselves (ai-inventory takes the item's consume amount); other inventories follow their own item settings.

const onUse: UsableItemHandler = (source, item) => {
  if (item.metadata.durability === 0) return false; // keep it
  return true;
};

ItemDefinitionCopy Anchor Link

One item as the active inventory defines it (GetItemDefinition). Other pages may call it "item" or "item definition".

const water: ItemDefinition = { name: "water", label: "Water", weight: 500, unique: false, close: true, description: "Fresh water" };

StashDefinitionCopy Anchor Link

A stash as ai-core keeps it (the arguments of RegisterStash).

const evidence: StashDefinition = { name: "police_evidence", label: "Evidence", slots: 50, maxWeight: 100000, jobs: ["police"] };

ShopProductCopy Anchor Link

One product of a script shop.

const product: ShopProduct = { name: "bandage", price: 50 };

ShopDefinitionCopy Anchor Link

A shop a script registers. The server opens it for a player; it has no place of its own.

const shop: ShopDefinition = { name: "police_armoury", label: "Armoury", items: [{ name: "bandage", price: 50 }] };

HeldWeaponCopy Anchor Link

The weapon item the local player holds, as the inventory knows it.

const held: HeldWeapon = { name: "WEAPON_PISTOL", label: "Pistol" };

VehiclesCopy Anchor Link

VehiclePropsCopy Anchor Link

A vehicle's look and tuning as plain data: colours, mods, extras, livery, wheels, neon, tint, plate and condition. From @aicore-fivem/lib/shared. Stored JSON carries v: 1. Check received data with toVehicleProps.

const props: VehicleProps = {
  v: 1, model: 1032823388, plate: "AI 123", plateIndex: 0,
  colors: [12, 12], extraColors: [0, 156], customPrimary: null, customSecondary: null,
  wheelType: 0, windowTint: -1, livery: -1, mods: { 11: 2, 18: 1 }, xenonColor: 255,
  neon: [false, false, false, false], neonColor: [255, 0, 255], tyreSmoke: [255, 255, 255],
  extras: { 1: true }, dirt: 0, engineHealth: 1000, bodyHealth: 1000,
};

VehicleSetupCopy Anchor Link

What a freshly spawned vehicle gets on top of the model's defaults (the setup of lib spawnVehicle, a shop's chosen colour). From @aicore-fivem/lib/shared. Every field is optional. Check received data with toVehicleSetup.

const setup: VehicleSetup = { colors: [27, 27], windowTint: 1, engineOn: true };

KeyPurposeCopy Anchor Link

Why a player gets a vehicle's key. Key scripts treat each one differently. Anything unknown counts as "temporary".

vehicleKeys.give(source, vehicle, "rental");

VehicleOwnerCopy Anchor Link

Who owns an ai-vehicles vehicle.

const owner: VehicleOwner = { type: "character", id: "12" };

OwnedVehicleCopy Anchor Link

An owned vehicle as ai-vehicles keeps it (GetVehicle).

const car: OwnedVehicle = {
  id: 7, plate: "AI 123", owner: { type: "character", id: "12" }, model: "sultan",
  props: null, setup: null, state: "garage", garage: "legion", fuel: 100, engine: 1000, body: 1000,
};

WorldCopy Anchor Link

WeatherCopy Anchor Link

A weather type name of the qb-weathersync contract, exact upper case: "EXTRASUNNY", "CLEAR", "NEUTRAL", "SMOG", "FOGGY", "OVERCAST", "CLOUDS", "CLEARING", "RAIN", "THUNDER", "SNOW", "BLIZZARD", "SNOWLIGHT", "XMAS", "HALLOWEEN". The list is the WEATHERS constant; isWeather(value) checks a value.

import { isWeather, type Weather } from "@aicore-fivem/shared";

const next: Weather = "RAIN";
if (isWeather(input)) world.setWeather(input);

BlipStyleCopy Anchor Link

A blip's look as the panel's blip widget stores it. From @aicore-fivem/lib/shared; read it with readBlipStyle.

const style: BlipStyle = { sprite: 52, color: 2, scale: 0.8 };

PlacePedCopy Anchor Link

An NPC standing at a place (a shopkeeper, a clerk). From @aicore-fivem/lib/shared; read it with readPlacePed.

const clerk: PlacePed = { model: "mp_m_shopkeep_01", scenario: "WORLD_HUMAN_STAND_IMPATIENT", coords: { x: 24.5, y: -1346.6, z: 29.5, heading: 270 } };

Player UICopy Anchor Link

NotificationKindCopy Anchor Link

The colour and icon of a notification card: "success", "error", "info" or "warning". Other pages may call it "notify kind".

notify(source, "Vehicle stored", "success"); // server lib notify(source, text, kind?, duration?)

NotificationCopy Anchor Link

A notification card. ai-lib draws it; texts are already translated by the sender.

const card: Notification = { text: "Vehicle stored", kind: "success", duration: 3000 };

ProgressOptionsCopy Anchor Link

What the client progress bar (lib progress on the client) shows and how the player may move while it runs. From @aicore-fivem/lib/client.

const repair: ProgressOptions = {
  label: "Repairing",
  duration: 8000,
  anim: { dict: "mini@repair", clip: "fixing_a_player" },
  canCancel: true,
  disable: { move: true, combat: true },
};

ServerProgressCopy Anchor Link

The bar a server flow runs on a player's client (lib progressFor). The same fields as ProgressOptions without whileDead. ProgressForOptions (from @aicore-fivem/lib/server) adds one field:

const bar: ProgressForOptions = { label: "Picking the lock", duration: 6000, scenario: "PROP_HUMAN_PARKING_METER", minRatio: 0.9 };

MenuItemCopy Anchor Link

One row of a menu.

const row: MenuItem = { id: "water", label: "Water ($5)", icon: "bottle-water" };

MenuRequestCopy Anchor Link

A menu to show (lib menu, Lua aiLib.menu.show).

const shop: MenuRequest = {
  title: "24/7",
  items: [ { id: "water", label: "Water ($5)" }, { id: "bread", label: "Bread ($3)" } ],
};

InputFieldCopy Anchor Link

One field of an input dialog. It is a number field or a text field, picked by type.

Number field:

Text field:

InputRequestCopy Anchor Link

An input dialog to show (lib input, Lua aiLib.input).

const fine: InputRequest = {
  title: "Write a fine",
  confirm: "Send",
  fields: [
    { name: "amount", label: "Amount", type: "number", min: 1, max: 10000 },
    { name: "reason", label: "Reason", type: "text", maxLength: 80 },
  ],
};

PromptAnchorCopy Anchor Link

Where a world prompt floats: a fixed point, or spots on entities. Entity offsets are in the entity's own space, so the prompt moves and turns with it (a swinging door). Of several entity spots, the one nearest the player is shown each frame.

Point:

Entity spots:

const atPoint: PromptAnchor = { x: 25.7, y: -1347.3, z: 30.2 };
const onDoor: PromptAnchor = { anchors: [{ entity: door, offset: { x: 0.5, y: 0, z: 0 } }] };

ItemPickerRequestCopy Anchor Link

ai-core's item picker for admin tools: every item of the active inventory with its picture, a search and a count.

const request: ItemPickerRequest = { title: "Give items", target: 7 };

PickedItemCopy Anchor Link

One row the item picker answers.

SkillDifficultyCopy Anchor Link

How hard a skill check stage is: "easy", "medium", "hard", or ox_lib's own shape { areaSize: number; speedMultiplier: number }. The named stages: easy = 50 degree green arc at 0.6 turns per second, medium = 40 at 0.85, hard = 25 at 1.

const stages: SkillDifficulty[] = ["easy", "medium", { areaSize: 30, speedMultiplier: 1.2 }];

LockpickResultCopy Anchor Link

What the lockpick answers: "opened" (the lock opened), "broken" (the player broke every pick) or "cancelled" (the player closed it).

RadialItemCopy Anchor Link

One item of the radial wheel (lib radial). Its functions run in the resource that added it; ai-core drops the item when that resource stops.

const item: RadialItem = {
  id: "engine", label: "Engine", icon: "car", parent: "vehicle",
  canShow: () => cache.seat === -1,
  onPressed: () => SetVehicleEngineOn(cache.vehicle as number, !GetIsVehicleEngineRunning(cache.vehicle as number), false, true),
};

KeyHintRequestCopy Anchor Link

A key help line a script shows for a while (admin noclip keys). Give keybind or key.

const hint: KeyHintRequest = { label: "Speed up", key: "SHIFT", icon: "gauge-high" };

KeyHintWhenCopy Anchor Link

When a keybind's hint shows in HUDs: "foot" (on foot), "vehicle" (in a vehicle) or "always". The server owner can change it in the panel; a keybind without one never shows a hint.

KeyHintViewCopy Anchor Link

One row of the key hints a HUD shows (client export GetKeyHints, event ai-core:client:keyHints): the key as the player has it bound, and what it does.

const row: KeyHintView = { id: "noclip_speed", key: "SHIFT", label: "Speed up", icon: "gauge-high" };

Logs, alerts, phoneCopy Anchor Link

LogOptionsCopy Anchor Link

Extra details of a log line (lib aiLog, export Log).

aiLog("payments", "Paid a bill", { source, metadata: { amount: 250 } });

LogLevelCopy Anchor Link

Severity of a log line: "debug", "info", "warn" or "error".

LogChannelCopy Anchor Link

How a resource describes one of its log channels (lib aiLogChannels, export LogChannels, called once at start). Webhook urls are never here: the server owner sets them in ai-core's panel.

aiLogChannels({ payments: { dataset: "my-shop" }, debug: { active: false } });

DispatchAlertCopy Anchor Link

A police (or other job) alert. The active alert script shows it to the on-duty members of jobs. Texts are already translated.

const alert: DispatchAlert = { code: "10-71", title: "Shots fired", source, jobs: ["police"], priority: "high" };

PhoneMailCopy Anchor Link

A mail a script sends to a player's phone.

const mail: PhoneMail = { sender: "Los Santos Customs", subject: "Your car is ready", message: "Pick it up at the garage." };

PhoneNotificationCopy Anchor Link

A notification on a player's phone.

const note: PhoneNotification = { title: "Bank", message: "You received $250", app: "bank" };

Billing, MDT, EMS, garagesCopy Anchor Link

BillRequestCopy Anchor Link

A bill a script sends (lib billing.send): from a job (fines, service fees) or from a player, to a player. Texts are already translated.

const bill: BillRequest = { to: 7, amount: 250, label: "Speeding", from: source, job: "police" };

UnpaidBillCopy Anchor Link

One open bill of a player.

MdtRecordCopy Anchor Link

A record a script writes into the police MDT (lib mdt.record). Texts are already translated.

const record: MdtRecord = { kind: "jail", target: 7, by: source, title: "Armed robbery", minutes: 20 };

MdtRecordKindCopy Anchor Link

What an MDT record is about: "fine", "warrant", "arrest" or "jail".

DistressCallCopy Anchor Link

A downed player's call to the medics (lib ems.distress).

const call: DistressCall = { jobs: ["ambulance"], message: "Unconscious" };

GaragedVehicleCopy Anchor Link

One of a player's vehicles kept by a garage script.

LooksCopy Anchor Link

CharacterAppearanceCopy Anchor Link

A look as ai-core's appearance layer hands it out: the ped model and the clothing script's own data. Treat data as opaque: give the whole object back to ApplyAppearance unchanged.

ClothingMenuCopy Anchor Link

A clothing script menu other scripts open: "clothing" (clothing shop), "barber" or "outfits" (the player's saved outfits).

JobOutfitCopy Anchor Link

A job outfit (uniform) for the freemode model the player wears. Only the listed pieces change.

OutfitPieceCopy Anchor Link

One piece of a job outfit.

const uniform: JobOutfit = {
  components: [ { id: 11, collection: "", index: 55, texture: 0 }, { id: 4, collection: "", index: 35, texture: 0 } ],
  props: [ { id: 0, collection: "", index: 46, texture: 0 } ],
};

CommandsCopy Anchor Link

CommandInfoCopy Anchor Link

A command of lib addCommand, as the resource announces it to ai-core (the panel's Commands tab lists it).

const info: CommandInfo = { names: ["jail", "prison"], help: "Jails a player", params: [{ name: "id", type: "playerId" }], aces: ["ai.admin"] };

CommandParamCopy Anchor Link

One argument of a lib addCommand command, parsed and checked before the handler runs.

const params: CommandParam[] = [
  { name: "id", type: "playerId", help: "Player id" },
  { name: "reason", type: "longString", help: "Reason", optional: true },
];

Admin panelCopy Anchor Link

PanelSchemaCopy Anchor Link

A script's admin panel: which data files it has and how the panel lays them out. A resource hands it to the lib's AdminPanel (see Admin panel). Every text field is a lang key of the resource's locales/*.json.

const schema: PanelSchema = {
  title: "ADMIN_TITLE",
  icon: "store",
  files: { shops: { kind: "records", sync: "all", labelPath: "label", sections: { label: { type: "text", min: 1, max: 48 }, coords: { type: "vec3" } } } },
  tabs: [{ id: "shops", file: "shops", icon: "store", label: "ADMIN_TAB_SHOPS", desc: "ADMIN_TAB_SHOPS_DESC", cards: [] }],
};

FileSpecCopy Anchor Link

One data file of a panel.

TabSpecCopy Anchor Link

One tab of the panel, showing one file.

CardSpecCopy Anchor Link

One card of fields inside a tab.

const card: CardSpec = {
  icon: "location-dot",
  title: "ADMIN_CARD_PLACE",
  fields: [{ widget: "point", path: "coords", label: "ADMIN_F_COORDS", hint: "ADMIN_H_COORDS" }],
};

LookupSourceCopy Anchor Link

A list of values a panel field picks from. A lookup on a text or names field makes the server refuse anything else and the panel offer the list.

AdminDeltaCopy Anchor Link

A changed record of a panel file, forwarded to the admins who have the panel open (export AdminPanelChanged).

const delta: AdminDelta = { resource: "my-shop", file: "shops", key: "legion", value: { label: "Legion" } };

UpdateInfoCopy Anchor Link

A script whose GitHub release is newer than the running version (ai-core's update check, export GetUpdates).

const update: UpdateInfo = { resource: "ai-core", label: "ai-core", current: "1.4.0", latest: "1.5.0", url: "https://github.com/..." };

vRP bridgeCopy Anchor Link

VrpConfigCopy Anchor Link

The panel's vRP permission mapping (data/vrp.json), as ai-core's vRP bridge reads it (server export GetVrpConfig; the local event ai-core:vrp:config carries the same shape after a change).

VrpPermissionRule: grants permission to whoever matches any filled target.

VrpGroupAlias: a vRP group name that means a job or gang grade, or admin (vRPex style ranks such as "Coronel").

const config: VrpConfig = {
  defaults: { jobPrefix: true, jobOnDuty: true, adminPrefix: true, playerPrefix: true },
  permissions: [{ permission: "police.armory", job: "police", gang: "", group: "", grade: 2, onDuty: true, admin: false, everyone: false }],
  groups: { Coronel: { job: "police", gang: "", grade: 4, admin: false } },
  items: { "edible|tacos": "tacos" },
};