ai-vehicles para desenvolvedores

O ai-vehicles só tem exports do servidor. Todos são síncronos (sem Promise, sem espera em Lua), exceto SpawnVehicle, que responde por um callback. Os tipos ficam em @aicore-fivem/shared (vehicles.ts).

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

local vehicles = exports['ai-vehicles']

TiposCopy Anchor Link

VehicleOwnerCopy Anchor Link

Quem é dono de um veículo.

OwnedVehicleCopy Anchor Link

O que GetVehicle e GetVehicles retornam.

Exports do servidorCopy Anchor Link

CreateVehicleCopy Anchor Link

Registra um novo veículo próprio e o estaciona. Use quando um jogador ganha um veículo (uma compra, uma recompensa, um presente de administrador). Ele não cria o carro no mundo: tire-o com SpawnVehicle ou deixe o jogador buscá-lo em uma garagem.

Lado: Servidor · Espera: não

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 } ou nil

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

{ id, plate } do novo veículo. null quando owner não é um dono válido ou model não é texto.

ExemploCopy Anchor Link

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

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

// Dá ao jogador um Sultan, estacionado na garagem Motel Parking.
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

Encontra um veículo próprio pelo id ou pela placa.

Lado: Servidor · Espera: não

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

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

O OwnedVehicle, ou null quando nenhum veículo na memória tem aquele id ou placa (também quando ele pertence a um personagem offline).

ExemploCopy Anchor Link

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

GetVehiclesCopy Anchor Link

Todos os veículos de um dono.

Lado: Servidor · Espera: não

GetVehicles(owner: VehicleOwner): OwnedVehicle[]

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Um array de OwnedVehicle. Vazio para um dono inválido, um dono sem veículos, ou um personagem offline.

ExemploCopy 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

Se uma placa pertence a um veículo próprio na memória.

Lado: Servidor · Espera: não

IsOwnedPlate(plate: string): boolean

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

RetornoCopy Anchor Link

true quando um veículo próprio tem esta placa. false para uma placa desconhecida, um valor que não é texto, ou um veículo de um personagem offline.

GetVehicleIdByEntityCopy Anchor Link

O id no ai-vehicles de um veículo próprio criado no mundo.

Lado: Servidor · Espera: não

GetVehicleIdByEntity(entity: number): number | null

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

O id do veículo, ou null quando a entidade não é um veículo próprio criado pelo ai-vehicles.

GetEntityCopy Anchor Link

A entidade de um veículo próprio criado no mundo.

Lado: Servidor · Espera: não

GetEntity(id: number): number | null

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

RetornoCopy Anchor Link

O handle de entidade do servidor, ou null quando o veículo não está fora ou a entidade dele não existe mais.

GetPlateOwnersCopy Anchor Link

Todos os veículos próprios na memória como [plate, ownerType, ownerId]. Um script que precisa verificar muitas placas (um sistema de chaves) lê isso uma vez na sua inicialização, depois acompanha o evento ai-vehicles:owners, em vez de chamar um export a cada verificação.

Lado: Servidor · Espera: não

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

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

RetornoCopy Anchor Link

Um array de trios. Vazio quando não há nenhum veículo na memória.

SaveVehicleCopy Anchor Link

Salva o estado e a aparência de um veículo: combustível, danos, estado, garagem e props (cores, extras, sujeira). O tuning guardado (mods, neon) nunca muda aqui, então uma aparência lida do cliente de um jogador não consegue salvar o trabalho de um mod menu. Use SaveTuning para tuning.

Lado: Servidor · Espera: não

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

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

ParâmetrosCopy Anchor Link

changeCopy Anchor Link

RetornoCopy Anchor Link

Nada. Um id desconhecido não faz nada.

ExemploCopy Anchor Link

// Um trabalho de reparo terminou: motor e lataria cheios.
vehicles.SaveVehicle(vehicleId, { engine: 1000, body: 1000 });

SaveTuningCopy Anchor Link

Salva as props completas, tuning incluído (mods, neon). Feito só para oficinas de tuning: a própria oficina de tuning do AI Core, o ai-mechanic, é o único script ai-* que o chama.

Lado: Servidor · Espera: não

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

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

RetornoCopy Anchor Link

Nada. Props inválidas são ignoradas. A placa dentro das props é sempre substituída pela do próprio veículo.

StoreVehicleCopy Anchor Link

Estaciona um veículo: apaga a entidade dele se estiver fora e define seu estado e garagem.

Lado: Servidor · Espera: não

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

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Nada. Ele não salva o estado antes: chame SaveVehicle antes dele quando os danos e o combustível devem ser mantidos. Para estacionar por qualquer script de garagem que o servidor rode, use o garages.store da lib.

SetOwnerCopy Anchor Link

Dá um veículo a outro dono (uma venda entre jogadores, um carro movido para uma frota de emprego).

Lado: Servidor · Espera: não

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

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

RetornoCopy Anchor Link

Nada. Um dono inválido ou um id desconhecido não faz nada. As chaves do dono antigo não são retiradas: remova-as pelo vehicleKeys.remove da lib se for preciso.

ExemploCopy Anchor Link

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

DeleteVehicleCopy Anchor Link

Apaga um veículo próprio de vez: a entidade dele se estiver fora, e a linha dele no banco de dados.

Lado: Servidor · Espera: não

DeleteVehicle(id: number): void

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

RetornoCopy Anchor Link

Nada.

SpawnVehicleCopy Anchor Link

Cria a entidade de um veículo próprio no mundo com sua aparência, placa, combustível e state bags, e dá as chaves a asker pelo sistema de chaves ativo. O estado do veículo passa a ser out.

Lado: Servidor · Espera: não (o resultado chega em 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)

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Nada. cb recebe o id de rede, ou null quando o veículo não existe, já está fora, está sendo criado neste momento, ou o jogo não conseguiu criá-lo.

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

EventosCopy Anchor Link

ai-vehicles:ownersCopy Anchor Link

Disparado quando veículos entram na memória do ai-vehicles ou mudam de dono, e quando placas saem da memória. Um lote por tick do servidor. Leia GetPlateOwners uma vez na inicialização, depois aplique esses lotes para manter uma cópia de placa para dono. O nome é VEHICLES_EVENTS.owners em @aicore-fivem/shared.

Lado: Servidor (evento local, não enviado aos clientes)

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

O ai-vehicles define estes em todo veículo próprio que cria. Os nomes ficam em 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

O ai-vehicles faz provide de qbx_vehicles, então essas chamadas chegam a ele. Os formatos seguem o Qbox: state é 0 fora, 1 garagem, 2 apreensão.

GetPlayerVehicle retorna as props no formato VehicleProps do AI Core, não no do ox_lib. depotPrice é sempre 0.