Vehicles and entities

Finding vehicles near the player, turning network ids from the server into local entities, and reading or applying a vehicle's look. Spawning a vehicle is server-only (spawnVehicle on Vehicles); a local showroom car is PreviewVehicle.

Finding vehiclesCopy Anchor Link

nearestVehicleCopy Anchor Link

The closest vehicle within a distance of the local player. The vehicle the player sits in wins first, unless notOwn. Use filter to skip vehicles that do not fit, so the trunk the player stands behind wins over a closer car next to it.

Side: Client · Waits: no

nearestVehicle(metres: number, options?: { networked?: boolean; notOwn?: boolean; filter?: (vehicle: number) => boolean }): number

local vehicle = aiLib.nearestVehicle(metres, options) -- 0 when none

ParametersCopy Anchor Link

OptionsCopy Anchor Link

ReturnsCopy Anchor Link

number: the vehicle handle, or 0 when none is within metres.

ExampleCopy Anchor Link

import { callAction, nearestVehicle, notify } from "@aicore-fivem/lib/client";

export async function impound(): Promise<void> {
  const vehicle = nearestVehicle(5, { notOwn: true, filter: (v) => GetPedInVehicleSeat(v, -1) === 0 });
  if (!vehicle) return notify("No empty vehicle near", "error");
  await callAction("mypolice:impound", [NetworkGetNetworkIdFromEntity(vehicle)], { fallback: "IMPOUND_FAILED" });
}

drivenVehicleCopy Anchor Link

The vehicle the local player drives (sits in the driver seat).

Side: Client · Waits: no

drivenVehicle(): number | false

No Lua twin: aiLib.cache.seat == -1 and aiLib.cache.vehicle.

ReturnsCopy Anchor Link

number | false: the vehicle handle when the player is the driver, false on foot or as a passenger.

ExampleCopy Anchor Link

import { drivenVehicle, notify } from "@aicore-fivem/lib/client";

RegisterCommand(
  "flip",
  () => {
    const vehicle = drivenVehicle();
    if (vehicle === false) return notify("You must drive a vehicle", "error");
    SetVehicleOnGroundProperly(vehicle);
  },
  false,
);

Entities from network idsCopy Anchor Link

The server sends entities as network ids. On a client the entity may not exist yet (the player is far, or it was just created).

waitForEntityCopy Anchor Link

Waits until the entity of a network id exists on this client and returns it.

Side: Client · Waits: yes (Promise in TypeScript, yields the thread in Lua)

waitForEntity(netId: number, timeoutMs?: number): Promise<number>

local entity = aiLib.waitForEntity(netId, timeout) -- call inside a thread

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<number>: the local entity handle, or 0 after the timeout. It never rejects.

ExampleCopy Anchor Link

import { onServerEvent, waitForEntity } from "@aicore-fivem/lib/client";
import { readId } from "@aicore-fivem/lib/shared";

// The server spawned a job vehicle and sends its net id.
onServerEvent(
  "myjob:vehicle",
  { args: ([id]) => { const netId = readId(id); return netId === null ? null : [netId]; } },
  async (netId) => {
    const vehicle = await waitForEntity(netId);
    if (vehicle) SetVehicleFuelLevel(vehicle, 100);
  },
);

entityFromNetIdCopy Anchor Link

The local entity of a network id right now, without waiting. Optionally checks the entity type.

Side: Client · Waits: no

entityFromNetId(netId: number, type?: 1 | 2 | 3): number

No Lua twin: NetworkDoesEntityExistWithNetworkId(netId) and NetToEnt(netId) or 0.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: the entity handle, or 0 when it is not on this client or not of type.

ExampleCopy Anchor Link

import { entityFromNetId, EntityState, stateBoolean } from "@aicore-fivem/lib/client";

const sirens = new EntityState("sirensMuted", stateBoolean);

sirens.onChange((netId, muted) => {
  const vehicle = entityFromNetId(netId, 2);
  if (vehicle) SetVehicleHasMutedSirens(vehicle, muted === true);
});

Vehicle lookCopy Anchor Link

getVehiclePropsCopy Anchor Link

Reads every property of a vehicle this client can see: plate, colours, mods, extras, neon, damage. Store the result to put the same look back later.

Side: Client · Waits: no

getVehicleProps(vehicle: number): VehicleProps

No Lua twin.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

VehicleProps: v (format version 1), model, plate (trimmed), plateIndex, colors, extraColors, customPrimary, customSecondary (RGB or null), wheelType, windowTint, livery, mods (by mod type 0-49; toggle mods 17-22 as 1 or 0), xenonColor, neon (four booleans), neonColor, tyreSmoke, extras (by extra id), dirt, engineHealth, bodyHealth.

ExampleCopy Anchor Link

import { callAction, drivenVehicle, getVehicleProps } from "@aicore-fivem/lib/client";

export async function saveLook(): Promise<void> {
  const vehicle = drivenVehicle();
  if (vehicle === false) return;
  await callAction("mygarage:saveProps", [NetworkGetNetworkIdFromEntity(vehicle), getVehicleProps(vehicle)], { fallback: "SAVE_FAILED" });
}

setVehiclePropsCopy Anchor Link

Applies stored properties to a vehicle. Only works on a vehicle this client controls; other players get the look through the network.

Side: Client · Waits: no

setVehicleProps(vehicle: number, props: VehicleProps): void

No Lua twin.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

void.

ExampleCopy Anchor Link

import { onServerEvent, setVehicleProps, waitForEntity } from "@aicore-fivem/lib/client";
import { readId, toVehicleProps } from "@aicore-fivem/lib/shared";

onServerEvent(
  "mygarage:look",
  {
    args: ([id, raw]) => {
      const netId = readId(id);
      const props = toVehicleProps(raw);
      return netId === null || props === null ? null : [netId, props];
    },
  },
  async (netId, props) => {
    const vehicle = await waitForEntity(netId);
    if (vehicle && NetworkHasControlOfEntity(vehicle)) setVehicleProps(vehicle, props);
  },
);

setVehicleSetupCopy Anchor Link

Applies a spawn setup to a fresh vehicle: maxed performance, colours, livery, tint, dirt, engine on. Only works on a vehicle this client controls.

Side: Client · Waits: no

setVehicleSetup(vehicle: number, setup: VehicleSetup): void

No Lua twin.

ParametersCopy Anchor Link

VehicleSetupCopy Anchor Link

The type is VehicleSetup.

ReturnsCopy Anchor Link

void.

ExampleCopy Anchor Link

import { PreviewVehicle, setVehicleSetup } from "@aicore-fivem/lib/client";

const preview = new PreviewVehicle();

export function showMaxed(model: string): Promise<number> {
  return preview.show(model, { x: -44.4, y: -1097.1, z: 26.4, heading: 120 }, (vehicle) =>
    setVehicleSetup(vehicle, { maxed: true, primary: [20, 200, 120], windowTint: 1 }),
  );
}