AI Core
Fahrzeugeai-vehicles

ai-vehicles für Entwickler

Server-Exports, State Bags und Events von ai-vehicles und die API von qbx_vehicles, die es beantwortet.

ai-vehicles hat nur Server-Exports. Die meisten sind synchron (kein Promise, kein Warten in Lua); die, die die Datenbank lesen können - FindVehicle, GetVehiclesOf, SetPlate, DeleteVehicleByPlate, AdoptVehicle - und SpawnVehicle antworten über einen Callback. Die Typen stehen in @aicore8/shared (vehicles.ts).

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

Um Schlüssel zu geben, zu nehmen oder zu prüfen, ein Fahrzeug in einer Garage abzustellen oder den Sprit zu lesen, nutze die Layer der Lib (vehicleKeys, garages, fuel): Sie funktionieren mit dem Schlüssel-, Garagen- oder Spritskript, das der Server gerade nutzt. Rufe ai-vehicles nur für den Besitz selbst direkt auf.

Typen

VehicleOwner

Wem ein Fahrzeug gehört.

Prop

Type

OwnedVehicle

Was GetVehicle und GetVehicles zurückgeben.

Prop

Type

DeleteByPlateResult

Was DeleteVehicleByPlate antwortet.

Prop

Type

AdoptVehicleResult

Was AdoptVehicle antwortet.

Prop

Type

Server-Exports

CreateVehicle

Registriert ein neues Fahrzeug im Besitz und parkt es. Nutze es, wenn ein Spieler ein Fahrzeug bekommt (ein Kauf, eine Belohnung, ein Geschenk eines Admins). Es spawnt das Auto nicht: Hol es mit SpawnVehicle heraus oder lass den Spieler es an einer Garage abholen.

Seite: Server · Wartet: nein

Signatur
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 } oder nil

Parameter

Prop

Type

Rückgabewert

{ id, plate } des neuen Fahrzeugs. null, wenn owner kein gültiger Besitzer ist oder model kein Text ist.

Beispiel

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

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

// Gibt dem Spieler einen Sultan, geparkt in der 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

Findet ein Fahrzeug im Besitz per ID oder Kennzeichen.

Seite: Server · Wartet: nein

Signatur
GetVehicle(ref: number | string): OwnedVehicle | null
Lua
local vehicle = exports['ai-vehicles']:GetVehicle(ref) -- Tabelle oder nil

Parameter

Prop

Type

Rückgabewert

Das OwnedVehicle oder null, wenn kein Fahrzeug im Speicher diese ID oder dieses Kennzeichen hat (auch wenn es einem Offline-Charakter gehört).

Beispiel

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

GetVehicles

Jedes Fahrzeug eines Besitzers.

Seite: Server · Wartet: nein

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

Parameter

Prop

Type

Rückgabewert

Ein Array von OwnedVehicle. Leer bei einem ungültigen Besitzer, einem Besitzer ohne Fahrzeuge oder einem Offline-Charakter.

Beispiel

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

Ob ein Kennzeichen zu einem Fahrzeug im Besitz im Speicher gehört.

Seite: Server · Wartet: nein

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

Rückgabewert

true, wenn ein Fahrzeug im Besitz dieses Kennzeichen hat. false bei einem unbekannten Kennzeichen, einem Wert, der kein Text ist, oder einem Fahrzeug eines Offline-Charakters.

GetVehicleIdByEntity

Die ai-vehicles-ID eines gespawnten Fahrzeugs im Besitz.

Seite: Server · Wartet: nein

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

Parameter

Prop

Type

Rückgabewert

Die Fahrzeug-ID oder null, wenn die Entity kein von ai-vehicles gespawntes Fahrzeug im Besitz ist.

GetEntity

Die Entity eines gespawnten Fahrzeugs im Besitz.

Seite: Server · Wartet: nein

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

Rückgabewert

Das serverseitige Entity-Handle oder null, wenn das Fahrzeug nicht draußen ist oder seine Entity nicht mehr existiert.

GetPlateOwners

Jedes Fahrzeug im Besitz im Speicher als [plate, ownerType, ownerId]. Ein Skript, das viele Kennzeichen prüfen muss (ein Schlüsselsystem), liest dies einmal beim Start und folgt dann dem Event ai-vehicles:owners, statt für jede Prüfung einen Export aufzurufen.

Seite: Server · Wartet: nein

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

Rückgabewert

Ein Array von Tripeln. Leer, wenn kein Fahrzeug im Speicher ist.

FindVehicle

Ein Fahrzeug im Besitz über sein genaues Kennzeichen, auch eines, dessen Besitzer nicht online ist: ai-vehicles antwortet aus dem Speicher, wenn es das Fahrzeug hält, und liest sonst die Datenbank. Das ist die Suche für ein Kennzeichen, das ein Spieler eingetippt hat - eine MDT-Abfrage, ein Abschleppplatz, eine Schranke, die prüft, wem das Auto davor gehört.

Seite: Server · Wartet: nein (die Antwort kommt in done)

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

Parameter

Prop

Type

Rückgabe

Nichts. done bekommt ein OwnedVehicle oder null.

Beispiel

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

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

/** Wem das Kennzeichen gehört, online oder nicht. */
export function ownerOf(plate: string): Promise<string | null> {
  return new Promise((resolve) =>
    vehicles.FindVehicle(plate, (vehicle) => resolve(vehicle?.owner.id ?? null)),
  );
}

Es gibt keine Suche über alle gespeicherten Kennzeichen. Für die Fahrzeuge eines Besitzers nimm GetVehiclesOf, für die Kennzeichen im Speicher GetPlateOwners.

GetVehiclesOf

Jedes Fahrzeug eines Besitzers, auch eines Charakters, der nicht online ist. GetVehicles antwortet nur für Besitzer, die ai-vehicles im Speicher hält; dieses liest die Datenbank, wenn es muss.

Seite: Server · Wartet: nein (die Antwort kommt in done)

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

Parameter

Prop

Type

Rückgabe

Nichts. done bekommt ein Array von OwnedVehicle.

Beispiel

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

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

/** Die Garagenliste eines Charakters, online oder nicht. */
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

Ein anderes Kennzeichen für ein Fahrzeug im Besitz: ein Kennzeichenwechsler, oder ein Admin, der eines korrigiert. Ist das Fahrzeug draußen, bekommt die Entity es auch.

Seite: Server · Wartet: nein (die Antwort kommt in done)

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

Parameter

Prop

Type

Rückgabe

Nichts. done(false) heißt: das Kennzeichen gehört einem anderen Fahrzeug im Besitz, sieht wie ein generiertes aus, oder ist nicht 1-8 Buchstaben und Ziffern.

SaveVehicle

Speichert Zustand und Aussehen eines Fahrzeugs: Sprit, Schaden, Status, Garage und Props (Farben, Extras, Schmutz). Das gespeicherte Tuning (mods, neon) ändert sich hier nie, sodass ein vom Client eines Spielers gelesenes Aussehen nicht die Arbeit eines Mod-Menüs speichern kann. Nutze SaveTuning für Tuning.

Seite: Server · Wartet: nein

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

Parameter

Prop

Type

change

Prop

Type

Rückgabewert

Nichts. Eine unbekannte ID tut nichts.

Beispiel

// Ein Reparaturauftrag ist fertig: Motor und Karosserie voll.
vehicles.SaveVehicle(vehicleId, { engine: 1000, body: 1000 });

SaveTuning

Speichert vollständige Props, Tuning inklusive (mods, neon). Nur für Tuningwerkstätten gedacht: Die eigene Tuningwerkstatt von AI Core, ai-mechanic, ist das einzige ai-*-Skript, das es aufruft.

Seite: Server · Wartet: nein

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

Rückgabewert

Nichts. Ungültige Props werden ignoriert. Das Kennzeichen in den Props wird immer durch das eigene des Fahrzeugs ersetzt.

Übergib nie Props, die direkt vom Client eines Spielers kommen, ohne sie auf dem Server zu prüfen: Was du hier speicherst, ist ab jetzt das Tuning des Autos.

StoreVehicle

Parkt ein Fahrzeug: löscht seine Entity, wenn es draußen ist, und setzt seinen Status und seine Garage.

Seite: Server · Wartet: nein

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

Parameter

Prop

Type

Rückgabewert

Nichts. Es speichert den Zustand vorher nicht: Rufe davor SaveVehicle auf, wenn Schaden und Sprit erhalten bleiben sollen. Um über das Garagenskript zu parken, das der Server gerade nutzt, nutze stattdessen garages.store der Lib.

SetOwner

Gibt ein Fahrzeug einem anderen Besitzer (ein Verkauf zwischen Spielern, ein Auto, das in einen Job-Fuhrpark wechselt).

Seite: Server · Wartet: nein

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

Rückgabewert

Nichts. Ein ungültiger Besitzer oder eine unbekannte ID tut nichts. Die Schlüssel des alten Besitzers werden nicht genommen: Entferne sie bei Bedarf über vehicleKeys.remove der Lib.

Beispiel

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

DeleteVehicle

Löscht ein Fahrzeug im Besitz endgültig: seine Entity, wenn es draußen ist, und seine Datenbankzeile.

Seite: Server · Wartet: nein

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

Rückgabewert

Nichts.

Das lässt sich nicht rückgängig machen. Das Fahrzeug, sein Aussehen und sein Tuning sind weg.

DeleteVehicleByPlate

Löscht ein Fahrzeug im Besitz über sein Kennzeichen, Besitzer online oder nicht: seine Zeile und jede Entity in der Welt, die dieses Kennzeichen trägt.

Seite: Server · Wartet: nein (die Antwort kommt in done)

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

Parameter

Prop

Type

Rückgabe

Nichts. done bekommt ein DeleteByPlateResult: { ok: true, id, entities } mit der gelöschten ID und der Zahl der Entities, die mitgingen, oder { ok: false, error }.

Beispiel

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

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

vehicles.DeleteVehicleByPlate(plate, (result) => {
  if (!result.ok) console.log(`${plate} nicht gelöscht: ${result.error}`);
});

Das kann nicht zurückgenommen werden, und es fragt nicht, ob das Fahrzeug draußen ist: das Auto unter einem Spieler verschwindet. Für einen Admin-Befehl vorher nachfragen.

AdoptVehicle

Macht ein Fahrzeug, das schon in der Welt steht, zu einem Fahrzeug im Besitz: es wird out, wird verfolgt wie eines, das ai-vehicles selbst gespawnt hat, und sein Besitzer kann es parken. Das ist, was ein Admin-/admincar macht.

Seite: Server · Wartet: nein (die Antwort kommt in 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)

Parameter

Prop

Type

Rückgabe

Nichts. done bekommt ein AdoptVehicleResult: { ok: true, id, plate }, oder { ok: false, error }. Die Entity behält ihr eigenes Kennzeichen, wenn das ein gültiges eigenes ist (die Regeln von SetPlate); sonst bekommt sie das generierte.

Beispiel

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

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

/** Gibt dem Admin das Auto, in dem er sitzt. */
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(`nicht übernommen: ${result.error}`);
  });
}

SpawnVehicle

Erstellt die Entity eines Fahrzeugs im Besitz in der Welt mit Aussehen, Kennzeichen, Sprit und State Bags und gibt asker die Schlüssel über das aktive Schlüsselsystem. Der Status des Fahrzeugs wird out.

Seite: Server · Wartet: nein (das Ergebnis kommt in cb)

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

Parameter

Prop

Type

Rückgabewert

Nichts. cb bekommt die Network-ID oder null, wenn das Fahrzeug nicht existiert, schon draußen ist, gerade gespawnt wird oder das Spiel es nicht erstellen konnte.

Beispiel

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

Ein Fahrzeug, das schon draußen ist, wird abgelehnt (cb(null)). Verschwindet seine Entity später, während es draußen ist, wechselt es in den Status Abschlepphof.

Events

ai-vehicles:owners

Wird ausgelöst, wenn Fahrzeuge in den Speicher von ai-vehicles kommen oder den Besitzer wechseln und wenn Kennzeichen den Speicher verlassen. Ein Paket pro Server-Tick. Lies GetPlateOwners einmal beim Start und wende dann diese Pakete an, um eine Kopie von Kennzeichen zu Besitzer aktuell zu halten. Der Name ist VEHICLES_EVENTS.owners in @aicore8/shared.

Seite: Server (lokales Event, nicht an Clients gesendet)

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 setzt diese an jedem Fahrzeug im Besitz, das es spawnt. Die Namen stehen in VEHICLE_BAGS (@aicore8/shared).

BagTypBedeutung
ai:ownedtrueDie Entity ist ein Fahrzeug im Besitz.
ai:vidnumberSeine ID in ai-vehicles.
ai:propsVehiclePropsDas gespeicherte Aussehen. Der Client von ai-core, dem die Entity gehört, wendet es an.
ai:setupVehicleSetupEin Spawn-Aussehen für ein Fahrzeug ohne Props, einmal angewendet.
fuelnumberSprit 0-100. Das Spritskript verwaltet ihn von da an.
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 providet qbx_vehicles, sodass diese Aufrufe es erreichen. Die Strukturen folgen Qbox: state ist 0 draußen, 1 Garage, 2 Abschlepphof.

ExportWas er macht
GetPlayerVehicles(filters: { citizenid?, garage? })Fahrzeuge eines Online-Charakters, optional nur aus einer Garage. Gibt { id, citizenid, modelName, garage, state, depotPrice, props }[] zurück.
GetPlayerVehicle(id: number)Ein Fahrzeug in derselben Struktur oder nil.
CreatePlayerVehicle(request: { model, citizenid, garage?, props? })Erstellt ein Fahrzeug für einen Online-Charakter. Gibt die ID zurück oder nil, { code, message } (bad_request, not_found).
SetPlayerVehicleOwner(id: number, citizenid: string)Neuer Besitzer (online). true, wenn es geklappt hat.
DeletePlayerVehicles(idType: "plate" | "vehicleId", idValue)Löscht ein Fahrzeug. true, wenn gefunden.
GetVehicleIdByPlate(plate: string)Die ID oder nil.
DoesPlayerVehiclePlateExist(plate: string)true, wenn das Kennzeichen im Besitz ist.
SaveVehicle(entity: number, options: { props?, state?, garage? })Speichert ein gespawntes Fahrzeug, Tuning inklusive. Nimmt die Props von AI Core oder die Props-Struktur von ox_lib / qb-core. Props eines anderen Modells als die Entity werden abgelehnt (Status und Garage werden trotzdem gespeichert).

GetPlayerVehicle gibt Props in der Struktur VehicleProps von AI Core zurück, nicht in der von ox_lib. depotPrice ist immer 0.

Auf dieser Seite