Связь с сервером

Клиентский скрипт никогда не доверяет сам себе: он спрашивает сервер, а сервер решает. Эти помощники переносят такие вопросы и ответы. Серверные половины описаны на странице Ввод от клиента (onClientCallback, onClientEvent, triggerClientCallback).

triggerServerCallbackCopy Anchor Link

Спрашивает сервер и ждёт ответа. Сервер отвечает через onClientCallback(name, ...). Используйте, чтобы читать данные, которые хранит сервер (прайс-лист, собственные записи игрока). Для действия, которое может быть отклонено, используйте callAction: он сам покажет отказ.

Сторона: Клиент · Ждёт: да (Promise в TypeScript, в Lua приостанавливает поток)

triggerServerCallback(name: string, args?: unknown[], timeoutMs?: number): Promise<unknown>

local result, err = aiLib.triggerServerCallback(name, args, timeout) -- вызывайте внутри потока

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

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

TypeScript: Promise<unknown>. Выполняется с тем, что вернул серверный обработчик (null, если он ничего не вернул). Значение не проверяется: проверьте его тип перед использованием. Promise отклоняется, если серверный обработчик выбросил ошибку, шлюз сервера отклонил вызов (ограничение частоты, guard-условие, неверные аргументы, блокировка) или ответ не пришёл в течение timeoutMs.

Lua: два значения. result это ответ; err равен nil при успехе, 'failed', если сервер отказал или произошла ошибка, 'timeout', если ответ не пришёл вовремя. При ошибке result равен nil.

ПримерCopy Anchor Link

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

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

RegisterCommand(
  "mycash",
  async () => {
    const cash = await triggerServerCallback("myscript:cash").catch(() => null);
    if (typeof cash !== "number") return notify(Locale("ERROR"), "error");
    notify(Locale("YOUR_CASH", cash), "info");
  },
  false,
);

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

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

onClientCallback("myscript:cash", (source) => core.GetMoney(source, "cash"));

callActionCopy Anchor Link

Выполняет действие на сервере и сам показывает отказ. Серверный обработчик (onClientCallback) отвечает ActionResult: { ok: true, ...data }, если всё получилось, или fail("LANG_KEY"), если отказал. При отказе, тайм-ауте или отказе шлюза callAction ищет ключ ошибки в языковом файле вашего ресурса и показывает его как уведомление об ошибке. Используйте для каждой кнопки, которая что-то меняет: купить, продать, арендовать, отремонтировать.

Сторона: Клиент · Ждёт: да (Promise в TypeScript, в Lua приостанавливает поток)

callAction(name: string, args: unknown[] | undefined, options: CallActionOptions): Promise<({ ok: true } & Record<string, unknown>) | null>

local reply = aiLib.callAction(name, args, options) -- таблица или nil, вызывайте внутри потока

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

CallActionOptionsCopy Anchor Link

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

Promise<({ ok: true } & Record<string, unknown>) | null>: весь успешный ответ (с любыми дополнительными полями, которые добавил сервер), если действие получилось; null, если оно было отклонено, завершилось ошибкой или тайм-аутом (уведомление уже показано, если не задан silent). Дополнительные поля не проверяются: проверяйте тип каждого, которое читаете. Lua возвращает таблицу ответа или nil.

ПримерCopy Anchor Link

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

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

export async function buy(itemId: string): Promise<void> {
  const reply = await callAction("myshop:buy", [itemId], { fallback: "BUY_FAILED" });
  if (!reply) return; // отказ уже на экране
  const paid = typeof reply.paid === "number" ? reply.paid : 0;
  notify(Locale("BOUGHT", paid), "success");
}

import { inventory, onClientCallback, resourceExport } from "@aicore-fivem/lib/server";
import { fail, oneArg, readText } from "@aicore-fivem/lib/shared";

const core = resourceExport("ai-core");
const PRICES: Record<string, number> = { water: 5, bread: 8 };

onClientCallback(
  "myshop:buy",
  { args: oneArg((v) => readText(v, 32)) },
  (source, item) => {
    const price = PRICES[item];
    if (price === undefined) return fail("UNKNOWN_ITEM");
    if (!inventory.canCarryItem(source, item, 1)) return fail("NO_ROOM");
    if (!core.RemoveMoney(source, "cash", price, "shop")) return fail("NO_MONEY");
    inventory.addItem(source, item, 1);
    return { ok: true, paid: price };
  },
);

isActionOkCopy Anchor Link

Сообщает, является ли ответ успешным ActionResult (ok ровно true). Используйте, когда сами вызываете triggerServerCallback и читаете ответ вручную.

Сторона: Клиент и сервер (из /shared, реэкспортируется из /client) · Ждёт: нет

isActionOk(reply: unknown): reply is { ok: true } & Record<string, unknown>

Lua-аналога нет: проверьте type(reply) == 'table' and reply.ok == true.

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

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

boolean: true, если reply является объектом (не массивом), у которого ok равно true. В TypeScript также сужает тип reply до { ok: true } & Record<string, unknown>.

ПримерCopy Anchor Link

import { isActionOk, replyError, triggerServerCallback } from "@aicore-fivem/lib/client";

export async function buyWater(): Promise<void> {
  const reply = await triggerServerCallback("myshop:buy", ["water"]).catch(() => null);
  if (isActionOk(reply)) console.log("bought");
  else console.log("refused with", replyError(reply, "BUY_FAILED"));
}

replyErrorCopy Anchor Link

Языковой ключ отклонённого ответа: его поле error или fallback, если ответа нет или в нём нет текста ошибки. Используйте вместе с isActionOk, когда показываете ошибку по-своему (на странице NUI вместо уведомления).

Сторона: Клиент и сервер (из /shared, реэкспортируется из /client) · Ждёт: нет

replyError(reply: unknown, fallback: string): string | null

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

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

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

string | null: null, если ответ успешный; error ответа, если это непустая строка; иначе fallback.

ПримерCopy Anchor Link

import { replyError, triggerServerCallback } from "@aicore-fivem/lib/client";

export async function buyFromPage(item: string): Promise<void> {
  const reply = await triggerServerCallback("myshop:buy", [item]).catch(() => null);
  const error = replyError(reply, "BUY_FAILED");
  if (error) SendNUIMessage({ action: "error", data: error });
}

onServerEventCopy Anchor Link

Слушает сетевое событие, которое сервер отправляет через emitNet (TriggerClientEvent в Lua). Вызовы, пришедшие не от сервера (локальный emit другого ресурса), отбрасываются, поэтому чит-меню не может их подделать. Каждый клиент ai-* слушает сервер именно так, никогда через голый onNet. В TypeScript обработчик, который принимает аргументы, должен указать парсер args: он проверяет сырые значения, а null отбрасывает вызов.

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

onServerEvent(name: string, handler: () => unknown): void
onServerEvent<A extends readonly unknown[]>(name: string, options: { args: (raw: unknown[]) => A | null }, handler: (...args: A) => unknown): void

aiLib.onServerEvent(name, handler) -- handler(...) получает сырые аргументы

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

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

void.

ПримерCopy Anchor Link

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

let renting = false;
const points = new Points();

// Без аргументов: короткая форма.
onServerEvent("myscript:reset", () => points.clear());

// Один булев аргумент: разбираем его, null отбрасывает неверный вызов.
onServerEvent(
  "myscript:state",
  { args: ([active]) => (typeof active === "boolean" ? [active] : null) },
  (active) => {
    renting = active;
    points.refresh();
  },
);

fromServerCopy Anchor Link

Пришло ли от сервера сетевое событие, которое обрабатывается прямо сейчас. onServerEvent уже использует это; вам это нужно только в голом обработчике onNet, который нельзя заменить.

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

fromServer(): boolean

Lua-аналога нет: в обработчике сетевого события Lua source пуст для локальных вызовов.

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

boolean: true, если текущее событие несёт числовой source сервера; false для локального вызова любым ресурсом.

ПримерCopy Anchor Link

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

onNet("legacy:event", (value: unknown) => {
  if (!fromServer()) return; // локальный вызов, не сервер
  console.log("server said", value);
});

onServerCallbackCopy Anchor Link

Отвечает на вопрос, который сервер задаёт этому клиенту через triggerClientCallback(name, source, ...). Значение, которое возвращает ваш обработчик (или с которым выполняется его promise), отправляется обратно. Выброшенная ошибка даёт ответ-неудачу, и promise сервера отклоняется.

Сторона: Клиент · Ждёт: нет (обработчик может быть async)

onServerCallback(name: string, handler: (...args: unknown[]) => unknown): void

aiLib.onServerCallback(name, handler) -- возвращаемое значение обработчика является ответом

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

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

void.

ПримерCopy Anchor Link

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

// Сервер спрашивает, как далеко этот игрок стоит от точки.
onServerCallback("myscript:distance", (x, y, z) => {
  if (typeof x !== "number" || typeof y !== "number" || typeof z !== "number") return null;
  return player.distanceTo({ x, y, z });
});