Точки взаимодействия

Точка это любое место, которым пользуется игрок: прилавок магазина, дверь, NPC, место возврата, каждый банкомат, багажник каждой машины. Вы описываете её один раз (где, какой текст, что происходит), а lib рисует её так, как выбрал владелец сервера.

Prompt или targetCopy Anchor Link

Владелец выбирает стиль взаимодействия в админ-панели ai-core (Interaction). В обоих случаях выполняется один и тот же onPressed, поэтому вашему скрипту неважно, какой стиль включён.

Если владелец выбрал target, но ни один target-скрипт не запущен, каждая точка становится подсказкой (prompt). Точка может переопределить выбор владельца: promptOnly оставляет подсказку (действия из транспорта: топливные колонки, автомойки), preferTarget использует опцию target всегда, когда запущен target-скрипт (сиденья). Когда target-скрипт запускается или останавливается или владелец переключает стиль, каждая точка переходит сама.

new PointsCopy Anchor Link

Создаёт группу точек. Создайте одну группу на функцию в начале файла и добавляйте в неё точки.

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

new Points()

local points = aiLib.Points.new()

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

Группа Points с методами ниже.

ПримерCopy Anchor Link

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

const points = new Points();

points.addCopy Anchor Link

Добавляет точку в месте или заменяет точку с тем же id. Точка может иметь собственного NPC (ped) и блип на карте (blip).

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

points.add(id: string, options: PointOptions): void

points:add(id, options)

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

PointOptionsCopy Anchor Link

PointPedCopy Anchor Link

Поле ped принимает опции LocalPed, кроме onSpawn и onDespawn (их использует точка):

PointBlipCopy Anchor Link

Поле blip принимает опции блипа; coords по умолчанию равен точке:

PromptAnchorCopy Anchor Link

Что возвращает функция world (PromptAnchor), одно из:

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

void.

ПримерCopy Anchor Link

import { callAction, createLocale, hasJob, onMembershipChange, Points } from "@aicore-fivem/lib/client";

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

// Прилавок магазина с продавцом и блипом на карте.
points.add("shop", {
  coords: { x: 25.7, y: -1347.3, z: 29.5 },
  label: Locale("OPEN_SHOP"),
  icon: "basket-shopping",
  ped: { model: "mp_m_shopkeep_01", coords: { x: 24.5, y: -1346.6, z: 29.5, heading: 270 } },
  blip: { sprite: 52, color: 2, label: Locale("SHOP") },
  onPressed: () => callAction("myshop:open", [], { fallback: "SHOP_FAILED" }),
});

// Хранилище, которое может открыть только полиция; текст следует состоянию.
let locked = true;
points.add("evidence", {
  coords: { x: 474.9, y: -996.4, z: 26.3 },
  label: () => (locked ? Locale("UNLOCK") : Locale("LOCK")),
  icon: "box-archive",
  canShow: () => hasJob(["police"], 2),
  onPressed: async () => {
    const reply = await callAction("myscript:toggle", [], { fallback: "TOGGLE_FAILED" });
    if (reply) locked = !locked;
    points.refresh("evidence");
  },
});

// canShow читает работу: проверяем снова, когда меняются работы, дежурство или банды.
onMembershipChange(() => points.refresh());

points.addModelCopy Anchor Link

Добавляет точку на каждый объект мира с определёнными моделями (банкоматы, торговые автоматы, мусорные контейнеры, стулья) или заменяет точку с тем же id. В режиме target это опция target на этих моделях; в режиме prompt подсказка показывается рядом с ближайшим объектом. Поиск ближайшего объекта выполняется один раз в ai-lib для всех ресурсов, два раза в секунду, и приостанавливается, пока игрок стоит на месте.

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

points.addModel(id: string, options: ModelPointOptions): void

points:addModel(id, options)

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

ModelPointOptionsCopy Anchor Link

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

void.

ПримерCopy Anchor Link

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

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

points.addModel("atm", {
  models: ["prop_atm_01", "prop_atm_02", "prop_atm_03", "prop_fleeca_atm"],
  label: Locale("USE_ATM"),
  icon: "credit-card",
  onPressed: (atm) => callAction("mybank:atm", [NetworkGetNetworkIdFromEntity(atm)], { fallback: "ATM_FAILED" }),
});

points.addVehicleCopy Anchor Link

Добавляет точку на каждый сетевой транспорт (багажник, капот, толкать, ремонт) или заменяет точку с тем же id. В режиме target это глобальная опция транспорта target-скрипта; в режиме prompt подсказка показывается у ближайшего сетевого транспорта в пределах radius.

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

points.addVehicle(id: string, options: VehiclePointOptions): void

points:addVehicle(id, options)

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

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

void.

ПримерCopy Anchor Link

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

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

points.addVehicle("trunk", {
  label: Locale("OPEN_TRUNK"),
  icon: "box-open",
  radius: 2.5,
  canShow: (vehicle) => vehicle !== 0 && cache.vehicle === false && GetVehicleDoorLockStatus(vehicle) < 2,
  onPressed: (vehicle) => SetVehicleDoorOpen(vehicle, 5, false, false),
});

points.removeCopy Anchor Link

Удаляет одну точку вместе с её подсказкой, опцией target, NPC и блипом. Работает для точек, созданных через add, addModel и addVehicle. Неизвестный id ничего не делает.

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

points.remove(id: string): void

points:remove(id)

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

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

void.

ПримерCopy Anchor Link

points.remove("shop");

points.clearCopy Anchor Link

Удаляет все точки группы.

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

points.clear(): void

points:clear()

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

void.

ПримерCopy Anchor Link

onServerEvent("myscript:jobEnded", () => points.clear());

points.refreshCopy Anchor Link

Заново читает canShow и функции подписей. Вызывайте, когда изменилось то, что они читают: работа, дежурство, транспорт, состояние, которое прислал сервер. Подсказки обновляются сразу; опции target читают canShow при открытии глаза, а изменённая подпись ставится заново.

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

points.refresh(id?: string): void

points:refresh() -- каждая точка группы

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

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

void.

ПримерCopy Anchor Link

import { EntityState, onCache, onMembershipChange, Points, stateBoolean } from "@aicore-fivem/lib/client";

const points = new Points();
const robbed = new EntityState("robbed", stateBoolean);

onCache("vehicle", () => points.refresh());
onMembershipChange(() => points.refresh());
// Изменилась одна касса: обновляем только её точку.
robbed.onChange((netId) => points.refresh(`register:${netId}`));

points.isInsideCopy Anchor Link

Стоит ли игрок сейчас внутри радиуса точки (точки, созданные через add).

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

points.isInside(id: string): boolean

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

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

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

boolean: true, пока игрок внутри; false снаружи, а также для неизвестного id или точки модели.

ПримерCopy Anchor Link

if (points.isInside("garage")) notify(Locale("PARK_HERE"), "info");

points.restyleCopy Anchor Link

Переводит все точки группы на текущий стиль взаимодействия. Lib вызывает это сама, когда владелец переключает стиль или target-скрипт запускается или останавливается; вам это никогда не нужно.

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

points.restyle(): void

Lua-аналога нет (Lua тоже меняет стиль сам).

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

void.

Точки из записей панелиCopy Anchor Link

Большинство точек берутся из файла записей админ-панели вашего скрипта (магазины, гаражи, стойки аренды). Зеркалируйте файл на клиенте через AdminWorld, затем стройте точки каждой записи через RecordObjects: изменённая запись перестраивает только свои точки, удалённая их убирает.

new RecordObjectsCopy Anchor Link

Поддерживает объекты мира из файла записей (точки, блипы, педы, зоны) в соответствии с файлом, по одной записи за раз. build(key, record) создаёт объекты одной записи и возвращает способ их удалить. Он строит все записи в своём конструкторе.

Сторона: Клиент и сервер (из @aicore-fivem/lib/shared) · Ждёт: нет

new RecordObjects<T>(
  source: RecordSource,
  file: string,
  records: RecordReader<T> | ReadonlyMap<string, T>,
  build: (key: string, record: T) => (() => void) | void,
)

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

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

ЧленыCopy Anchor Link

ПримерCopy Anchor Link

import { AdminWorld, callAction, createLocale, Points } from "@aicore-fivem/lib/client";
import { readVec3, RecordObjects, str } from "@aicore-fivem/lib/shared";

const Locale = createLocale<typeof import("../../locales/en.json")>();
const world = new AdminWorld(["settings", "shops"]);
const points = new Points();

interface Shop { label: string; coords: { x: number; y: number; z: number } }
const readShop = (_key: string, raw: Record<string, unknown>): Shop | null => {
  const coords = readVec3(raw.coords);
  return coords ? { label: str(raw.label, "Shop"), coords } : null;
};

const shops = new RecordObjects(world, "shops", readShop, (id, shop) => {
  points.add(id, {
    coords: shop.coords,
    label: Locale("OPEN_SHOP", shop.label),
    onPressed: () => callAction("myshop:open", [id], { fallback: "SHOP_FAILED" }),
  });
  return () => points.remove(id);
});

// Изменилась настройка, которую читает каждый магазин: перестраиваем все.
world.onChange("settings", () => shops.rebuildAll());

new AdminWorldCopy Anchor Link

Клиентская копия мировых файлов панели вашего скрипта (файлов, в схеме которых указано sync: "all", см. Админ-панель). Она читает копию, которую FiveM закэшировал при старте, один раз спрашивает сервер о записях, изменённых с тех пор, а затем следует живым изменениям. Никогда не опрашивает.

Сторона: Клиент · Ждёт: нет (promise ready сообщает, когда пришли изменения с момента старта)

new AdminWorld(files: string[])

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

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

ЧленыCopy Anchor Link

ПримерCopy Anchor Link

import { AdminWorld } from "@aicore-fivem/lib/client";
import { num, record } from "@aicore-fivem/lib/shared";

const world = new AdminWorld(["settings"]);
const settings = world.view("settings", (raw) => ({
  radius: num(record(raw).radius, 2),
}));

world.onChange("settings", () => console.log("new radius", settings.value.radius));