ai-vehicles para desarrolladores

ai-vehicles solo tiene exports de servidor. Todos son síncronos (sin Promise, sin esperas en Lua), salvo SpawnVehicle, que responde con un callback. Los tipos están en @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

Quién es dueño de un vehículo.

OwnedVehicleCopy Anchor Link

Lo que devuelven GetVehicle y GetVehicles.

Exports de servidorCopy Anchor Link

CreateVehicleCopy Anchor Link

Registra un vehículo en propiedad nuevo y lo aparca. Úsalo cuando un jugador consigue un vehículo (una compra, una recompensa, un regalo de un administrador). No hace aparecer el coche: sácalo con SpawnVehicle o deja que el jugador lo recoja en un garaje.

Lado: Servidor · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

{ id, plate } del vehículo nuevo. null cuando owner no es un dueño válido o model no es texto.

EjemploCopy Anchor Link

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

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

// Da al jugador un Sultan, aparcado en el garaje 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

Busca un vehículo en propiedad por su id o matrícula.

Lado: Servidor · Espera: no

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

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

El OwnedVehicle, o null cuando ningún vehículo en memoria tiene ese id o matrícula (también cuando pertenece a un personaje desconectado).

EjemploCopy Anchor Link

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

GetVehiclesCopy Anchor Link

Todos los vehículos de un dueño.

Lado: Servidor · Espera: no

GetVehicles(owner: VehicleOwner): OwnedVehicle[]

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Un array de OwnedVehicle. Vacío para un dueño no válido, un dueño sin vehículos o un personaje desconectado.

EjemploCopy 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

Si una matrícula pertenece a un vehículo en propiedad en memoria.

Lado: Servidor · Espera: no

IsOwnedPlate(plate: string): boolean

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

DevuelveCopy Anchor Link

true cuando un vehículo en propiedad tiene esta matrícula. false para una matrícula desconocida, un valor que no es texto o un vehículo de un personaje desconectado.

GetVehicleIdByEntityCopy Anchor Link

El id de ai-vehicles de un vehículo en propiedad que está en el mundo.

Lado: Servidor · Espera: no

GetVehicleIdByEntity(entity: number): number | null

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

El id del vehículo, o null cuando la entidad no es un vehículo en propiedad sacado por ai-vehicles.

GetEntityCopy Anchor Link

La entidad de un vehículo en propiedad que está en el mundo.

Lado: Servidor · Espera: no

GetEntity(id: number): number | null

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

DevuelveCopy Anchor Link

El handle de entidad de servidor, o null cuando el vehículo no está fuera o su entidad ya no existe.

GetPlateOwnersCopy Anchor Link

Todos los vehículos en propiedad en memoria como [plate, ownerType, ownerId]. Un script que debe comprobar muchas matrículas (un sistema de llaves) lee esto una vez al iniciar y después sigue el evento ai-vehicles:owners, en lugar de llamar a un export en cada comprobación.

Lado: Servidor · Espera: no

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

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

DevuelveCopy Anchor Link

Un array de tríos. Vacío cuando no hay ningún vehículo en memoria.

SaveVehicleCopy Anchor Link

Guarda el estado y el aspecto de un vehículo: combustible, daños, estado, garaje y props (colores, extras, suciedad). El tuning guardado (mods, neon) nunca cambia aquí, así que un aspecto leído del cliente de un jugador no puede guardar el trabajo de un mod menu. Usa SaveTuning para el tuning.

Lado: Servidor · Espera: no

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

DevuelveCopy Anchor Link

Nada. Un id desconocido no hace nada.

EjemploCopy Anchor Link

// Terminó un trabajo de reparación: motor y carrocería al máximo.
vehicles.SaveVehicle(vehicleId, { engine: 1000, body: 1000 });

SaveTuningCopy Anchor Link

Guarda las props completas, tuning incluido (mods, neon). Pensado solo para talleres de tuning: el taller de tuning propio de AI Core, ai-mechanic, es el único script ai-* que lo llama.

Lado: Servidor · Espera: no

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

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

DevuelveCopy Anchor Link

Nada. Las props no válidas se ignoran. La matrícula de dentro de las props siempre se reemplaza por la propia del vehículo.

StoreVehicleCopy Anchor Link

Aparca un vehículo: borra su entidad si está fuera y fija su estado y garaje.

Lado: Servidor · Espera: no

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

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Nada. No guarda antes el estado: llama a SaveVehicle antes cuando haya que conservar los daños y el combustible. Para aparcar con el script de garajes que use el servidor, usa en su lugar garages.store de la lib.

SetOwnerCopy Anchor Link

Da un vehículo a otro dueño (una venta entre jugadores, un coche pasado a una flota de trabajo).

Lado: Servidor · Espera: no

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

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

DevuelveCopy Anchor Link

Nada. Un dueño no válido o un id desconocido no hacen nada. Las llaves del dueño anterior no se quitan: quítalas con vehicleKeys.remove de la lib si hace falta.

EjemploCopy Anchor Link

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

DeleteVehicleCopy Anchor Link

Borra para siempre un vehículo en propiedad: su entidad si está fuera, y su fila de la base de datos.

Lado: Servidor · Espera: no

DeleteVehicle(id: number): void

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

DevuelveCopy Anchor Link

Nada.

SpawnVehicleCopy Anchor Link

Crea en el mundo la entidad de un vehículo en propiedad con su aspecto, matrícula, combustible y state bags, y da las llaves a asker a través del sistema de llaves activo. El estado del vehículo pasa a out.

Lado: Servidor · Espera: no (el resultado llega en 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

DevuelveCopy Anchor Link

Nada. cb recibe el network id, o null cuando el vehículo no existe, ya está fuera, está apareciendo justo ahora o el juego no pudo crearlo.

EjemploCopy 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

Se dispara cuando entran vehículos en la memoria de ai-vehicles o cambian de dueño, y cuando las matrículas salen de la memoria. Un lote por tick del servidor. Lee GetPlateOwners una vez al iniciar y después aplica estos lotes para mantener una copia de matrícula a dueño. El nombre es VEHICLES_EVENTS.owners en @aicore-fivem/shared.

Lado: Servidor (evento local, no se envía a los 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

ai-vehicles los fija en cada vehículo en propiedad que hace aparecer. Los nombres están en 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

ai-vehicles hace provide de qbx_vehicles, así que estas llamadas llegan a él. Las formas siguen a Qbox: state es 0 fuera, 1 garaje, 2 depósito.

GetPlayerVehicle devuelve las props con la forma VehicleProps de AI Core, no la de ox_lib. depotPrice siempre es 0.