Vehículos

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

ApariciónCopy Anchor Link

spawnVehicleCopy Anchor Link

Crea un vehículo en red en el servidor y lo configura en una sola llamada: matrícula, combustible, aspecto, cierre, routing bucket, llaves con el propósito adecuado, un conductor y pasajeros. Úsalo para cada vehículo de script (vehículos de trabajo, alquileres, vehículos de garaje, spawns de admin).

Lado: Servidor · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

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

local vehicle = aiLib.spawnVehicle(options) -- entidad o nil, llamar dentro de un hilo

ParámetrosCopy Anchor Link

SpawnVehicleOptionsCopy Anchor Link

DevuelveCopy Anchor Link

Promise<number | null>: el handle de entidad del vehículo. null cuando el modelo no existe (lo dijo el cliente asker), la entidad no se creó en 5 segundos o el tipo es desconocido.

EjemploCopy 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

El tipo de spawn de un modelo, preguntado al cliente de un jugador. Úsalo para comprobar que un modelo existe antes de cobrar.

Lado: Servidor · Espera: sí (Promise)

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

Sin equivalente en Lua: aiLib.spawnVehicle con asker lo comprueba y devuelve nil para un modelo desconocido.

DevuelveCopy Anchor Link

Promise<string | null>: automobile, bike, boat, heli, plane, submarine, trailer o train; null cuando el juego no tiene ese vehículo o el cliente no dio una respuesta válida. Una respuesta se guarda para todos una vez que los clientes de dos jugadores distintos coincidieron en ella, así que un cliente modificado solo puede romper sus propios spawns.

EjemploCopy 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 el dinero y luego spawnVehicle(...)
  return { ok: true };
});

randomPlateCopy Anchor Link

Una matrícula aleatoria como las del propio juego (dos dígitos, tres letras, tres dígitos), o tu prefijo seguido de dígitos.

Lado: Servidor · Espera: no

randomPlate(prefix?: string): string

Sin equivalente en Lua (aiLib.spawnVehicle pone una matrícula aleatoria cuando no pasas ninguna).

Devuelve una matrícula de 8 caracteres (42ABC123, o TAXI1234 para randomPlate("TAXI")). No se comprueba que sea única: comprueba tu propia tabla antes de guardarla.

const plate = randomPlate("RENT");

Encontrar vehículosCopy Anchor Link

nearestVehicleToCopy Anchor Link

El vehículo más cercano a menos de metres de un jugador que pasa tu filtro. El vehículo en el que está sentado el jugador gana primero.

Lado: Servidor · Espera: no

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

local vehicle = aiLib.nearestVehicleTo(source, metres, filter) -- entidad o 0

Devuelve la entidad del vehículo, o 0 cuando no hay ninguno.

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

nearestVehicleAtCopy Anchor Link

El vehículo más cercano a menos de metres de un punto. Úsalo para comprobar que un sitio de spawn está libre.

Lado: Servidor · Espera: no

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

Sin equivalente en Lua.

Devuelve la entidad del vehículo, o 0 cuando no hay ninguno. Recorre todos los vehí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 de la entrada del clienteCopy Anchor Link

Un cliente envía un network id, nunca un handle de entidad. Estas funciones convierten un net id en la entidad viva del servidor y la comprueban, así que nunca llamas a mano a NetworkGetEntityFromNetworkId + DoesEntityExist + GetEntityType.

entityFromNetCopy Anchor Link

La entidad viva detrás del network id de un cliente.

Lado: Servidor · Espera: no

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

Sin equivalente en Lua (Lua tiene vehicleFromNet).

Devuelve la entidad, o 0 cuando el valor no es un número entero positivo, no está en red, ya no existe o es de otro tipo.

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

pedFromNetCopy Anchor Link

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

Lado: Servidor · Espera: no

pedFromNet(netId: unknown): number

Sin equivalente en Lua.

const ped = pedFromNet(rawNetId);

vehicleFromNetCopy Anchor Link

entityFromNet(netId, 2): el vehículo vivo, o 0.

Lado: Servidor · Espera: no

vehicleFromNet(netId: unknown): number

local vehicle = aiLib.vehicleFromNet(netId) -- entidad o 0

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

vehicleNearPlayerCopy Anchor Link

El vehículo detrás del network id de un cliente, pero solo cuando el jugador está cerca de él (o en su asiento del conductor).

Lado: Servidor · Espera: no

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

local vehicle = aiLib.vehicleNearPlayer(source, netId, options) -- entidad o 0

Devuelve el vehículo, o 0 cuando el id no es válido, el vehículo ya no existe o el jugador está demasiado lejos / no es el conductor.

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

LlavesCopy Anchor Link

vehicleKeys pasa por la capa de llaves de ai-core: responde el script de llaves que usa el servidor (ai-vehiclekeys, u otro que elija el dueño). Un vehículo es un handle de entidad del servidor o una matrícula.

vehicleKeys.giveCopy Anchor Link

Da a un jugador las llaves de un vehículo.

Lado: Servidor · Espera: no

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

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

Devuelve void.

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

vehicleKeys.removeCopy Anchor Link

Quita a un jugador las llaves de un vehículo.

Lado: Servidor · Espera: no

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

aiLib.vehicleKeys.remove(source, vehicle)

Devuelve void.

vehicleKeys.remove(source, "RENT1234");

vehicleKeys.hasCopy Anchor Link

Si un jugador tiene las llaves.

Lado: Servidor · Espera: no

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

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

Devuelve boolean. También true cuando el script de llaves no puede saberlo o no hay ninguno en marcha, así que no lo uses como único cierre de algo valioso.

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

CombustibleCopy Anchor Link

fuel lee y fija el combustible de un vehículo (de 0 a 100) a través de la capa de combustible de ai-core, sea cual sea el script de combustible que funcione. Sin equivalente en Lua en el servidor: llama a los exports de ai-core GetVehicleFuel / SetVehicleFuel.

fuel.getCopy Anchor Link

Lado: Servidor · Espera: no

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

Devuelve el nivel de una entidad de vehículo del servidor (de 0 a 100), o null cuando no tiene.

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

fuel.setCopy Anchor Link

Lado: Servidor · Espera: no

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

Devuelve true cuando se fijó, false para un vehículo incorrecto.

fuel.set(vehicle, 100);

fuel.providerCopy Anchor Link

Lado: Servidor · Espera: no

fuel.provider(): string | null

Devuelve el nombre del recurso del script de combustible que responde (ai-fuel, ox_fuel, LegacyFuel...), o null cuando no hay ninguno en marcha.

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

GarajesCopy Anchor Link

garages pasa por la capa de garajes de ai-core, sea cual sea el script de garaje que funcione; cada script responde solo lo que expone. Sin equivalente en Lua.

garages.impoundCopy Anchor Link

Envía un vehículo al depósito, o abre el formulario de depósito del script de garaje para by.

Lado: Servidor · Espera: no

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

Devuelve true cuando el script de garaje lo aceptó. false cuando nada lo aceptó: elimina el vehículo tú mismo.

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

garages.storeCopy Anchor Link

Guarda un vehículo en un garaje.

Lado: Servidor · Espera: no

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

Devuelve true cuando se guardó, false cuando nada lo aceptó.

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

garages.openCopy Anchor Link

Abre el menú de garaje del script de garaje para un jugador.

Lado: Servidor · Espera: no

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

Devuelve true cuando se abrió, false cuando el script no tiene ese menú.

garages.open(source, "pillbox");

garages.storedCopy Anchor Link

Los vehículos de un jugador en garajes o en el depósito.

Lado: Servidor · Espera: sí (Promise)

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

Devuelve GaragedVehicle[] (plate, model, garage, impounded), o null cuando el script no puede saberlo o ai-core está detenido.

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

garages.providerCopy Anchor Link

Lado: Servidor · Espera: no

garages.provider(): string | null

Devuelve el script de garaje que responde, o null cuando no hay ninguno en marcha.

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