AI Core
Véhiculesai-vehicles

ai-vehicles pour les développeurs

Les exports serveur, les state bags et les events d’ai-vehicles, et l’API qbx_vehicles à laquelle il répond.

ai-vehicles n’a que des exports serveur. La plupart sont synchrones (pas de Promise, pas d’attente en Lua) ; ceux qui peuvent lire la base - FindVehicle, GetVehiclesOf, SetPlate, DeleteVehicleByPlate, AdoptVehicle - et SpawnVehicle répondent via un callback. Les types sont dans @aicore8/shared (vehicles.ts).

TypeScript
import { resourceExport } from "@aicore8/lib/server";
const vehicles = resourceExport("ai-vehicles");
Lua
local vehicles = exports['ai-vehicles']

Pour donner, retirer ou vérifier des clés, garer un véhicule dans un garage ou lire le carburant, utilisez les couches de la lib (vehicleKeys, garages, fuel) : elles fonctionnent avec le script de clés, de garage ou de carburant que fait tourner le serveur, quel qu’il soit. N’appelez directement ai-vehicles que pour la propriété elle-même.

Types

VehicleOwner

À qui appartient un véhicule.

Prop

Type

OwnedVehicle

Ce que renvoient GetVehicle et GetVehicles.

Prop

Type

DeleteByPlateResult

Ce que répond DeleteVehicleByPlate.

Prop

Type

AdoptVehicleResult

Ce que répond AdoptVehicle.

Prop

Type

Exports serveur

CreateVehicle

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

Signature
CreateVehicle(owner: VehicleOwner, model: string, garage: string | null, props?: VehicleProps): { id: number; plate: string } | null
Lua
local created = exports['ai-vehicles']:CreateVehicle(owner, model, garage, props) -- { id = number, plate = string } ou nil

Paramètres

Prop

Type

Retour

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

Exemple

import { resourceExport } from "@aicore8/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;
}

GetVehicle

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

Côté : serveur · Attend : non

Signature
GetVehicle(ref: number | string): OwnedVehicle | null
Lua
local vehicle = exports['ai-vehicles']:GetVehicle(ref) -- table ou nil

Paramètres

Prop

Type

Retour

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).

Exemple

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

GetVehicles

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

Côté : serveur · Attend : non

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

Paramètres

Prop

Type

Retour

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

Exemple

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

IsOwnedPlate

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

Côté : serveur · Attend : non

Signature
IsOwnedPlate(plate: string): boolean
Lua
local owned = exports['ai-vehicles']:IsOwnedPlate(plate)

Retour

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.

GetVehicleIdByEntity

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

Côté : serveur · Attend : non

Signature
GetVehicleIdByEntity(entity: number): number | null
Lua
local id = exports['ai-vehicles']:GetVehicleIdByEntity(entity)

Paramètres

Prop

Type

Retour

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

GetEntity

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

Côté : serveur · Attend : non

Signature
GetEntity(id: number): number | null
Lua
local entity = exports['ai-vehicles']:GetEntity(id)

Retour

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

GetPlateOwners

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

Signature
GetPlateOwners(): Array<[plate: string, type: VehicleOwnerType, id: string]>
Lua
local owners = exports['ai-vehicles']:GetPlateOwners() -- { { plate, type, id }, ... }

Retour

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

FindVehicle

Un véhicule possédé par sa plaque exacte, même un dont le propriétaire n'est pas en ligne : ai-vehicles répond depuis la mémoire quand il tient le véhicule, et lit la base quand il ne l'a pas. C'est la recherche pour une plaque qu'un joueur a tapée - une requête MDT, une fourrière, une barrière qui vérifie à qui est la voiture devant elle.

Côté : Serveur · Attend : non (la réponse arrive dans done)

Signature
FindVehicle(plate: string, done: (vehicle: OwnedVehicle | null) => void, shape?: "framework"): void
Lua
exports['ai-vehicles']:FindVehicle(plate, function(vehicle) end, shape)

Paramètres

Prop

Type

Retour

Rien. done reçoit un OwnedVehicle ou null.

Exemple

import { resourceExport } from "@aicore8/lib/server";

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

/** À qui appartient la plaque, en ligne ou non. */
export function ownerOf(plate: string): Promise<string | null> {
  return new Promise((resolve) =>
    vehicles.FindVehicle(plate, (vehicle) => resolve(vehicle?.owner.id ?? null)),
  );
}

Il n'existe pas de recherche sur toutes les plaques stockées. Pour les véhicules d'un propriétaire, utilisez GetVehiclesOf ; pour les plaques en mémoire, GetPlateOwners.

GetVehiclesOf

Tous les véhicules d'un propriétaire, y compris un personnage qui n'est pas en ligne. GetVehicles ne répond que pour les propriétaires qu'ai-vehicles tient en mémoire ; celui-ci lit la base quand il le faut.

Côté : Serveur · Attend : non (la réponse arrive dans done)

Signature
GetVehiclesOf(owner: VehicleOwner, done: (vehicles: OwnedVehicle[]) => void, shape?: "framework"): void
Lua
exports['ai-vehicles']:GetVehiclesOf(owner, function(vehicles) end, shape)

Paramètres

Prop

Type

Retour

Rien. done reçoit un tableau de OwnedVehicle.

Exemple

import { characters, resourceExport } from "@aicore8/lib/server";

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

/** La liste de garage d'un personnage, en ligne ou non. */
export async function garageOf(citizenid: string) {
  const charId = await characters.idOf(citizenid);
  if (charId === null) return [];
  return new Promise((resolve) =>
    vehicles.GetVehiclesOf({ type: "character", id: String(charId) }, resolve),
  );
}

SetPlate

Une autre plaque pour un véhicule possédé : un changeur de plaque, ou un admin qui en corrige une. Si le véhicule est dehors, l'entité la reçoit aussi.

Côté : Serveur · Attend : non (la réponse arrive dans done)

Signature
SetPlate(id: number, plate: string, done?: (ok: boolean) => void): void
Lua
exports['ai-vehicles']:SetPlate(id, plate, function(ok) end)

Paramètres

Prop

Type

Retour

Rien. done(false) veut dire : la plaque appartient à un autre véhicule possédé, ressemble à une plaque générée, ou n'est pas 1 à 8 lettres et chiffres.

SaveVehicle

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

Signature
SaveVehicle(id: number, change: { props?: VehicleProps; fuel?: number; engine?: number; body?: number; state?: VehicleState; garage?: string | null }): void
Lua
exports['ai-vehicles']:SaveVehicle(id, change)

Paramètres

Prop

Type

change

Prop

Type

Retour

Rien. Un id inconnu ne fait rien.

Exemple

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

SaveTuning

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

Signature
SaveTuning(id: number, props: VehicleProps): void
Lua
exports['ai-vehicles']:SaveTuning(id, props)

Retour

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

Ne passez jamais des props venues directement du client d’un joueur sans les vérifier sur le serveur : tout ce que vous enregistrez ici devient désormais le tuning de la voiture.

StoreVehicle

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

Côté : serveur · Attend : non

Signature
StoreVehicle(id: number, garage: string | null, state?: VehicleState): void
Lua
exports['ai-vehicles']:StoreVehicle(id, garage, state)

Paramètres

Prop

Type

Retour

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.

SetOwner

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

Signature
SetOwner(id: number, owner: VehicleOwner): void
Lua
exports['ai-vehicles']:SetOwner(id, owner)

Retour

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.

Exemple

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

DeleteVehicle

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

Signature
DeleteVehicle(id: number): void
Lua
exports['ai-vehicles']:DeleteVehicle(id)

Retour

Rien.

C’est irréversible. Le véhicule, son apparence et son tuning disparaissent.

DeleteVehicleByPlate

Supprime un véhicule possédé par sa plaque, propriétaire en ligne ou non : sa ligne et toutes les entités du monde qui portent cette plaque.

Côté : Serveur · Attend : non (la réponse arrive dans done)

Signature
DeleteVehicleByPlate(plate: string, done?: (result: DeleteByPlateResult) => void): void
Lua
exports['ai-vehicles']:DeleteVehicleByPlate(plate, function(result) end)

Paramètres

Prop

Type

Retour

Rien. done reçoit un DeleteByPlateResult : { ok: true, id, entities } avec l'id supprimé et le nombre d'entités parties avec lui, ou { ok: false, error }.

Exemple

import { resourceExport } from "@aicore8/lib/server";

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

vehicles.DeleteVehicleByPlate(plate, (result) => {
  if (!result.ok) console.log(`${plate} non supprimée : ${result.error}`);
});

C'est irréversible, et cela ne demande pas si le véhicule est dehors : la voiture sous un joueur disparaît. Pour une commande d'admin, demandez confirmation d'abord.

AdoptVehicle

Transforme un véhicule déjà dans le monde en véhicule possédé : il passe en out, est suivi comme un véhicule qu'ai-vehicles a fait apparaître lui-même, et son propriétaire peut le garer. C'est ce que fait un /admincar d'administrateur.

Côté : Serveur · Attend : non (la réponse arrive dans done)

Signature
AdoptVehicle(owner: VehicleOwner, entity: number, model: string, props: unknown, done?: (result: AdoptVehicleResult) => void): void
Lua
exports['ai-vehicles']:AdoptVehicle(owner, entity, model, props, function(result) end)

Paramètres

Prop

Type

Retour

Rien. done reçoit un AdoptVehicleResult : { ok: true, id, plate }, ou { ok: false, error }. L'entité garde sa propre plaque quand c'est une plaque personnalisée valide (les règles de SetPlate) ; sinon elle reçoit la plaque générée.

Exemple

import { resourceExport, triggerClientCallback } from "@aicore8/lib/server";

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

/** Donne à l'admin la voiture dans laquelle il est assis. */
export async function adminCar(source: number, charId: number, entity: number) {
  const look = await triggerClientCallback<{ model: string; props: unknown }>("mycars:look", source);
  if (!look) return;
  vehicles.AdoptVehicle({ type: "character", id: String(charId) }, entity, look.model, look.props, (result) => {
    if (!result.ok) console.log(`non adopté : ${result.error}`);
  });
}

SpawnVehicle

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)

Signature
SpawnVehicle(id: number, at: { x: number; y: number; z: number; heading: number }, asker: number, cb: (netId: number | null) => void, purpose?: KeyPurpose, setup?: VehicleSetup): void
Lua
exports['ai-vehicles']:SpawnVehicle(id, at, asker, function(netId) end, purpose, setup)

Paramètres

Prop

Type

Retour

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.

Exemple

import { resourceExport } from "@aicore8/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`);
  });
}

Un véhicule déjà sorti est refusé (cb(null)). Si son entité disparaît plus tard pendant qu’il est sorti, il passe à l’état fourrière.

Events

ai-vehicles:owners

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 @aicore8/shared.

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

Prop

Type

import { resourceExport } from "@aicore8/lib/server";
import { VEHICLES_EVENTS } from "@aicore8/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 bags

ai-vehicles les règle sur chaque véhicule possédé qu’il fait apparaître. Les noms sont dans VEHICLE_BAGS (@aicore8/shared).

BagTypeSignification
ai:ownedtrueL’entité est un véhicule possédé.
ai:vidnumberSon id dans ai-vehicles.
ai:propsVehiclePropsL’apparence enregistrée. Le client d’ai-core propriétaire de l’entité l’applique.
ai:setupVehicleSetupUne apparence d’apparition pour un véhicule sans props, appliquée une fois.
fuelnumberCarburant 0-100. Le script de carburant le gère ensuite.
Lua (client)
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
if Entity(vehicle).state['ai:owned'] then
  print('owned vehicle', Entity(vehicle).state['ai:vid'])
end

qbx_vehicles API

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.

ExportCe qu’il fait
GetPlayerVehicles(filters: { citizenid?, garage? })Les véhicules d’un personnage en ligne, éventuellement d’un seul garage. Renvoie { id, citizenid, modelName, garage, state, depotPrice, props }[].
GetPlayerVehicle(id: number)Un véhicule dans la même forme, ou nil.
CreatePlayerVehicle(request: { model, citizenid, garage?, props? })Crée un véhicule pour un personnage en ligne. Renvoie l’id, ou nil, { code, message } (bad_request, not_found).
SetPlayerVehicleOwner(id: number, citizenid: string)Nouveau propriétaire (en ligne). true quand cela a fonctionné.
DeletePlayerVehicles(idType: "plate" | "vehicleId", idValue)Supprime un véhicule. true quand il a été trouvé.
GetVehicleIdByPlate(plate: string)L’id, ou nil.
DoesPlayerVehiclePlateExist(plate: string)true quand la plaque est possédée.
SaveVehicle(entity: number, options: { props?, state?, garage? })Enregistre un véhicule apparu, tuning compris. Accepte les props d’AI Core ou la forme de props d’ox_lib / qb-core. Les props d’un autre modèle que l’entité sont refusées (l’état et le garage sont quand même enregistrés).

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

Sur cette page