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).
import { resourceExport } from "@aicore8/lib/server";
const vehicles = resourceExport("ai-vehicles");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
CreateVehicle(owner: VehicleOwner, model: string, garage: string | null, props?: VehicleProps): { id: number; plate: string } | nulllocal created = exports['ai-vehicles']:CreateVehicle(owner, model, garage, props) -- { id = number, plate = string } ou nilParamè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
GetVehicle(ref: number | string): OwnedVehicle | nulllocal vehicle = exports['ai-vehicles']:GetVehicle(ref) -- table ou nilParamè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
GetVehicles(owner: VehicleOwner): OwnedVehicle[]local list = exports['ai-vehicles']:GetVehicles(owner) -- tableauParamè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
IsOwnedPlate(plate: string): booleanlocal 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
GetVehicleIdByEntity(entity: number): number | nulllocal 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
GetEntity(id: number): number | nulllocal 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
GetPlateOwners(): Array<[plate: string, type: VehicleOwnerType, id: string]>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)
FindVehicle(plate: string, done: (vehicle: OwnedVehicle | null) => void, shape?: "framework"): voidexports['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)
GetVehiclesOf(owner: VehicleOwner, done: (vehicles: OwnedVehicle[]) => void, shape?: "framework"): voidexports['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)
SetPlate(id: number, plate: string, done?: (ok: boolean) => void): voidexports['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
SaveVehicle(id: number, change: { props?: VehicleProps; fuel?: number; engine?: number; body?: number; state?: VehicleState; garage?: string | null }): voidexports['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
SaveTuning(id: number, props: VehicleProps): voidexports['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
StoreVehicle(id: number, garage: string | null, state?: VehicleState): voidexports['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
SetOwner(id: number, owner: VehicleOwner): voidexports['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
DeleteVehicle(id: number): voidexports['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)
DeleteVehicleByPlate(plate: string, done?: (result: DeleteByPlateResult) => void): voidexports['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)
AdoptVehicle(owner: VehicleOwner, entity: number, model: string, props: unknown, done?: (result: AdoptVehicleResult) => void): voidexports['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)
SpawnVehicle(id: number, at: { x: number; y: number; z: number; heading: number }, asker: number, cb: (netId: number | null) => void, purpose?: KeyPurpose, setup?: VehicleSetup): voidexports['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).
| Bag | Type | Signification |
|---|---|---|
ai:owned | true | L’entité est un véhicule possédé. |
ai:vid | number | Son id dans ai-vehicles. |
ai:props | VehicleProps | L’apparence enregistrée. Le client d’ai-core propriétaire de l’entité l’applique. |
ai:setup | VehicleSetup | Une apparence d’apparition pour un véhicule sans props, appliquée une fois. |
fuel | number | Carburant 0-100. Le script de carburant le gère ensuite. |
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
if Entity(vehicle).state['ai:owned'] then
print('owned vehicle', Entity(vehicle).state['ai:vid'])
endqbx_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.
| Export | Ce 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.
ai-vehicles
Les véhicules possédés par les personnages, les métiers et les gangs. Le stockage sur lequel reposent chaque script de garage, de concession, de clés et de carburant.
ai-vehiclekeys
Clés de véhicule, verrouillage avec une télécommande, crochetage et démarrage aux fils, et blocage du moteur sans clé.