Server ile konuşmak

Bir client script’i asla kendine güvenmez: server’a sorar ve kararı server verir. Bu yardımcılar o soruları ve cevapları taşır. Server tarafındaki yarılar Client girdisi sayfasındadır (onClientCallback, onClientEvent, triggerClientCallback).

triggerServerCallbackCopy Anchor Link

Server’a sorar ve cevabını bekler. Server onClientCallback(name, ...) ile cevap verir. Server’ın tuttuğu verileri (bir fiyat listesi, bir oyuncunun kendi kayıtları) okumak için kullan. Reddedilebilecek bir aksiyon için callAction kullan: reddi senin için gösterir.

Taraf: Client · Bekler: evet (TypeScript’te Promise, Lua’da thread’i yield eder)

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

local result, err = aiLib.triggerServerCallback(name, args, timeout) -- bir thread içinde çağır

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

TypeScript: Promise<unknown>. Server handler’ının döndürdüğüyle çözülür (hiçbir şey döndürmediyse null). Değer kontrol edilmez: kullanmadan önce tipini test et. Server handler’ı hata fırlattıysa, server kapısı çağrıyı reddettiyse (hız sınırı, bir koruma, hatalı argümanlar, bir kilit) ya da timeoutMs içinde cevap gelmediyse promise reddedilir.

Lua: iki değer. result cevaptır; err başarıda nil, server reddettiyse ya da başarısız olduysa 'failed', zamanında cevap gelmediyse 'timeout'’tur. Hata durumunda result nil olur.

ÖrnekCopy 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

Server’da bir aksiyon çalıştırır ve reddi senin için gösterir. Server handler’ı (onClientCallback) bir ActionResult ile cevap verir: çalıştıysa { ok: true, ...data }, reddettiyse fail("LANG_KEY"). Bir reddetmede, zaman aşımında ya da kapı reddinde callAction, hata anahtarını senin resource’unun dil dosyasında arar ve bir hata bildirimi olarak gösterir. Bir şeyi değiştiren her buton için kullan: satın al, sat, kirala, tamir et.

Taraf: Client · Bekler: evet (TypeScript’te Promise, Lua’da thread’i yield eder)

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

local reply = aiLib.callAction(name, args, options) -- table ya da nil, bir thread içinde çağır

ParametrelerCopy Anchor Link

CallActionOptionsCopy Anchor Link

Dönüş değeriCopy Anchor Link

Promise<({ ok: true } & Record<string, unknown>) | null>: aksiyon çalıştıysa ok cevabının tamamı (server’ın eklediği ek alanlarla birlikte); reddedildiyse, başarısız olduysa ya da zaman aşımına uğradıysa null (silent değilse bildirim zaten gösterilmiştir). Ek alanlar kontrol edilmez: okuduğun her birinin tipini test et. Lua cevap tablosunu ya da nil döndürür.

ÖrnekCopy 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; // ret zaten ekranda
  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

Bir cevabın ok bir ActionResult olup olmadığını söyler (ok tam olarak true). triggerServerCallback’i kendin çağırıp cevabı elle okuduğunda kullan.

Taraf: Client ve server (/shared’dan, /client tarafından yeniden export edilir) · Bekler: hayır

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

Lua karşılığı yok: type(reply) == 'table' and reply.ok == true test et.

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

boolean: reply ok’u true olan bir nesneyse (dizi değil) true. TypeScript’te ayrıca reply’ı { ok: true } & Record<string, unknown> tipine daraltır.

ÖrnekCopy 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

Reddedilmiş bir cevabın lang anahtarı: error alanı ya da cevap yoksa veya hata metni yoksa fallback. Hatayı kendi yönteminle (bir bildirim yerine bir NUI sayfasında) gösterdiğinde isActionOk ile birlikte kullan.

Taraf: Client ve server (/shared’dan, /client tarafından yeniden export edilir) · Bekler: hayır

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

Lua karşılığı yok.

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

string | null: cevap ok ise null; boş olmayan bir string ise cevabın error’u; aksi halde fallback.

ÖrnekCopy 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

Server’ın emitNet ile (Lua’da TriggerClientEvent) gönderdiği bir net event’i dinler. Server’dan gelmeyen çağrılar (başka bir resource’un yerel emit’i) atılır; böylece bir hile menüsü onları taklit edemez. Her ai-* client’ı server’ı bu şekilde dinler, asla çıplak bir onNet ile değil. TypeScript’te argüman alan bir handler bir args ayrıştırıcısı belirtmelidir: ham değerleri kontrol eder ve null çağrıyı atar.

Taraf: Client · Bekler: hayır

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(...) ham argümanları alır

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

void.

ÖrnekCopy Anchor Link

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

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

// Argüman yok: kısa biçim.
onServerEvent("myscript:reset", () => points.clear());

// Tek bir boolean argüman: onu ayrıştır, null hatalı bir çağrıyı atar.
onServerEvent(
  "myscript:state",
  { args: ([active]) => (typeof active === "boolean" ? [active] : null) },
  (active) => {
    renting = active;
    points.refresh();
  },
);

fromServerCopy Anchor Link

Şu an işlenen net event’in server’dan gelip gelmediği. onServerEvent bunu zaten kullanır; ona yalnızca değiştiremediğin çıplak bir onNet handler’ında ihtiyacın olur.

Taraf: Client · Bekler: hayır

fromServer(): boolean

Lua karşılığı yok: bir Lua net event handler’ında yerel emit’ler için source boştur.

Dönüş değeriCopy Anchor Link

boolean: güncel event server’ın sayısal source’unu taşıyorsa true; herhangi bir resource’un yerel emit’i için false.

ÖrnekCopy Anchor Link

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

onNet("legacy:event", (value: unknown) => {
  if (!fromServer()) return; // server değil, yerel bir emit
  console.log("server said", value);
});

onServerCallbackCopy Anchor Link

Server’ın bu client’a triggerClientCallback(name, source, ...) ile sorduğu bir soruya cevap verir. Handler’ının döndürdüğü değer (ya da promise’inin çözüldüğü değer) geri gönderilir. Fırlatılan bir hata başarısızlık cevabı verir ve server’ın promise’i reddedilir.

Taraf: Client · Bekler: hayır (handler async olabilir)

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

aiLib.onServerCallback(name, handler) -- handler’ın dönüş değeri cevaptır

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

void.

ÖrnekCopy Anchor Link

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

// Server bu oyuncunun bir noktaya ne kadar uzakta durduğunu sorar.
onServerCallback("myscript:distance", (x, y, z) => {
  if (typeof x !== "number" || typeof y !== "number" || typeof z !== "number") return null;
  return player.distanceTo({ x, y, z });
});