Педы, блипы и пропы

То, что видит только этот клиент: NPC за прилавком, блипы на карте, проп в руке игрока, машина на витрине. Ничто из этого не является сетевым, поэтому никогда не конфликтует с блокировкой сущностей и ничего не стоит серверу. Точка уже сама создаёт свой NPC и блип (ped и blip у points.add); используйте эти классы для тех, у которых нет точки.

Локальные педыCopy Anchor Link

new LocalPedCopy Anchor Link

Пед, которого видит только этот клиент (продавец, NPC работы). Он создаётся, когда игрок подходит на distance к coords, и удаляется, когда игрок уходит, поэтому тысяча NPC на карте ничего не стоит, пока кто-нибудь не подойдёт. Он стоит замороженным, неуязвим и игнорирует события (выстрелы, толчки).

Сторона: Клиент · Ждёт: нет (модель загружается в фоне, когда игрок подходит ближе)

new LocalPed(options: LocalPedOptions)

local ped = aiLib.LocalPed.new(options)

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

LocalPedOptionsCopy Anchor Link

ЧленыCopy Anchor Link

ПримерCopy Anchor Link

import { LocalPed } from "@aicore-fivem/lib/client";

const guard = new LocalPed({
  model: "s_m_m_security_01",
  coords: { x: -1037.6, y: -2737.8, z: 20.2, heading: 330 },
  scenario: "WORLD_HUMAN_GUARD_STAND",
  distance: 80,
  onSpawn: (ped) => SetPedComponentVariation(ped, 0, 1, 0, 0),
});

// Позже, когда работа заканчивается:
guard.remove();

БлипыCopy Anchor Link

createBlipCopy Anchor Link

Создаёт один именованный блип на карте и возвращает его хэндл. Удаляете его вы сами через RemoveBlip(handle); для блипов, которые вы перестраиваете при изменении панели, используйте группу Blips.

Сторона: Клиент · Ждёт: нет

createBlip(options: BlipOptions): number

local blip = aiLib.Blips.create(options)

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

BlipOptionsCopy Anchor Link

Стиль блипа, выбранный в вашей админ-панели (виджет blip, читается через readBlipStyle), разворачивается прямо в эти опции: createBlip({ ...style, coords, label }).

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

number: хэндл блипа.

ПримерCopy Anchor Link

import { createBlip, createLocale } from "@aicore-fivem/lib/client";

const Locale = createLocale<typeof import("../../locales/en.json")>();

// Цель доставки с GPS-маршрутом; удаляется после доставки.
const target = createBlip({
  coords: { x: 1197.4, y: -3253.6, z: 7.1 },
  sprite: 478,
  color: 5,
  label: Locale("DELIVERY"),
  shortRange: false,
  route: true,
});
// ... при доставке:
RemoveBlip(target);

new BlipsCopy Anchor Link

Группа блипов по id: add заменяет блип с тем же id, а clear удаляет их все. Используйте одну группу на функцию.

Сторона: Клиент · Ждёт: нет

new Blips()

local blips = aiLib.Blips.new()

МетодыCopy Anchor Link

В Lua вызывайте методы через двоеточие: blips:add(id, options).

ПримерCopy Anchor Link

import { Blips, createLocale } from "@aicore-fivem/lib/client";

const Locale = createLocale<typeof import("../../locales/en.json")>();
const blips = new Blips();

const GARAGES = [
  { id: "legion", coords: { x: 215.8, y: -810.1, z: 30.7 } },
  { id: "airport", coords: { x: -796.5, y: -2023.3, z: 9.2 } },
];

for (const garage of GARAGES)
  blips.add(garage.id, { coords: garage.coords, sprite: 357, color: 3, label: Locale("GARAGE") });

// Гараж закрыли:
blips.remove("airport");

Пропы и удерживаемые анимацииCopy Anchor Link

attachPropCopy Anchor Link

Создаёт локальный проп и прикрепляет его к кости педа (телефон в руке, коробка перед собой). У пропа нет коллизии, если вы её не запросите.

Сторона: Клиент · Ждёт: да (Promise: сначала загружает модель)

attachProp(model: string | number, options: AttachPropOptions): Promise<number>

Lua-аналога нет: создайте объект и вызовите AttachEntityToEntity сами.

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

AttachPropOptionsCopy Anchor Link

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

Promise<number>: сущность пропа или 0, если модель не загрузилась или педа больше нет. Никогда не отклоняется.

ПримерCopy Anchor Link

import { attachProp, player } from "@aicore-fivem/lib/client";

export async function readNewspaper(): Promise<void> {
  const paper = await attachProp("prop_cliff_paper", {
    bone: 18905,
    offset: { x: 0.12, y: 0.03, z: 0.02 },
    rotation: { x: 10, y: 0, z: 0 },
  });
  const hold = player.holdAnim("amb@world_human_tourist_map@male@base", "base");
  setTimeout(() => {
    hold.stop();
    if (paper) DeleteEntity(paper);
  }, 10_000);
}

player.holdAnimCopy Anchor Link

Поддерживает проигрывание анимации, пока вы её не остановите. Когда её прерывает падение, толчок или ragdoll, она возвращается в течение полусекунды. Используйте для переноски, удержания телефона или рабочего цикла. Одно удержание на ресурс: новое заменяет старое.

Сторона: Клиент · Ждёт: нет

player.holdAnim(dict: string, clip: string, options?: HoldAnimOptions): { stop(): void }

Lua-аналога нет: проиграйте анимацию через aiLib.player.playAnim и проверяйте её задачей aiLib.every.

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

HoldAnimOptionsCopy Anchor Link

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

{ stop(): void }: вызовите stop(), чтобы завершить удержание и очистить задачи педа. Вызов stop() у уже заменённого удержания ничего не делает.

ПримерCopy Anchor Link

import { attachProp, cache, player } from "@aicore-fivem/lib/client";

export async function carryBox(): Promise<void> {
  const box = await attachProp("hei_prop_heist_box", {
    bone: 60309,
    offset: { x: 0.025, y: 0.08, z: 0.255 },
    rotation: { x: -145, y: 290, z: 0 },
  });
  // Заканчивается само, когда игрок садится в транспорт.
  player.holdAnim("anim@heists@box_carry@", "idle", {
    while: () => cache.vehicle === false,
  });
  setTimeout(() => box && DeleteEntity(box), 60_000);
}

Витринный транспортCopy Anchor Link

new PreviewVehicleCopy Anchor Link

Локальный транспорт для витрин и магазинов: заморожен, неуязвим, заперт и чист. Показ новой модели заменяет старую, и последний вызов всегда побеждает (более ранний вызов, ещё загружающий свою модель, ничего не делает). Удаляется при clear() и когда ваш ресурс останавливается. Ничего сетевого.

Сторона: Клиент · Ждёт: show ждёт (Promise)

new PreviewVehicle()

Lua-аналога нет.

ЧленыCopy Anchor Link

ПримерCopy Anchor Link

import { PreviewVehicle, setVehicleSetup } from "@aicore-fivem/lib/client";

const preview = new PreviewVehicle();
const STAGE = { x: -44.4, y: -1097.1, z: 26.4, heading: 120 };

export async function showCar(model: string, color: number): Promise<void> {
  const vehicle = await preview.show(model, STAGE, (v) => setVehicleSetup(v, { colors: [color, color] }));
  if (vehicle) SetVehicleNumberPlateText(vehicle, "SHOWROOM");
}

export function leaveShowroom(): void {
  preview.clear();
}