ai-vehicles for developers

ai-vehicles has server exports only. They are all synchronous (no Promise, no waiting in Lua), except SpawnVehicle, which answers through a callback. Types are in @aicore-fivem/shared (vehicles.ts).

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

local vehicles = exports['ai-vehicles']

TypesCopy Anchor Link

VehicleOwnerCopy Anchor Link

Who owns a vehicle.

OwnedVehicleCopy Anchor Link

What GetVehicle and GetVehicles return.

Server exportsCopy Anchor Link

CreateVehicleCopy Anchor Link

Registers a new owned vehicle and parks it. Use it when a player gets a vehicle (a purchase, a reward, an admin gift). It does not spawn the car: take it out with SpawnVehicle or let the player pick it up at a garage.

Side: Server · Waits: no

CreateVehicle(owner: VehicleOwner, model: string, garage: string | null, props?: VehicleProps): { id: number; plate: string } | null

local created = exports['ai-vehicles']:CreateVehicle(owner, model, garage, props) -- { id = number, plate = string } or nil

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

{ id, plate } of the new vehicle. null when owner is not a valid owner or model is not text.

ExampleCopy Anchor Link

import { resourceExport } from "@aicore-fivem/lib/server";

const core = resourceExport("ai-core");
const vehicles = resourceExport("ai-vehicles");

// Gives the player a Sultan, parked at the Motel Parking garage.
export function giveSultan(source: number): string | null {
  const character = core.GetCharacter(source);
  if (!character) return null;
  const created = vehicles.CreateVehicle(
    { type: "character", id: String(character.id) },
    "sultan",
    "pillbox",
  );
  return created?.plate ?? null;
}

GetVehicleCopy Anchor Link

Finds one owned vehicle by its id or plate.

Side: Server · Waits: no

GetVehicle(ref: number | string): OwnedVehicle | null

local vehicle = exports['ai-vehicles']:GetVehicle(ref) -- table or nil

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

The OwnedVehicle, or null when no vehicle in memory has that id or plate (also when it belongs to an offline character).

ExampleCopy Anchor Link

const vehicle = vehicles.GetVehicle("AI00001A");
if (vehicle) console.log(vehicle.model, vehicle.state, vehicle.fuel);

GetVehiclesCopy Anchor Link

Every vehicle of one owner.

Side: Server · Waits: no

GetVehicles(owner: VehicleOwner): OwnedVehicle[]

local list = exports['ai-vehicles']:GetVehicles(owner) -- array

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

An array of OwnedVehicle. Empty for an invalid owner, an owner without vehicles, or an offline character.

ExampleCopy Anchor Link

const fleet = vehicles.GetVehicles({ type: "job", id: "police" });
const parked = fleet.filter((v) => v.state === "garage").length;
console.log(`police: ${parked} of ${fleet.length} cars parked`);

IsOwnedPlateCopy Anchor Link

Whether a plate belongs to an owned vehicle in memory.

Side: Server · Waits: no

IsOwnedPlate(plate: string): boolean

local owned = exports['ai-vehicles']:IsOwnedPlate(plate)

ReturnsCopy Anchor Link

true when an owned vehicle has this plate. false for an unknown plate, a non-text value, or a vehicle of an offline character.

GetVehicleIdByEntityCopy Anchor Link

The ai-vehicles id of a spawned owned vehicle.

Side: Server · Waits: no

GetVehicleIdByEntity(entity: number): number | null

local id = exports['ai-vehicles']:GetVehicleIdByEntity(entity)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

The vehicle id, or null when the entity is not an owned vehicle spawned by ai-vehicles.

GetEntityCopy Anchor Link

The entity of a spawned owned vehicle.

Side: Server · Waits: no

GetEntity(id: number): number | null

local entity = exports['ai-vehicles']:GetEntity(id)

ReturnsCopy Anchor Link

The server entity handle, or null when the vehicle is not out or its entity no longer exists.

GetPlateOwnersCopy Anchor Link

Every owned vehicle in memory as [plate, ownerType, ownerId]. A script that must check many plates (a key system) reads this once at its start, then follows the ai-vehicles:owners event, instead of calling an export for every check.

Side: Server · Waits: no

GetPlateOwners(): Array<[plate: string, type: VehicleOwnerType, id: string]>

local owners = exports['ai-vehicles']:GetPlateOwners() -- { { plate, type, id }, ... }

ReturnsCopy Anchor Link

An array of triples. Empty when no vehicle is in memory.

SaveVehicleCopy Anchor Link

Saves the condition and look of a vehicle: fuel, damage, state, garage, and props (colors, extras, dirt). The stored tuning (mods, neon) never changes here, so a look read from a player's client cannot save a mod menu's work. Use SaveTuning for tuning.

Side: Server · Waits: no

SaveVehicle(id: number, change: { props?: VehicleProps; fuel?: number; engine?: number; body?: number; state?: VehicleState; garage?: string | null }): void

exports['ai-vehicles']:SaveVehicle(id, change)

ParametersCopy Anchor Link

changeCopy Anchor Link

ReturnsCopy Anchor Link

Nothing. An unknown id does nothing.

ExampleCopy Anchor Link

// A repair job finished: full engine and body.
vehicles.SaveVehicle(vehicleId, { engine: 1000, body: 1000 });

SaveTuningCopy Anchor Link

Saves full props, tuning included (mods, neon). Meant for tuning shops only: AI Core's own tuning shop, ai-mechanic, is the only ai-* script that calls it.

Side: Server · Waits: no

SaveTuning(id: number, props: VehicleProps): void

exports['ai-vehicles']:SaveTuning(id, props)

ReturnsCopy Anchor Link

Nothing. Invalid props are ignored. The plate inside the props is always replaced with the vehicle's own.

StoreVehicleCopy Anchor Link

Parks a vehicle: deletes its entity if it is out and sets its state and garage.

Side: Server · Waits: no

StoreVehicle(id: number, garage: string | null, state?: VehicleState): void

exports['ai-vehicles']:StoreVehicle(id, garage, state)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Nothing. It does not save the condition first: call SaveVehicle before it when the damage and fuel should be kept. To park through whatever garage script the server runs, use the lib's garages.store instead.

SetOwnerCopy Anchor Link

Gives a vehicle to another owner (a sale between players, a car moved into a job fleet).

Side: Server · Waits: no

SetOwner(id: number, owner: VehicleOwner): void

exports['ai-vehicles']:SetOwner(id, owner)

ReturnsCopy Anchor Link

Nothing. An invalid owner or unknown id does nothing. The keys of the old owner are not taken: remove them through the lib's vehicleKeys.remove if needed.

ExampleCopy Anchor Link

vehicles.SetOwner(vehicleId, { type: "job", id: "mechanic" });

DeleteVehicleCopy Anchor Link

Deletes an owned vehicle for good: its entity if it is out, and its database row.

Side: Server · Waits: no

DeleteVehicle(id: number): void

exports['ai-vehicles']:DeleteVehicle(id)

ReturnsCopy Anchor Link

Nothing.

SpawnVehicleCopy Anchor Link

Creates the entity of an owned vehicle in the world with its look, plate, fuel and state bags, and gives the keys to asker through the active key system. The vehicle's state becomes out.

Side: Server · Waits: no (the result arrives in cb)

SpawnVehicle(id: number, at: { x: number; y: number; z: number; heading: number }, asker: number, cb: (netId: number | null) => void, purpose?: KeyPurpose, setup?: VehicleSetup): void

exports['ai-vehicles']:SpawnVehicle(id, at, asker, function(netId) end, purpose, setup)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Nothing. cb gets the network id, or null when the vehicle does not exist, is already out, is being spawned right now, or the game could not create it.

ExampleCopy Anchor Link

import { resourceExport } from "@aicore-fivem/lib/server";

const vehicles = resourceExport("ai-vehicles");

export function bringOut(source: number, vehicleId: number): void {
  const ped = GetPlayerPed(String(source));
  const [x, y, z] = GetEntityCoords(ped);
  const heading = GetEntityHeading(ped);
  vehicles.SpawnVehicle(vehicleId, { x: x + 3, y, z, heading }, source, (netId) => {
    if (netId === null) console.log(`vehicle ${vehicleId} could not come out`);
  });
}

EventsCopy Anchor Link

ai-vehicles:ownersCopy Anchor Link

Fires when vehicles enter ai-vehicles' memory or change owner, and when plates leave memory. One batch per server tick. Read GetPlateOwners once at start, then apply these batches to keep a plate-to-owner copy. The name is VEHICLES_EVENTS.owners in @aicore-fivem/shared.

Side: Server (local event, not sent to clients)

import { resourceExport } from "@aicore-fivem/lib/server";
import { VEHICLES_EVENTS } from "@aicore-fivem/shared";

const owners = new Map<string, string>();
for (const [plate, type, id] of resourceExport("ai-vehicles").GetPlateOwners())
  owners.set(plate, `${type}:${id}`);

on(VEHICLES_EVENTS.owners, (puts: [string, string, string][], removes: string[]) => {
  for (const [plate, type, id] of puts) owners.set(plate, `${type}:${id}`);
  for (const plate of removes) owners.delete(plate);
});

State bagsCopy Anchor Link

ai-vehicles sets these on every owned vehicle it spawns. Names are in VEHICLE_BAGS (@aicore-fivem/shared).

local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
if Entity(vehicle).state['ai:owned'] then
  print('owned vehicle', Entity(vehicle).state['ai:vid'])
end

qbx_vehicles APICopy Anchor Link

ai-vehicles provides qbx_vehicles, so these calls reach it. Shapes follow Qbox: state is 0 out, 1 garage, 2 impound.

GetPlayerVehicle returns props in AI Core's VehicleProps shape, not ox_lib's. depotPrice is always 0.