Veículos

import { spawnVehicle, vehicleKeys, fuel, garages, vehicleFromNet } from "@aicore-fivem/lib/server";

SpawnCopy Anchor Link

spawnVehicleCopy Anchor Link

Cria um veículo em rede no servidor e o configura em uma chamada: placa, combustível, visual, tranca, routing bucket, chaves para o propósito certo, um motorista e passageiros. Use para todo veículo de script (veículos de emprego, aluguéis, veículos de garagem, spawns de admin).

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

spawnVehicle(options: SpawnVehicleOptions): Promise<number | null>

local vehicle = aiLib.spawnVehicle(options) -- entidade ou nil, chame dentro de uma thread

ParâmetrosCopy Anchor Link

SpawnVehicleOptionsCopy Anchor Link

RetornoCopy Anchor Link

Promise<number | null>: o handle da entidade do veículo. null quando o modelo não existe (o cliente asker disse isso), a entidade não foi criada em 5 segundos ou o tipo é desconhecido.

ExemploCopy Anchor Link

import { onClientCallback, spawnVehicle, hasCharacter, near } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const DEPOT = { x: 895.4, y: -179.3, z: 74.7 };

onClientCallback(
  "my-taxi:start",
  async (source) => {
    const vehicle = await spawnVehicle({
      model: "taxi",
      coords: { x: 899.1, y: -180.6, z: 73.8, heading: 238 },
      asker: source,
      keysTo: source,
      purpose: "job",
      driver: source,
      fuel: 100,
      setup: { dirt: 0 },
    });
    if (!vehicle) return fail("SPAWN_FAILED");
    return { ok: true, netId: NetworkGetNetworkIdFromEntity(vehicle) };
  },
  { guards: [hasCharacter(), near(DEPOT, 5)], lock: true },
);

vehicleTypeCopy Anchor Link

O tipo de spawn de um modelo, perguntado ao cliente de um jogador. Use para verificar se um modelo existe antes de cobrar o dinheiro.

Lado: Servidor · Espera: sim (Promise)

vehicleType(model: string, asker: number): Promise<string | null>

Sem equivalente em Lua: aiLib.spawnVehicle com asker faz essa verificação e retorna nil para um modelo desconhecido.

RetornoCopy Anchor Link

Promise<string | null>: automobile, bike, boat, heli, plane, submarine, trailer ou train; null quando o jogo não tem esse veículo ou o cliente não deu uma resposta válida. Uma resposta passa a valer para todos assim que os clientes de dois jogadores diferentes concordaram com ela, então um cliente modificado só consegue quebrar os próprios spawns.

ExemploCopy Anchor Link

import { onClientCallback, vehicleType } from "@aicore-fivem/lib/server";
import { fail, oneArg, readText } from "@aicore-fivem/lib/shared";

onClientCallback("my-dealer:buy", { args: oneArg((v) => readText(v, 32)), lock: true }, async (source, model) => {
  if (!(await vehicleType(model, source))) return fail("UNKNOWN_MODEL");
  // cobra o dinheiro, depois spawnVehicle(...)
  return { ok: true };
});

randomPlateCopy Anchor Link

Uma placa aleatória como as do próprio jogo (dois dígitos, três letras, três dígitos), ou o seu prefixo seguido de dígitos.

Lado: Servidor · Espera: não

randomPlate(prefix?: string): string

Sem equivalente em Lua (aiLib.spawnVehicle define uma placa aleatória quando você não passa nenhuma).

Retorno uma placa de 8 caracteres (42ABC123, ou TAXI1234 para randomPlate("TAXI")). Ela não é verificada quanto à unicidade: verifique a sua própria tabela antes de guardá-la.

const plate = randomPlate("RENT");

Encontrando veículosCopy Anchor Link

nearestVehicleToCopy Anchor Link

O veículo mais próximo, a até metres de um jogador, que passa no seu filtro. O veículo em que o jogador está sentado vence primeiro.

Lado: Servidor · Espera: não

nearestVehicleTo(source: number, metres: number, filter?: (vehicle: number) => boolean): number

local vehicle = aiLib.nearestVehicleTo(source, metres, filter) -- entidade ou 0

Retorno a entidade do veículo, ou 0 quando não há nenhum.

const vehicle = nearestVehicleTo(source, 5);
if (!vehicle) return fail("NO_VEHICLE");

nearestVehicleAtCopy Anchor Link

O veículo mais próximo a até metres de um ponto. Use para verificar se um local de spawn está livre.

Lado: Servidor · Espera: não

nearestVehicleAt(point: { x: number; y: number; z: number }, metres: number, filter?: (vehicle: number) => boolean): number

Sem equivalente em Lua.

Retorno a entidade do veículo, ou 0 quando não há nenhum. Percorre todos os veículos, como nearestVehicleTo.

const SPOT = { x: 899.1, y: -180.6, z: 73.8 };
if (nearestVehicleAt(SPOT, 3)) return fail("SPOT_BLOCKED");

Entidades a partir da entrada do clienteCopy Anchor Link

Um cliente envia um network id, nunca um handle de entidade. Estes helpers transformam um net id na entidade viva do servidor e a verificam, então você nunca chama NetworkGetEntityFromNetworkId + DoesEntityExist + GetEntityType à mão.

entityFromNetCopy Anchor Link

A entidade viva por trás do network id de um cliente.

Lado: Servidor · Espera: não

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

Sem equivalente em Lua (Lua tem vehicleFromNet).

Retorno a entidade, ou 0 quando o valor não é um número inteiro positivo, não está em rede, sumiu ou é de outro tipo.

const prop = entityFromNet(rawNetId, 3);
if (!prop) return fail("NOT_FOUND");

pedFromNetCopy Anchor Link

entityFromNet(netId, 1): o ped vivo, ou 0.

Lado: Servidor · Espera: não

pedFromNet(netId: unknown): number

Sem equivalente em Lua.

const ped = pedFromNet(rawNetId);

vehicleFromNetCopy Anchor Link

entityFromNet(netId, 2): o veículo vivo, ou 0.

Lado: Servidor · Espera: não

vehicleFromNet(netId: unknown): number

local vehicle = aiLib.vehicleFromNet(netId) -- entidade ou 0

const vehicle = vehicleFromNet(rawNetId);
if (!vehicle) return fail("NO_VEHICLE");

vehicleNearPlayerCopy Anchor Link

O veículo por trás do network id de um cliente, mas só quando o jogador está perto dele (ou no banco do motorista).

Lado: Servidor · Espera: não

vehicleNearPlayer(source: number, netId: unknown, options?: { metres?: number; driver?: boolean }): number

local vehicle = aiLib.vehicleNearPlayer(source, netId, options) -- entidade ou 0

Retorno o veículo, ou 0 quando o id é inválido, o veículo sumiu ou o jogador está longe demais / não é o motorista.

onClientCallback("my-tow:hook", { args: oneArg(readId), lock: true }, (source, netId) => {
  const vehicle = vehicleNearPlayer(source, netId, { metres: 6 });
  if (!vehicle) return fail("TOO_FAR");
  return { ok: true };
});

ChavesCopy Anchor Link

vehicleKeys passa pela camada de chaves do ai-core: o script de chaves que o servidor roda (ai-vehiclekeys, ou outro que o dono escolhe) responde. Um veículo é um handle de entidade do servidor ou uma placa.

vehicleKeys.giveCopy Anchor Link

Dá a um jogador as chaves de um veículo.

Lado: Servidor · Espera: não

vehicleKeys.give(source: number, vehicle: number | string, purpose?: KeyPurpose): void

aiLib.vehicleKeys.give(source, vehicle, purpose)

Retorno void.

vehicleKeys.give(source, vehicle, "rental");

vehicleKeys.removeCopy Anchor Link

Tira as chaves de um veículo de um jogador.

Lado: Servidor · Espera: não

vehicleKeys.remove(source: number, vehicle: number | string): void

aiLib.vehicleKeys.remove(source, vehicle)

Retorno void.

vehicleKeys.remove(source, "RENT1234");

vehicleKeys.hasCopy Anchor Link

Se um jogador tem as chaves.

Lado: Servidor · Espera: não

vehicleKeys.has(source: number, vehicle: number | string): boolean

local has = aiLib.vehicleKeys.has(source, vehicle)

Retorno boolean. true também quando o script de chaves não consegue informar ou nenhum está rodando, então não use isso como a única tranca de algo valioso.

if (!vehicleKeys.has(source, vehicle)) return fail("NO_KEYS");

CombustívelCopy Anchor Link

fuel lê e define o combustível de um veículo (0 a 100) pela camada de combustível do ai-core, qualquer que seja o script de combustível rodando. Sem equivalente em Lua no servidor: chame os exports do ai-core GetVehicleFuel / SetVehicleFuel.

fuel.getCopy Anchor Link

Lado: Servidor · Espera: não

fuel.get(vehicle: number): number | null

Retorno o nível de uma entidade de veículo do servidor (0 a 100), ou null quando ela não tem.

const level = fuel.get(vehicle) ?? 0;

fuel.setCopy Anchor Link

Lado: Servidor · Espera: não

fuel.set(vehicle: number, level: number): boolean

Retorno true quando definido, false para um veículo errado.

fuel.set(vehicle, 100);

fuel.providerCopy Anchor Link

Lado: Servidor · Espera: não

fuel.provider(): string | null

Retorno o nome do recurso do script de combustível que responde (ai-fuel, ox_fuel, LegacyFuel...), ou null quando nenhum está rodando.

console.log(`fuel through ${fuel.provider() ?? "nothing"}`);

GaragensCopy Anchor Link

garages passa pela camada de garagens do ai-core, qualquer que seja o script de garagem rodando; cada script responde só o que expõe. Sem equivalente em Lua.

garages.impoundCopy Anchor Link

Manda um veículo para o pátio de apreensão, ou abre o formulário de apreensão do script de garagem para by.

Lado: Servidor · Espera: não

garages.impound(vehicle: number, by?: number): boolean

Retorno true quando o script de garagem o aceitou. false quando nada o aceitou: apague o veículo você mesmo.

if (!garages.impound(vehicle, source)) DeleteEntity(vehicle);

garages.storeCopy Anchor Link

Guarda um veículo em uma garagem.

Lado: Servidor · Espera: não

garages.store(vehicle: number, garage?: string | null, by?: number): boolean

Retorno true quando guardado, false quando nada o aceitou.

if (!garages.store(vehicle, "legion", source)) return fail("STORE_FAILED");

garages.openCopy Anchor Link

Abre o menu de garagem do script de garagem para um jogador.

Lado: Servidor · Espera: não

garages.open(source: number, garage?: string | null): boolean

Retorno true quando aberto, false quando o script não tem esse menu.

garages.open(source, "pillbox");

garages.storedCopy Anchor Link

Os veículos de um jogador nas garagens ou no pátio de apreensão.

Lado: Servidor · Espera: sim (Promise)

garages.stored(source: number): Promise<GaragedVehicle[] | null>

Retorno GaragedVehicle[] (plate, model, garage, impounded), ou null quando o script não consegue informar ou o ai-core está parado.

const list = await garages.stored(source);
const impounded = list?.filter((v) => v.impounded).length ?? 0;

garages.providerCopy Anchor Link

Lado: Servidor · Espera: não

garages.provider(): string | null

Retorno o script de garagem que responde, ou null quando nenhum está rodando.

if (!garages.provider()) console.warn("no garage script runs");