Probes and loading

Questions to the game about the world (what is in front of the player, how high is the ground, what is this street called) and the loaders every model, animation and effect needs before use.

ProbesCopy Anchor Link

raycastCopy Anchor Link

A line probe answered in the same frame: what the line from from to to hits first. Use it for "what is the player looking at", placing objects on the ground, or line of sight.

Side: Client · Waits: no (it blocks the frame until the test is done)

raycast(from: Vec3, to: Vec3, options?: RaycastOptions): RayHit | null

local hit = aiLib.raycast(from, to, options) -- table or nil; from / to are vector3

ParametersCopy Anchor Link

RaycastOptionsCopy Anchor Link

ReturnsCopy Anchor Link

RayHit | null: { coords, normal, entity } for the first hit, or null (nil) when the line hits nothing.

ExampleCopy Anchor Link

import { raycast } from "@aicore-fivem/lib/client";

/** What the camera looks at within 10 m. */
export function lookedAt(): number {
  const [cx = 0, cy = 0, cz = 0] = GetGameplayCamCoord();
  const [rx = 0, , rz = 0] = GetGameplayCamRot(2);
  const pitch = (rx * Math.PI) / 180;
  const yaw = (rz * Math.PI) / 180;
  const dir = { x: -Math.sin(yaw) * Math.cos(pitch), y: Math.cos(yaw) * Math.cos(pitch), z: Math.sin(pitch) };
  const hit = raycast(
    { x: cx, y: cy, z: cz },
    { x: cx + dir.x * 10, y: cy + dir.y * 10, z: cz + dir.z * 10 },
    { flags: 2 | 4 | 16 },
  );
  return hit?.entity ?? 0;
}

groundZCopy Anchor Link

The ground height under a point, probing down from z.

Side: Client · Waits: no

groundZ(x: number, y: number, z?: number): number | null

local ground = aiLib.groundZ(x, y, z) -- number or nil

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number | null: the ground height, or null (nil) while the collision there is not loaded (the area is far from the player).

ExampleCopy Anchor Link

import { groundZ, player } from "@aicore-fivem/lib/client";

const { x, y, z } = player.coords();
const ground = groundZ(x, y, z + 2);
if (ground !== null) console.log(`ground is ${(z - ground).toFixed(2)} m below`);

locationNameCopy Anchor Link

The street, crossing street and area names at a point. Use it in dispatch alerts, phone messages and HUDs.

Side: Client · Waits: no

locationName(coords?: Vec3): LocationName

local where = aiLib.locationName(coords) -- coords is a vector3, optional

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

LocationName:

ExampleCopy Anchor Link

import { locationName } from "@aicore-fivem/lib/client";

const { street, crossing, zone } = locationName();
const text = crossing ? `${street} / ${crossing}, ${zone}` : `${street}, ${zone}`;

vehicleLabelCopy Anchor Link

A vehicle's display name (Sultan RS) from a model name, a model hash or a vehicle entity.

Side: Client · Waits: no

vehicleLabel(vehicle: string | number): string

local name = aiLib.vehicleLabel(vehicle)

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string: the game's label for the model; the model's display name when the game has no text for it (add-on vehicles without a text entry); the model name or hash as text when even that is missing.

ExampleCopy Anchor Link

import { cache, notify, onCache, vehicleLabel } from "@aicore-fivem/lib/client";

onCache("vehicle", (vehicle) => {
  if (vehicle !== false && cache.seat === -1) notify(vehicleLabel(vehicle), "info", 2000);
});

waypointCopy Anchor Link

The waypoint the player set on the map.

Side: Client · Waits: no

waypoint(): { x: number; y: number } | null

local target = aiLib.waypoint() -- { x, y } or nil

ReturnsCopy Anchor Link

{ x: number; y: number } | null: the waypoint position (no height: map waypoints have none), or null (nil) when no waypoint is set.

ExampleCopy Anchor Link

See player.teleport: teleporting to the waypoint.

pedHeadshotCopy Anchor Link

Takes a headshot picture of a ped and waits until the game rendered it. Use the texture name in a NUI page as https://nui-img/<txd>/<txd>.

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

pedHeadshot(ped: number, transparent?: boolean, timeoutMs?: number): Promise<{ handle: number; txd: string } | null>

local handle, txd = aiLib.pedHeadshot(ped, transparent, timeout) -- call inside a thread

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ handle: number; txd: string } | null>: the headshot handle and its texture name; null when the ped does not exist or the render took longer than the timeout. Lua returns handle, txd, or nil.

ExampleCopy Anchor Link

import { cache, pedHeadshot } from "@aicore-fivem/lib/client";

export async function sendMugshot(): Promise<void> {
  const shot = await pedHeadshot(cache.ped, true);
  if (!shot) return;
  SendNUIMessage({ action: "photo", data: `https://nui-img/${shot.txd}/${shot.txd}` });
  setTimeout(() => UnregisterPedheadshot(shot.handle), 10_000);
}

onShotCopy Anchor Link

Runs a handler in the frame the local ped fires a shot (stress, shot alerts, casings). One per-frame check for your resource, on only while a weapon is in hand.

Side: Client · Waits: no

onShot(handler: (weapon: number) => void): () => void

aiLib.onShot(function(weapon) end) -- returns nothing

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

TypeScript: () => void, a function that removes the handler. Lua returns nothing (the handler stays).

ExampleCopy Anchor Link

import { onShot } from "@aicore-fivem/lib/client";

let lastAlert = 0;
onShot(() => {
  if (GetGameTimer() - lastAlert < 30_000) return; // one alert per 30 s
  lastAlert = GetGameTimer();
  emitNet("mypolice:shots");
});

Loading game assetsCopy Anchor Link

Models, animations, effects and textures must be loaded before use. Each loader requests the asset and waits until it is ready. Free it when you are done, as each entry says.

requestModelCopy Anchor Link

Loads a model (ped, vehicle, object) and gives its hash.

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

requestModel(model: string | number, timeoutMs?: number): Promise<number>

local hash = aiLib.requestModel(model, timeout) -- integer or nil, call inside a thread

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<number>: the model hash once loaded. It rejects when the model does not exist in the game files or does not load in time. Lua returns the hash, or nil in both cases.

ExampleCopy Anchor Link

import { requestModel } from "@aicore-fivem/lib/client";

export async function placeCone(x: number, y: number, z: number): Promise<number> {
  const hash = await requestModel("prop_roadcone02a");
  const cone = CreateObject(hash, x, y, z, false, false, false);
  SetModelAsNoLongerNeeded(hash);
  PlaceObjectOnGroundProperly(cone);
  return cone;
}

requestAnimDictCopy Anchor Link

Loads an animation dictionary.

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

requestAnimDict(dict: string, timeoutMs?: number): Promise<string>

local dict = aiLib.requestAnimDict(dict, timeout) -- string or nil, call inside a thread

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<string>: the dictionary name once loaded. It rejects when the dictionary does not exist or does not load in time. Lua returns the name, or nil.

ExampleCopy Anchor Link

import { cache, requestAnimDict } from "@aicore-fivem/lib/client";

export async function dance(): Promise<void> {
  const dict = await requestAnimDict("anim@amb@nightclub@dancers@crowddance_facedj@");
  TaskPlayAnim(cache.ped, dict, "hi_dance_facedj_09_v2_male^1", 8, -8, -1, 1, 0, false, false, false);
  RemoveAnimDict(dict);
}

requestAnimSetCopy Anchor Link

Loads a movement clipset (crouch walk, injured walk).

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

requestAnimSet(set: string, timeoutMs?: number): Promise<string>

local set = aiLib.requestAnimSet(set, timeout) -- string or nil, call inside a thread

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<string>: the clipset name once loaded. It rejects when it does not load in time. Lua returns the name, or nil.

ExampleCopy Anchor Link

import { cache, requestAnimSet } from "@aicore-fivem/lib/client";

export async function limp(): Promise<void> {
  const set = await requestAnimSet("move_m@injured");
  SetPedMovementClipset(cache.ped, set, 0.2);
}

requestPtfxAssetCopy Anchor Link

Loads a particle effect asset.

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

requestPtfxAsset(asset: string, timeoutMs?: number): Promise<string>

local asset = aiLib.requestPtfxAsset(asset, timeout) -- string or nil, call inside a thread

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<string>: the asset name once loaded. It rejects when it does not load in time. Lua returns the name, or nil.

ExampleCopy Anchor Link

import { player, requestPtfxAsset } from "@aicore-fivem/lib/client";

export async function sparks(): Promise<void> {
  const asset = await requestPtfxAsset("core");
  const { x, y, z } = player.coords();
  UseParticleFxAsset(asset);
  StartParticleFxNonLoopedAtCoord("ent_sht_electrical_box", x, y, z, 0, 0, 0, 1, false, false, false);
  RemoveNamedPtfxAsset(asset);
}

requestTextureDictCopy Anchor Link

Loads a streamed texture dictionary (for DrawSprite and similar).

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

requestTextureDict(dict: string, timeoutMs?: number): Promise<string>

local dict = aiLib.requestTextureDict(dict, timeout) -- string or nil, call inside a thread

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<string>: the dictionary name once loaded. It rejects when it does not load in time. Lua returns the name, or nil.

ExampleCopy Anchor Link

import { every, requestTextureDict } from "@aicore-fivem/lib/client";

export async function showCrosshair(): Promise<void> {
  const dict = await requestTextureDict("shared");
  every(0, () => DrawSprite(dict, "emptydot_32", 0.5, 0.5, 0.01, 0.018, 0, 255, 255, 255, 200));
}

requestWeaponAssetCopy Anchor Link

Loads a weapon's model and assets and gives its hash.

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

requestWeaponAsset(weapon: string | number, timeoutMs?: number): Promise<number>

local hash = aiLib.requestWeaponAsset(weapon, timeout) -- integer or nil, call inside a thread

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<number>: the weapon hash once loaded. It rejects when it does not load in time. Lua returns the hash, or nil.

ExampleCopy Anchor Link

import { player, requestWeaponAsset } from "@aicore-fivem/lib/client";

export async function showcasePistol(): Promise<number> {
  const hash = await requestWeaponAsset("WEAPON_PISTOL");
  const { x, y, z } = player.coords();
  const object = CreateWeaponObject(hash, 0, x, y, z + 1, true, 1, 0);
  RemoveWeaponAsset(hash);
  return object;
}