ai-vehicles dla deweloperów
Eksporty serwera, state bagi i zdarzenia ai-vehicles oraz API qbx_vehicles, na które odpowiada.
ai-vehicles ma tylko eksporty serwera. Większość jest synchroniczna (bez Promise, bez czekania w Lua); te, które mogą czytać bazę - FindVehicle, GetVehiclesOf, SetPlate, DeleteVehicleByPlate, AdoptVehicle - oraz SpawnVehicle odpowiadają przez callback. Typy są w @aicore8/shared (vehicles.ts).
import { resourceExport } from "@aicore8/lib/server";
const vehicles = resourceExport("ai-vehicles");local vehicles = exports['ai-vehicles']Aby dawać, zabierać lub sprawdzać klucze, zaparkować pojazd w garażu lub odczytać paliwo, używaj warstw biblioteki (vehicleKeys, garages, fuel): działają z każdym skryptem kluczy, garaży lub paliwa, którego używa serwer. Wywołuj ai-vehicles bezpośrednio tylko w sprawie samej własności.
Typy
VehicleOwner
Kto jest właścicielem pojazdu.
Prop
Type
OwnedVehicle
Co zwracają GetVehicle i GetVehicles.
Prop
Type
DeleteByPlateResult
Co odpowiada DeleteVehicleByPlate.
Prop
Type
AdoptVehicleResult
Co odpowiada AdoptVehicle.
Prop
Type
Eksporty serwera
CreateVehicle
Rejestruje nowy posiadany pojazd i go parkuje. Używaj, gdy gracz dostaje pojazd (zakup, nagroda, prezent od administratora). Nie tworzy auta w świecie: wyjmij je przez SpawnVehicle albo pozwól graczowi odebrać je w garażu.
Strona: serwer · Czeka: nie
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 } albo nilParametry
Prop
Type
Zwraca
{ id, plate } nowego pojazdu. null, gdy owner nie jest prawidłowym właścicielem albo model nie jest tekstem.
Przykład
import { resourceExport } from "@aicore8/lib/server";
const core = resourceExport("ai-core");
const vehicles = resourceExport("ai-vehicles");
// Daje graczowi Sultana zaparkowanego w garażu 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
Znajduje jeden posiadany pojazd według ID lub tablicy.
Strona: serwer · Czeka: nie
GetVehicle(ref: number | string): OwnedVehicle | nulllocal vehicle = exports['ai-vehicles']:GetVehicle(ref) -- tabela lub nilParametry
Prop
Type
Zwraca
OwnedVehicle albo null, gdy żaden pojazd w pamięci nie ma tego ID lub tablicy (także gdy należy do postaci offline).
Przykład
const vehicle = vehicles.GetVehicle("AI00001A");
if (vehicle) console.log(vehicle.model, vehicle.state, vehicle.fuel);GetVehicles
Każdy pojazd jednego właściciela.
Strona: serwer · Czeka: nie
GetVehicles(owner: VehicleOwner): OwnedVehicle[]local list = exports['ai-vehicles']:GetVehicles(owner) -- tablicaParametry
Prop
Type
Zwraca
Tablica OwnedVehicle. Pusta dla nieprawidłowego właściciela, właściciela bez pojazdów lub postaci offline.
Przykład
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
Czy tablica należy do posiadanego pojazdu w pamięci.
Strona: serwer · Czeka: nie
IsOwnedPlate(plate: string): booleanlocal owned = exports['ai-vehicles']:IsOwnedPlate(plate)Zwraca
true, gdy posiadany pojazd ma tę tablicę. false dla nieznanej tablicy, wartości, która nie jest tekstem, lub pojazdu postaci offline.
GetVehicleIdByEntity
ID w ai-vehicles utworzonego w świecie posiadanego pojazdu.
Strona: serwer · Czeka: nie
GetVehicleIdByEntity(entity: number): number | nulllocal id = exports['ai-vehicles']:GetVehicleIdByEntity(entity)Parametry
Prop
Type
Zwraca
ID pojazdu albo null, gdy encja nie jest posiadanym pojazdem utworzonym przez ai-vehicles.
GetEntity
Encja utworzonego w świecie posiadanego pojazdu.
Strona: serwer · Czeka: nie
GetEntity(id: number): number | nulllocal entity = exports['ai-vehicles']:GetEntity(id)Zwraca
Uchwyt encji po stronie serwera albo null, gdy pojazd nie jest na zewnątrz lub jego encja już nie istnieje.
GetPlateOwners
Każdy posiadany pojazd w pamięci jako [plate, ownerType, ownerId]. Skrypt, który musi sprawdzać wiele tablic (system kluczy), czyta to raz przy starcie, a potem śledzi zdarzenie ai-vehicles:owners, zamiast wywoływać eksport przy każdym sprawdzeniu.
Strona: serwer · Czeka: nie
GetPlateOwners(): Array<[plate: string, type: VehicleOwnerType, id: string]>local owners = exports['ai-vehicles']:GetPlateOwners() -- { { plate, type, id }, ... }Zwraca
Tablica trójek. Pusta, gdy w pamięci nie ma żadnego pojazdu.
FindVehicle
Jeden posiadany pojazd po dokładnej tablicy, także taki, którego właściciel nie jest online: ai-vehicles odpowiada z pamięci, gdy trzyma pojazd, a gdy nie - czyta bazę. To wyszukiwanie dla tablicy wpisanej przez gracza: zapytanie w MDT, parking depozytowy, brama sprawdzająca, czyje jest auto przed nią.
Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done)
FindVehicle(plate: string, done: (vehicle: OwnedVehicle | null) => void, shape?: "framework"): voidexports['ai-vehicles']:FindVehicle(plate, function(vehicle) end, shape)Parametry
Prop
Type
Zwraca
Nic. done dostaje OwnedVehicle albo null.
Przykład
import { resourceExport } from "@aicore8/lib/server";
const vehicles = resourceExport("ai-vehicles");
/** Czyja jest tablica, online czy nie. */
export function ownerOf(plate: string): Promise<string | null> {
return new Promise((resolve) =>
vehicles.FindVehicle(plate, (vehicle) => resolve(vehicle?.owner.id ?? null)),
);
}Nie ma wyszukiwania po wszystkich zapisanych tablicach. Po pojazdy jednego właściciela weź GetVehiclesOf, po tablice w pamięci - GetPlateOwners.
GetVehiclesOf
Wszystkie pojazdy jednego właściciela, także postaci, która nie jest online. GetVehicles odpowiada tylko za właścicieli, których ai-vehicles trzyma w pamięci; ten czyta bazę, gdy musi.
Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done)
GetVehiclesOf(owner: VehicleOwner, done: (vehicles: OwnedVehicle[]) => void, shape?: "framework"): voidexports['ai-vehicles']:GetVehiclesOf(owner, function(vehicles) end, shape)Parametry
Prop
Type
Zwraca
Nic. done dostaje tablicę OwnedVehicle.
Przykład
import { characters, resourceExport } from "@aicore8/lib/server";
const vehicles = resourceExport("ai-vehicles");
/** Lista garażowa postaci, online czy nie. */
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
Inna tablica dla posiadanego pojazdu: zmieniacz tablic albo administrator, który poprawia jedną. Gdy pojazd jest w świecie, encja też ją dostaje.
Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done)
SetPlate(id: number, plate: string, done?: (ok: boolean) => void): voidexports['ai-vehicles']:SetPlate(id, plate, function(ok) end)Parametry
Prop
Type
Zwraca
Nic. done(false) znaczy, że tablica należy do innego posiadanego pojazdu, wygląda jak wygenerowana albo nie jest 1-8 liter i cyfr.
SaveVehicle
Zapisuje stan i wygląd pojazdu: paliwo, uszkodzenia, stan, garaż i props (kolory, dodatki, brud). Zapisany tuning (mods, neon) nigdy się tu nie zmienia, więc wygląd odczytany z klienta gracza nie może zapisać pracy menu modów. Do tuningu używaj SaveTuning.
Strona: serwer · Czeka: nie
SaveVehicle(id: number, change: { props?: VehicleProps; fuel?: number; engine?: number; body?: number; state?: VehicleState; garage?: string | null }): voidexports['ai-vehicles']:SaveVehicle(id, change)Parametry
Prop
Type
change
Prop
Type
Zwraca
Nic. Nieznane ID nic nie robi.
Przykład
// Naprawa zakończona: pełny silnik i karoseria.
vehicles.SaveVehicle(vehicleId, { engine: 1000, body: 1000 });SaveTuning
Zapisuje pełne props, łącznie z tuningiem (mods, neon). Przeznaczony tylko dla warsztatów tuningowych: własny warsztat tuningowy AI Core, ai-mechanic, to jedyny skrypt ai-*, który go wywołuje.
Strona: serwer · Czeka: nie
SaveTuning(id: number, props: VehicleProps): voidexports['ai-vehicles']:SaveTuning(id, props)Zwraca
Nic. Nieprawidłowe props są ignorowane. Tablica w props jest zawsze zastępowana własną tablicą pojazdu.
Nigdy nie przekazuj props, które przyszły prosto z klienta gracza, bez sprawdzenia ich na serwerze: wszystko, co tu zapiszesz, jest od teraz tuningiem auta.
StoreVehicle
Parkuje pojazd: usuwa jego encję, jeśli jest na zewnątrz, i ustawia jego stan i garaż.
Strona: serwer · Czeka: nie
StoreVehicle(id: number, garage: string | null, state?: VehicleState): voidexports['ai-vehicles']:StoreVehicle(id, garage, state)Parametry
Prop
Type
Zwraca
Nic. Nie zapisuje najpierw stanu: wywołaj przed nim SaveVehicle, gdy uszkodzenia i paliwo mają zostać zachowane. Aby zaparkować przez dowolny skrypt garaży, którego używa serwer, użyj zamiast tego garages.store z biblioteki.
SetOwner
Daje pojazd innemu właścicielowi (sprzedaż między graczami, auto przeniesione do floty pracy).
Strona: serwer · Czeka: nie
SetOwner(id: number, owner: VehicleOwner): voidexports['ai-vehicles']:SetOwner(id, owner)Zwraca
Nic. Nieprawidłowy właściciel lub nieznane ID nic nie robią. Klucze starego właściciela nie są zabierane: w razie potrzeby usuń je przez vehicleKeys.remove z biblioteki.
Przykład
vehicles.SetOwner(vehicleId, { type: "job", id: "mechanic" });DeleteVehicle
Usuwa posiadany pojazd na zawsze: jego encję, jeśli jest na zewnątrz, i jego wiersz w bazie danych.
Strona: serwer · Czeka: nie
DeleteVehicle(id: number): voidexports['ai-vehicles']:DeleteVehicle(id)Zwraca
Nic.
Tego nie da się cofnąć. Pojazd, jego wygląd i tuning znikają.
DeleteVehicleByPlate
Usuwa posiadany pojazd po tablicy, niezależnie od tego, czy właściciel jest online: jego wiersz i każdą encję w świecie z tą tablicą.
Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done)
DeleteVehicleByPlate(plate: string, done?: (result: DeleteByPlateResult) => void): voidexports['ai-vehicles']:DeleteVehicleByPlate(plate, function(result) end)Parametry
Prop
Type
Zwraca
Nic. done dostaje DeleteByPlateResult: { ok: true, id, entities } z usuniętym id i liczbą encji, które poszły razem z nim, albo { ok: false, error }.
Przykład
import { resourceExport } from "@aicore8/lib/server";
const vehicles = resourceExport("ai-vehicles");
vehicles.DeleteVehicleByPlate(plate, (result) => {
if (!result.ok) console.log(`${plate} nie usunięto: ${result.error}`);
});Tego nie da się cofnąć i nie pyta, czy pojazd jest w świecie: auto pod graczem znika. Przy komendzie administratora najpierw poproś o potwierdzenie.
AdoptVehicle
Zamienia pojazd, który już stoi w świecie, w posiadany: wchodzi w stan out, jest śledzony jak ten, który ai-vehicles sam stworzył, a właściciel może go zaparkować. To właśnie robi administratorskie /admincar.
Strona: Serwer · Czeka: nie (odpowiedź przychodzi w 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)Parametry
Prop
Type
Zwraca
Nic. done dostaje AdoptVehicleResult: { ok: true, id, plate } albo { ok: false, error }. Encja zachowuje własną tablicę, gdy jest prawidłową tablicą własną (zasady SetPlate); w przeciwnym razie dostaje wygenerowaną.
Przykład
import { resourceExport, triggerClientCallback } from "@aicore8/lib/server";
const vehicles = resourceExport("ai-vehicles");
/** Daje administratorowi auto, w którym siedzi. */
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(`nie przyjęto: ${result.error}`);
});
}SpawnVehicle
Tworzy w świecie encję posiadanego pojazdu z jego wyglądem, tablicą, paliwem i state bagami oraz daje klucze graczowi asker przez aktywny system kluczy. Stan pojazdu zmienia się na out.
Strona: serwer · Czeka: nie (wynik przychodzi w 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)Parametry
Prop
Type
Zwraca
Nic. cb dostaje ID sieciowe albo null, gdy pojazd nie istnieje, jest już na zewnątrz, jest właśnie tworzony albo gra nie mogła go utworzyć.
Przykład
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`);
});
}Pojazd, który jest już na zewnątrz, jest odrzucany (cb(null)). Jeśli jego encja później zniknie, gdy jest na zewnątrz, przechodzi do stanu parkingu policyjnego.
Zdarzenia
ai-vehicles:owners
Wywoływane, gdy pojazdy trafiają do pamięci ai-vehicles lub zmieniają właściciela oraz gdy tablice opuszczają pamięć. Jedna paczka na tick serwera. Odczytaj GetPlateOwners raz przy starcie, a potem nakładaj te paczki, aby utrzymywać kopię przypisań tablica-właściciel. Nazwa to VEHICLES_EVENTS.owners w @aicore8/shared.
Strona: serwer (zdarzenie lokalne, niewysyłane do klientów)
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 bagi
ai-vehicles ustawia je na każdym posiadanym pojeździe, który tworzy w świecie. Nazwy są w VEHICLE_BAGS (@aicore8/shared).
| Bag | Typ | Znaczenie |
|---|---|---|
ai:owned | true | Encja jest posiadanym pojazdem. |
ai:vid | number | Jej ID w ai-vehicles. |
ai:props | VehicleProps | Zapisany wygląd. Nakłada go klient ai-core, który jest właścicielem encji. |
ai:setup | VehicleSetup | Wygląd spawnu dla pojazdu bez props, nakładany raz. |
fuel | number | Paliwo 0-100. Od tego momentu utrzymuje je skrypt paliwa. |
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
if Entity(vehicle).state['ai:owned'] then
print('owned vehicle', Entity(vehicle).state['ai:vid'])
endAPI qbx_vehicles
ai-vehicles robi provide dla qbx_vehicles, więc te wywołania do niego trafiają. Kształty są zgodne z Qbox: state to 0 na zewnątrz, 1 garaż, 2 parking policyjny.
| Eksport | Co robi |
|---|---|
GetPlayerVehicles(filters: { citizenid?, garage? }) | Pojazdy postaci online, opcjonalnie tylko z jednego garażu. Zwraca { id, citizenid, modelName, garage, state, depotPrice, props }[]. |
GetPlayerVehicle(id: number) | Jeden pojazd w tym samym kształcie albo nil. |
CreatePlayerVehicle(request: { model, citizenid, garage?, props? }) | Tworzy pojazd dla postaci online. Zwraca ID albo nil, { code, message } (bad_request, not_found). |
SetPlayerVehicleOwner(id: number, citizenid: string) | Nowy właściciel (online). true, gdy się udało. |
DeletePlayerVehicles(idType: "plate" | "vehicleId", idValue) | Usuwa jeden pojazd. true, gdy znaleziono. |
GetVehicleIdByPlate(plate: string) | ID albo nil. |
DoesPlayerVehiclePlateExist(plate: string) | true, gdy tablica jest posiadana. |
SaveVehicle(entity: number, options: { props?, state?, garage? }) | Zapisuje utworzony w świecie pojazd, łącznie z tuningiem. Przyjmuje props AI Core albo kształt props z ox_lib / qb-core. Props innego modelu niż encja są odrzucane (stan i garaż i tak się zapisują). |
GetPlayerVehicle zwraca props w kształcie VehicleProps z AI Core, a nie ox_lib. depotPrice zawsze wynosi 0.