ai-vehicles для разработчиков

У ai-vehicles только серверные экспорты. Все они синхронные (без Promise, без ожидания в Lua), кроме SpawnVehicle, который отвечает через колбэк. Типы находятся в @aicore-fivem/shared (vehicles.ts).

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

local vehicles = exports['ai-vehicles']

ТипыCopy Anchor Link

VehicleOwnerCopy Anchor Link

Кому принадлежит транспорт.

OwnedVehicleCopy Anchor Link

Что возвращают GetVehicle и GetVehicles.

Серверные экспортыCopy Anchor Link

CreateVehicleCopy Anchor Link

Регистрирует новый личный транспорт и ставит его в гараж. Используйте, когда игрок получает транспорт (покупка, награда, подарок администратора). Машину не создаёт: выведите её через SpawnVehicle или позвольте игроку забрать её в гараже.

Сторона: сервер · Ожидание: нет

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 } или nil

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

{ id, plate } нового транспорта. null, если owner не является корректным владельцем или model не текст.

ПримерCopy Anchor Link

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

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

// Даёт игроку Sultan, поставленный в гараж 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

Находит один личный транспорт по id или номеру.

Сторона: сервер · Ожидание: нет

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

local vehicle = exports['ai-vehicles']:GetVehicle(ref) -- таблица или nil

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

OwnedVehicle или null, если ни у одного транспорта в памяти нет такого id или номера (в том числе если он принадлежит персонажу офлайн).

ПримерCopy Anchor Link

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

GetVehiclesCopy Anchor Link

Весь транспорт одного владельца.

Сторона: сервер · Ожидание: нет

GetVehicles(owner: VehicleOwner): OwnedVehicle[]

local list = exports['ai-vehicles']:GetVehicles(owner) -- массив

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Массив OwnedVehicle. Пустой для некорректного владельца, владельца без транспорта или персонажа офлайн.

ПримерCopy 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

Принадлежит ли номер личному транспорту в памяти.

Сторона: сервер · Ожидание: нет

IsOwnedPlate(plate: string): boolean

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

ВозвращаетCopy Anchor Link

true, если у личного транспорта есть этот номер. false для неизвестного номера, не текстового значения или транспорта персонажа офлайн.

GetVehicleIdByEntityCopy Anchor Link

Id в ai-vehicles для созданного личного транспорта.

Сторона: сервер · Ожидание: нет

GetVehicleIdByEntity(entity: number): number | null

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Id транспорта или null, если сущность не является личным транспортом, созданным ai-vehicles.

GetEntityCopy Anchor Link

Сущность созданного личного транспорта.

Сторона: сервер · Ожидание: нет

GetEntity(id: number): number | null

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

ВозвращаетCopy Anchor Link

Хэндл серверной сущности или null, если транспорт не снаружи или его сущность больше не существует.

GetPlateOwnersCopy Anchor Link

Весь личный транспорт в памяти в виде [plate, ownerType, ownerId]. Скрипт, которому нужно проверять много номеров (система ключей), читает это один раз при старте, а затем следит за событием ai-vehicles:owners, вместо того чтобы вызывать экспорт при каждой проверке.

Сторона: сервер · Ожидание: нет

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

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

ВозвращаетCopy Anchor Link

Массив троек. Пустой, если в памяти нет транспорта.

SaveVehicleCopy Anchor Link

Сохраняет состояние и вид транспорта: топливо, повреждения, состояние, гараж и props (цвета, дополнительные детали, грязь). Сохранённый тюнинг (mods, neon) здесь никогда не меняется, поэтому вид, прочитанный с клиента игрока, не может сохранить работу мод-меню. Для тюнинга используйте SaveTuning.

Сторона: сервер · Ожидание: нет

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

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

ПараметрыCopy Anchor Link

changeCopy Anchor Link

ВозвращаетCopy Anchor Link

Ничего. Неизвестный id ничего не делает.

ПримерCopy Anchor Link

// Ремонт закончен: полный двигатель и кузов.
vehicles.SaveVehicle(vehicleId, { engine: 1000, body: 1000 });

SaveTuningCopy Anchor Link

Сохраняет полные props, включая тюнинг (mods, neon). Предназначен только для тюнинг-мастерских: собственная тюнинг-мастерская AI Core, ai-mechanic, является единственным скриптом ai-*, который его вызывает.

Сторона: сервер · Ожидание: нет

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

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

ВозвращаетCopy Anchor Link

Ничего. Некорректные props игнорируются. Номер внутри props всегда заменяется собственным номером транспорта.

StoreVehicleCopy Anchor Link

Ставит транспорт в гараж: удаляет его сущность, если он снаружи, и выставляет его состояние и гараж.

Сторона: сервер · Ожидание: нет

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

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Ничего. Сначала состояние не сохраняется: вызовите перед ним SaveVehicle, если нужно сохранить повреждения и топливо. Чтобы ставить в гараж через любой запущенный скрипт гаражей, используйте вместо этого garages.store из lib.

SetOwnerCopy Anchor Link

Передаёт транспорт другому владельцу (продажа между игроками, машина, перемещённая в автопарк работы).

Сторона: сервер · Ожидание: нет

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

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

ВозвращаетCopy Anchor Link

Ничего. Некорректный владелец или неизвестный id ничего не делает. Ключи старого владельца не забираются: при необходимости уберите их через vehicleKeys.remove из lib.

ПримерCopy Anchor Link

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

DeleteVehicleCopy Anchor Link

Удаляет личный транспорт навсегда: его сущность, если он снаружи, и его строку в базе данных.

Сторона: сервер · Ожидание: нет

DeleteVehicle(id: number): void

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

ВозвращаетCopy Anchor Link

Ничего.

SpawnVehicleCopy Anchor Link

Создаёт сущность личного транспорта в мире с его видом, номером, топливом и state bags и выдаёт ключи asker через активную систему ключей. Состояние транспорта становится out.

Сторона: сервер · Ожидание: нет (результат приходит в 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)

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Ничего. cb получает network id или null, если транспорт не существует, уже снаружи, прямо сейчас создаётся или игра не смогла его создать.

ПримерCopy 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`);
  });
}

СобытияCopy Anchor Link

ai-vehicles:ownersCopy Anchor Link

Срабатывает, когда транспорт попадает в память ai-vehicles или меняет владельца, и когда номера уходят из памяти. Один пакет за серверный тик. Прочитайте GetPlateOwners один раз при старте, затем применяйте эти пакеты, чтобы держать копию «номер – владелец». Имя VEHICLES_EVENTS.owners в @aicore-fivem/shared.

Сторона: сервер (локальное событие, не отправляется клиентам)

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 выставляет их на каждом личном транспорте, который создаёт. Имена находятся в 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 делает provide для qbx_vehicles, поэтому эти вызовы доходят до него. Форматы следуют Qbox: state равно 0 снаружи, 1 гараж, 2 штрафстоянка.

GetPlayerVehicle возвращает props в формате VehicleProps AI Core, а не ox_lib. depotPrice всегда 0.