ai-vehicles pour les développeurs

ai-vehicles n’a que des exports serveur. Ils sont tous synchrones (pas de Promise, pas d’attente en Lua), sauf SpawnVehicle, qui répond via un callback. Les types sont dans @aicore-fivem/shared (vehicles.ts).

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

local vehicles = exports['ai-vehicles']

TypesCopy Anchor Link

VehicleOwnerCopy Anchor Link

À qui appartient un véhicule.

OwnedVehicleCopy Anchor Link

Ce que renvoient GetVehicle et GetVehicles.

Exports serveurCopy Anchor Link

CreateVehicleCopy Anchor Link

Enregistre un nouveau véhicule possédé et le gare. Utilisez-le quand un joueur reçoit un véhicule (un achat, une récompense, un cadeau d’administrateur). Il ne fait pas apparaître la voiture : sortez-la avec SpawnVehicle ou laissez le joueur la récupérer dans un garage.

Côté : serveur · Attend : non

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

{ id, plate } du nouveau véhicule. null quand owner n’est pas un propriétaire valide ou que model n’est pas un texte.

ExempleCopy Anchor Link

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

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

// Donne une Sultan au joueur, garée au garage 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

Trouve un véhicule possédé par son id ou sa plaque.

Côté : serveur · Attend : non

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

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Le OwnedVehicle, ou null quand aucun véhicule en mémoire n’a cet id ou cette plaque (y compris quand il appartient à un personnage hors ligne).

ExempleCopy Anchor Link

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

GetVehiclesCopy Anchor Link

Tous les véhicules d’un propriétaire.

Côté : serveur · Attend : non

GetVehicles(owner: VehicleOwner): OwnedVehicle[]

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Un tableau de OwnedVehicle. Vide pour un propriétaire invalide, un propriétaire sans véhicule, ou un personnage hors ligne.

ExempleCopy 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

Indique si une plaque appartient à un véhicule possédé en mémoire.

Côté : serveur · Attend : non

IsOwnedPlate(plate: string): boolean

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

RetourCopy Anchor Link

true quand un véhicule possédé a cette plaque. false pour une plaque inconnue, une valeur qui n’est pas un texte, ou un véhicule d’un personnage hors ligne.

GetVehicleIdByEntityCopy Anchor Link

L’id ai-vehicles d’un véhicule possédé apparu.

Côté : serveur · Attend : non

GetVehicleIdByEntity(entity: number): number | null

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

L’id du véhicule, ou null quand l’entité n’est pas un véhicule possédé apparu par ai-vehicles.

GetEntityCopy Anchor Link

L’entité d’un véhicule possédé apparu.

Côté : serveur · Attend : non

GetEntity(id: number): number | null

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

RetourCopy Anchor Link

Le handle d’entité serveur, ou null quand le véhicule n’est pas sorti ou que son entité n’existe plus.

GetPlateOwnersCopy Anchor Link

Chaque véhicule possédé en mémoire sous la forme [plate, ownerType, ownerId]. Un script qui doit vérifier beaucoup de plaques (un système de clés) le lit une fois à son démarrage, puis suit l’event ai-vehicles:owners, au lieu d’appeler un export à chaque vérification.

Côté : serveur · Attend : non

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

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

RetourCopy Anchor Link

Un tableau de triplets. Vide quand aucun véhicule n’est en mémoire.

SaveVehicleCopy Anchor Link

Enregistre l’état et l’apparence d’un véhicule : carburant, dégâts, état, garage, et props (couleurs, extras, saleté). Le tuning enregistré (mods, neon) ne change jamais ici, donc une apparence lue depuis le client d’un joueur ne peut pas enregistrer le travail d’un menu de modifications. Utilisez SaveTuning pour le tuning.

Côté : serveur · Attend : non

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

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

ParamètresCopy Anchor Link

changeCopy Anchor Link

RetourCopy Anchor Link

Rien. Un id inconnu ne fait rien.

ExempleCopy Anchor Link

// Une réparation est terminée : moteur et carrosserie au maximum.
vehicles.SaveVehicle(vehicleId, { engine: 1000, body: 1000 });

SaveTuningCopy Anchor Link

Enregistre les props complètes, tuning compris (mods, neon). Réservé aux ateliers de tuning : l’atelier de tuning propre à AI Core, ai-mechanic, est le seul script ai-* qui l’appelle.

Côté : serveur · Attend : non

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

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

RetourCopy Anchor Link

Rien. Les props invalides sont ignorées. La plaque contenue dans les props est toujours remplacée par celle du véhicule.

StoreVehicleCopy Anchor Link

Gare un véhicule : supprime son entité s’il est sorti et règle son état et son garage.

Côté : serveur · Attend : non

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

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Rien. Il n’enregistre pas l’état du véhicule au préalable : appelez SaveVehicle avant lui quand les dégâts et le carburant doivent être conservés. Pour garer via le script de garage que fait tourner le serveur, quel qu’il soit, utilisez plutôt le garages.store de la lib.

SetOwnerCopy Anchor Link

Donne un véhicule à un autre propriétaire (une vente entre joueurs, une voiture placée dans une flotte de métier).

Côté : serveur · Attend : non

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

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

RetourCopy Anchor Link

Rien. Un propriétaire invalide ou un id inconnu ne fait rien. Les clés de l’ancien propriétaire ne sont pas retirées : retirez-les via le vehicleKeys.remove de la lib si nécessaire.

ExempleCopy Anchor Link

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

DeleteVehicleCopy Anchor Link

Supprime définitivement un véhicule possédé : son entité s’il est sorti, et sa ligne en base de données.

Côté : serveur · Attend : non

DeleteVehicle(id: number): void

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

RetourCopy Anchor Link

Rien.

SpawnVehicleCopy Anchor Link

Crée l’entité d’un véhicule possédé dans le monde avec son apparence, sa plaque, son carburant et ses state bags, et donne les clés à asker via le système de clés actif. L’état du véhicule devient out.

Côté : serveur · Attend : non (le résultat arrive dans 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)

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Rien. cb reçoit le network id, ou null quand le véhicule n’existe pas, est déjà sorti, est en train d’apparaître, ou que le jeu n’a pas pu le créer.

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

EventsCopy Anchor Link

ai-vehicles:ownersCopy Anchor Link

Se déclenche quand des véhicules entrent dans la mémoire d’ai-vehicles ou changent de propriétaire, et quand des plaques quittent la mémoire. Un lot par tick serveur. Lisez GetPlateOwners une fois au démarrage, puis appliquez ces lots pour garder une copie plaque-propriétaire. Le nom est VEHICLES_EVENTS.owners dans @aicore-fivem/shared.

Côté : serveur (event local, non envoyé aux clients)

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 les règle sur chaque véhicule possédé qu’il fait apparaître. Les noms sont dans 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 fait un provide de qbx_vehicles, donc ces appels l’atteignent. Les formes suivent Qbox : state vaut 0 sorti, 1 garage, 2 fourrière.

GetPlayerVehicle renvoie les props dans la forme VehicleProps d’AI Core, pas celle d’ox_lib. depotPrice vaut toujours 0.