AI Core
Referência da APILib: cliente

Veículos e entidades

nearestVehicle, drivenVehicle, waitForEntity, entityFromNetId e os helpers de props de veículo - encontrar veículos e entidades no cliente e ler ou aplicar o visual de um veículo.

Encontrar veículos perto do jogador, transformar network ids vindos do servidor em entidades locais, e ler ou aplicar o visual de um veículo. Spawnar um veículo é só no servidor (spawnVehicle em Veículos); um carro local de vitrine é PreviewVehicle.

Encontrando veículos

nearestVehicle

O veículo mais próximo dentro de uma distância do jogador local. O veículo em que o jogador está sentado vence primeiro, a menos que notOwn. Use filter para pular veículos que não servem, para que o porta-malas atrás do qual o jogador está vença um carro mais próximo ao lado.

Lado: Cliente · Espera: não

Signature
nearestVehicle(metres: number, options?: { networked?: boolean; notOwn?: boolean; filter?: (vehicle: number) => boolean }): number
Lua
local vehicle = aiLib.nearestVehicle(metres, options) -- 0 quando não há nenhum

Parâmetros

Prop

Type

Opções

Prop

Type

Retorno

number: o handle do veículo, ou 0 quando nenhum está a até metres.

Exemplo

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" });
}

Ela percorre todos os veículos que o cliente conhece, então chame em um aperto de tecla ou uma ação, não a cada frame. Envie o veículo ao servidor como network id; o servidor o transforma de volta com vehicleFromNet ou vehicleNearPlayer e verifica a distância.

drivenVehicle

O veículo que o jogador local dirige (sentado no banco do motorista).

Lado: Cliente · Espera: não

Signature
drivenVehicle(): number | false

Sem equivalente em Lua: aiLib.cache.seat == -1 and aiLib.cache.vehicle.

Retorno

number | false: o handle do veículo quando o jogador é o motorista, false a pé ou como passageiro.

Exemplo

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,
);

Entidades a partir de network ids

O servidor envia entidades como network ids. Em um cliente a entidade pode ainda não existir (o jogador está longe, ou ela acabou de ser criada).

waitForEntity

Espera até a entidade de um network id existir neste cliente e a retorna.

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

Signature
waitForEntity(netId: number, timeoutMs?: number): Promise<number>
Lua
local entity = aiLib.waitForEntity(netId, timeout) -- chame dentro de uma thread

Parâmetros

Prop

Type

Retorno

Promise<number>: o handle da entidade local, ou 0 depois do timeout. Nunca rejeita.

Exemplo

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

// O servidor spawnou um veículo de emprego e envia o net id dele.
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);
  },
);

entityFromNetId

A entidade local de um network id agora mesmo, sem esperar. Opcionalmente verifica o tipo da entidade.

Lado: Cliente · Espera: não

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

Sem equivalente em Lua: NetworkDoesEntityExistWithNetworkId(netId) and NetToEnt(netId) or 0.

Parâmetros

Prop

Type

Retorno

number: o handle da entidade, ou 0 quando ela não está neste cliente ou não é do type.

Exemplo

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

Visual do veículo

getVehicleProps

Lê todas as propriedades de um veículo que este cliente consegue ver: placa, cores, mods, extras, neon, danos. Guarde o resultado para colocar o mesmo visual de volta depois.

Lado: Cliente · Espera: não

Signature
getVehicleProps(vehicle: number): VehicleProps

Sem equivalente em Lua.

Parâmetros

Prop

Type

Retorno

VehicleProps: v (versão do formato 1), model, plate (sem espaços nas pontas), plateIndex, colors, extraColors, customPrimary, customSecondary (RGB ou null), wheelType, windowTint, livery, mods (por tipo de mod 0-49; mods de liga/desliga 17-22 como 1 ou 0), xenonColor, neon (quatro booleanos), neonColor, tyreSmoke, extras (por id de extra), dirt, engineHealth, bodyHealth.

Exemplo

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" });
}

As props vêm do cliente do jogador: o servidor precisa interpretá-las e verificá-las (toVehicleProps de @aicore-fivem/lib/shared) antes de guardar.

setVehicleProps

Aplica propriedades salvas a um veículo. Só funciona em um veículo que este cliente controla; os outros jogadores recebem o visual pela rede.

Lado: Cliente · Espera: não

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

Sem equivalente em Lua.

Parâmetros

Prop

Type

Retorno

void.

Exemplo

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);
  },
);

Um veículo spawnado com spawnVehicle({ props }) já recebe o visual aplicado pelo ai-core no cliente dono. Você só precisa de setVehicleProps para os seus próprios fluxos.

setVehicleSetup

Aplica uma configuração de spawn a um veículo novo: desempenho no máximo, cores, livery, insulfilm, sujeira, motor ligado. Só funciona em um veículo que este cliente controla.

Lado: Cliente · Espera: não

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

Sem equivalente em Lua.

Parâmetros

Prop

Type

VehicleSetup

Prop

Type

O tipo é VehicleSetup.

Retorno

void.

Exemplo

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 }),
  );
}

Camadas pelo ai-core

medical, appearance, gestures, seatbelt, fuel, mdt, radial, world e inventory - chamadas do cliente que alcançam qualquer script de morte, roupas, emotes, cinto, combustível, MDT, radial, clima ou inventário que o servidor roda.

Sondagens e carregamento

raycast, groundZ, locationName, vehicleLabel, waypoint, pedHeadshot, onShot e os carregadores request - perguntar ao jogo sobre o mundo e carregar assets do jogo.

Nesta página

Encontrando veículosnearestVehicleParâmetrosOpçõesRetornoExemplodrivenVehicleRetornoExemploEntidades a partir de network idswaitForEntityParâmetrosRetornoExemploentityFromNetIdParâmetrosRetornoExemploVisual do veículogetVehiclePropsParâmetrosRetornoExemplosetVehiclePropsParâmetrosRetornoExemplosetVehicleSetupParâmetrosVehicleSetupRetornoExemplo