Sondagens e carregamento

Perguntas ao jogo sobre o mundo (o que está na frente do jogador, qual a altura do chão, como se chama esta rua) e os carregadores de que todo modelo, animação e efeito precisa antes do uso.

SondagensCopy Anchor Link

raycastCopy Anchor Link

Uma sondagem por linha respondida no mesmo frame: o que a linha de from até to atinge primeiro. Use para "para onde o jogador está olhando", colocar objetos no chão ou linha de visão.

Lado: Cliente · Espera: não (bloqueia o frame até o teste terminar)

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

local hit = aiLib.raycast(from, to, options) -- table ou nil; from / to são vector3

ParâmetrosCopy Anchor Link

RaycastOptionsCopy Anchor Link

RetornoCopy Anchor Link

RayHit | null: { coords, normal, entity } para o primeiro acerto, ou null (nil) quando a linha não atinge nada.

ExemploCopy 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

A altura do chão sob um ponto, sondando para baixo a partir de z.

Lado: Cliente · Espera: não

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

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number | null: a altura do chão, ou null (nil) enquanto a colisão ali não está carregada (a área está longe do jogador).

ExemploCopy 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

Os nomes da rua, da rua transversal e da área em um ponto. Use em alertas de dispatch, mensagens de celular e HUDs.

Lado: Cliente · Espera: não

locationName(coords?: Vec3): LocationName

local where = aiLib.locationName(coords) -- coords é um vector3, opcional

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

LocationName:

ExemploCopy 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

O nome de exibição de um veículo (Sultan RS) a partir de um nome de modelo, um hash de modelo ou uma entidade de veículo.

Lado: Cliente · Espera: não

vehicleLabel(vehicle: string | number): string

local name = aiLib.vehicleLabel(vehicle)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

string: o rótulo do jogo para o modelo; o nome de exibição do modelo quando o jogo não tem texto para ele (veículos add-on sem entrada de texto); o nome ou hash do modelo como texto quando até isso falta.

ExemploCopy 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

O waypoint que o jogador marcou no mapa.

Lado: Cliente · Espera: não

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

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

RetornoCopy Anchor Link

{ x: number; y: number } | null: a posição do waypoint (sem altura: waypoints do mapa não têm), ou null (nil) quando nenhum waypoint está marcado.

ExemploCopy Anchor Link

Veja player.teleport: teleporte até o waypoint.

pedHeadshotCopy Anchor Link

Tira uma foto de rosto (headshot) de um ped e espera até o jogo renderizá-la. Use o nome da textura em uma página NUI como https://nui-img/<txd>/<txd>.

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

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

local handle, txd = aiLib.pedHeadshot(ped, transparent, timeout) -- chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<{ handle: number; txd: string } | null>: o handle do headshot e o nome da textura; null quando o ped não existe ou a renderização demorou mais que o timeout. Lua retorna handle, txd, ou nil.

ExemploCopy 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

Roda um handler no frame em que o ped local dispara um tiro (estresse, alertas de tiro, cápsulas). Uma verificação por frame para o seu recurso, ligada só enquanto há uma arma na mão.

Lado: Cliente · Espera: não

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

aiLib.onShot(function(weapon) end) -- não retorna nada

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

TypeScript: () => void, uma função que remove o handler. Lua não retorna nada (o handler fica).

ExemploCopy Anchor Link

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

let lastAlert = 0;
onShot(() => {
  if (GetGameTimer() - lastAlert < 30_000) return; // um alerta a cada 30 s
  lastAlert = GetGameTimer();
  emitNet("mypolice:shots");
});

Carregando assets do jogoCopy Anchor Link

Modelos, animações, efeitos e texturas precisam ser carregados antes do uso. Cada carregador pede o asset e espera até ele ficar pronto. Libere-o quando terminar, como cada entrada indica.

requestModelCopy Anchor Link

Carrega um modelo (ped, veículo, objeto) e dá o hash dele.

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

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

local hash = aiLib.requestModel(model, timeout) -- integer ou nil, chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<number>: o hash do modelo depois de carregado. Ela rejeita quando o modelo não existe nos arquivos do jogo ou não carrega a tempo. Lua retorna o hash, ou nil nos dois casos.

ExemploCopy 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

Carrega um dicionário de animação.

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

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

local dict = aiLib.requestAnimDict(dict, timeout) -- string ou nil, chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<string>: o nome do dicionário depois de carregado. Ela rejeita quando o dicionário não existe ou não carrega a tempo. Lua retorna o nome, ou nil.

ExemploCopy 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

Carrega um clipset de movimento (andar agachado, andar ferido).

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

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

local set = aiLib.requestAnimSet(set, timeout) -- string ou nil, chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<string>: o nome do clipset depois de carregado. Ela rejeita quando ele não carrega a tempo. Lua retorna o nome, ou nil.

ExemploCopy 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

Carrega um asset de efeito de partículas.

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

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

local asset = aiLib.requestPtfxAsset(asset, timeout) -- string ou nil, chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<string>: o nome do asset depois de carregado. Ela rejeita quando ele não carrega a tempo. Lua retorna o nome, ou nil.

ExemploCopy 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

Carrega um dicionário de texturas transmitido (para DrawSprite e similares).

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

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

local dict = aiLib.requestTextureDict(dict, timeout) -- string ou nil, chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<string>: o nome do dicionário depois de carregado. Ela rejeita quando ele não carrega a tempo. Lua retorna o nome, ou nil.

ExemploCopy 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

Carrega o modelo e os assets de uma arma e dá o hash dela.

Lado: Cliente · Espera: sim (Promise em TypeScript, pausa a thread em Lua)

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

local hash = aiLib.requestWeaponAsset(weapon, timeout) -- integer ou nil, chame dentro de uma thread

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Promise<number>: o hash da arma depois de carregada. Ela rejeita quando não carrega a tempo. Lua retorna o hash, ou nil.

ExemploCopy 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;
}