Oyuncular ve karakterler

import { online, onCharacter, notify, playersNear, coordsOf, PlayerMap, Cooldowns } from "@aicore-fivem/lib/server";

Oyuncu, server id’si (source) olan bağlı bir client’tır. Karakter ise oynadığı kişidir; karakter ekranındaki bir oyuncunun yüklü karakteri yoktur. Oyuncuların ve karakterlerin sahibi ai-core’dur; bu yardımcılar onları okur.

onlineCopy Anchor Link

online, resource’unun ai-core’un yüklü oyuncularından tuttuğu kopyadır: karakterler, rütbeleriyle meslek ve çete üyelikleri, meslek ve çete başına üye listeleri ve görev durumu. İlk kullanımda ai-core’u bir kez okur, sonra ai-core’un event’lerini takip eder; bu yüzden bir okuma bellekten bakmaktır. Sık çalışan yollarda (her sohbet mesajı, her ihbar) ai-core’un export’larını çağırmak yerine bunu kullan.

Lua’da aiLib.online her çağrıda ai-core’un export’larına sorar: aksiyonlar için uygundur, her tick için değil. character, name, jobs, gangs, jobGrade, gangGrade, dutyJob ve sources vardır; geri kalanının Lua karşılığı yoktur.

online.sourcesCopy Anchor Link

Yüklü karakteri olan her oyuncunun server id’si.

Taraf: Server · Bekler: hayır

online.sources(): IterableIterator<number>

local list = aiLib.online.sources() -- integer[]

Dönüş değeriCopy Anchor Link

IterableIterator<number> (Lua: bir dizi). Karakter ekranındaki oyuncular içinde değildir.

ÖrnekCopy Anchor Link

import { online, notify } from "@aicore-fivem/lib/server";

for (const source of online.sources()) notify(source, "Server restart in 5 minutes", "warning", 10_000);

online.sizeCopy Anchor Link

Kaç oyuncunun yüklü karakteri olduğu.

Taraf: Server · Bekler: hayır

readonly online.size: number

Lua karşılığı yok: #aiLib.online.sources().

online.characterCopy Anchor Link

Bir oyuncunun yüklü karakteri.

Taraf: Server · Bekler: hayır

online.character(source: number): CharacterInfo | null

local character = aiLib.online.character(source) -- table ya da nil

Dönüş değeriCopy Anchor Link

CharacterInfo (id, citizenid, slot, firstname, lastname, birthdate, sex, nationality) ya da oyuncunun yüklü karakteri yoksa null (Lua’da nil).

ÖrnekCopy Anchor Link

const character = online.character(source);
if (character) console.log(`${character.citizenid} is ${character.firstname}`);

online.charIdCopy Anchor Link

Oyuncunun yüklü karakterinin id’si (veritabanı id’si, yeniden bağlanmalarda değişmez).

Taraf: Server · Bekler: hayır

online.charId(source: number): number | undefined

Lua karşılığı yok: (aiLib.online.character(source) or {}).id.

Dönüş değeri: karakter id’si ya da hiçbiri yüklü değilse undefined. Yeniden bağlanmadan sonra da kalması gereken verileri (cooldown’lar, sahiplik) source ile değil, bu id ile anahtarla.

const charId = online.charId(source);
if (charId === undefined) return fail("NO_CHARACTER");

online.nameCopy Anchor Link

Karakterin "Ad Soyad"ı ya da karakter yüklü değilse FiveM oyuncu adı.

Taraf: Server · Bekler: hayır

online.name(source: number, options?: { fallback?: boolean }): string

local name = aiLib.online.name(source, fallback) -- fallback: boolean?

Dönüş değeri string.

notify(target, `${online.name(source)} sent you a gift`, "success");

online.jobsCopy Anchor Link

Görevde olsun ya da olmasın oyuncunun üyesi olduğu her meslek. ai-core bir karakterin birkaç meslek tutmasına (paneldeki maxJobs) ve aynı anda tek bir meslekte görevde olmasına izin verir.

Taraf: Server · Bekler: hayır

online.jobs(source: number): readonly string[]

local memberships = aiLib.online.jobs(source) -- { { job = 'police', grade = 2 }, ... }

Dönüş değeri: meslek adları (hiç yoksa ya da karakter yoksa boş). Lua karşılığı adları değil, üyelik tablolarını { job, grade } döndürür.

const isMechanic = online.jobs(source).includes("mechanic");

online.gangsCopy Anchor Link

Oyuncunun içinde olduğu her çete.

Taraf: Server · Bekler: hayır

online.gangs(source: number): readonly string[]

local memberships = aiLib.online.gangs(source) -- { { gang = 'ballas', grade = 0 }, ... }

Dönüş değeri: çete adları (hiç yoksa boş). Lua karşılığı üyelik tablolarını { gang, grade } döndürür.

if (online.gangs(source).length === 0) return fail("NOT_IN_GANG");

online.jobGradeCopy Anchor Link

Oyuncunun bir meslekteki rütbesi.

Taraf: Server · Bekler: hayır

online.jobGrade(source: number, job: string): number | null

local grade = aiLib.online.jobGrade(source, job) -- integer ya da nil

Dönüş değeri: rütbe numarası ya da oyuncu üye değilse null (Lua’da nil). 0 rütbesi bir üyedir: truthy kontrolüyle değil, null ile karşılaştır.

const grade = online.jobGrade(source, "police");
if (grade === null || grade < 3) return fail("RANK_TOO_LOW");

online.gangGradeCopy Anchor Link

Oyuncunun bir çetedeki rütbesi.

Taraf: Server · Bekler: hayır

online.gangGrade(source: number, gang: string): number | null

local grade = aiLib.online.gangGrade(source, gang) -- integer ya da nil

Dönüş değeri: rütbe ya da üye değilse null (Lua’da nil).

const boss = (online.gangGrade(source, "ballas") ?? -1) >= 4;

online.jobMembersCopy Anchor Link

Görevde olsun ya da olmasın bir meslekte üyeliği olan her oyuncu.

Taraf: Server · Bekler: hayır

online.jobMembers(job: string): ReadonlySet<number>

Lua karşılığı yok.

Dönüş değeri: canlı bir server id set’i (hiç yoksa boş). Oyuncular mesleğe girip çıktıkça değişir: bir await’ten önce onu kopyala ([...set]).

for (const source of online.jobMembers("mechanic")) notify(source, "A customer is waiting", "info");

online.gangMembersCopy Anchor Link

Bir çetedeki her oyuncu.

Taraf: Server · Bekler: hayır

online.gangMembers(gang: string): ReadonlySet<number>

Lua karşılığı yok. Dönüş değeri: canlı bir server id set’i; bir await’ten önce onu kopyala.

const members = [...online.gangMembers("ballas")];

online.dutyJobCopy Anchor Link

Oyuncunun görevde olduğu meslek.

Taraf: Server · Bekler: hayır

online.dutyJob(source: number): string | null

local job = aiLib.online.dutyJob(source) -- string ya da nil

Dönüş değeri: meslek adı ya da görevde değilse null (Lua’da nil).

if (online.dutyJob(source) !== "ambulance") return fail("NOT_ON_DUTY");

online.onDutyInCopy Anchor Link

Oyuncunun birkaç meslekten birinde (tüm polis meslekleri, tüm EMS meslekleri) görevde olup olmadığı.

Taraf: Server · Bekler: hayır

online.onDutyIn(source: number, jobs: readonly string[]): boolean

Lua karşılığı yok. Dönüş değeri: görevdeki meslek jobs içindeyse true.

const POLICE = ["police", "sheriff"];
if (!online.onDutyIn(source, POLICE)) return fail("NOT_POLICE");

online.onDutyForCopy Anchor Link

Bir meslekte görevde olan oyuncular.

Taraf: Server · Bekler: hayır

online.onDutyFor(job: string): ReadonlySet<number>

Lua karşılığı yok. Dönüş değeri: canlı bir server id set’i; bir await’ten önce onu kopyala.

for (const medic of online.onDutyFor("ambulance")) notify(medic, "Patient at Pillbox", "info");

online.countOnDutyCopy Anchor Link

Birkaç meslek genelinde kaç oyuncunun görevde olduğu.

Taraf: Server · Bekler: hayır

online.countOnDuty(jobs: readonly string[]): number

Lua karşılığı yok. Dönüş değeri: toplam sayı (maliyet oyuncu sayısıyla değil, meslek sayısıyla artar).

if (online.countOnDuty(["police", "sheriff"]) < 2) return fail("NOT_ENOUGH_POLICE");

online.allowsCopy Anchor Link

Oyuncunun bir erişim kuralıyla (meslekler, çeteler, minimum rütbeler, görevde olma) kilitlenmiş bir yeri kullanıp kullanamayacağı. Client’ın allows’u aynı kuralı kullanır; böylece oyuncunun gördüğü, server’ın kullanmasına izin verdiğiyle aynıdır.

Taraf: Server · Bekler: hayır

online.allows(source: number, rule: AccessRule): boolean

Lua karşılığı yok.

Dönüş değeri: listeler boşsa, oyuncu gangs’ten birinde minimum rütbesindeyse ya da jobs’tan birinde minimum rütbesindeyse (ve onDuty ayarlıysa o meslekte görevdeyse) true.

import { online } from "@aicore-fivem/lib/server";
import { readAccess, fail } from "@aicore-fivem/lib/shared";

const rule = readAccess(stashRecord); // { jobs: ["police"], gangs: [], grades: { police: 2 }, onDuty: true }
if (!online.allows(source, rule)) return fail("NO_ACCESS");

Karakter yaşam döngüsüCopy Anchor Link

onCharacterCopy Anchor Link

Bir karakter dünyaya girdiğinde ve ayrıldığında kodunu çalıştırır. Resource’un (yeniden) başladığında dünyada zaten olan karakterleri de yeniden oynatır ve oyundan çıkmaları kapsar; bu yüzden yanında bir playerDropped handler’ına ihtiyacın olmaz.

Taraf: Server · Bekler: hayır

onCharacter(handlers: CharacterHandlers): void

aiLib.onCharacter({ loaded = function(source, character) end, unloaded = function(source, charId, reason) end })

CharacterHandlersCopy Anchor Link

Dönüş değeriCopy Anchor Link

void.

ÖrnekCopy Anchor Link

import { onCharacter, PlayerMap } from "@aicore-fivem/lib/server";

const playtime = new PlayerMap<{ charId: number; since: number }>();

onCharacter({
  loaded(source, character) {
    playtime.set(source, { charId: character.id, since: Date.now() });
  },
  unloaded(source, charId, reason) {
    const entry = playtime.get(source);
    if (entry) console.log(`character ${charId} played ${Date.now() - entry.since} ms (${reason})`);
    playtime.delete(source);
  },
});

Oyuncularla konuşmakCopy Anchor Link

notifyCopy Anchor Link

Bir oyuncunun ekranında bir bildirim kartı gösterir (onu ai-lib ya da sahibin ai-core panelinde seçtiği bildirim arayüzü çizer).

Taraf: Server · Bekler: hayır

notify(source: number, text: string, kind?: NotificationKind, duration?: number): void

aiLib.notify(source, text, kind, duration)

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

void.

ÖrnekCopy Anchor Link

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

const Locale = createLocale();
notify(source, Locale("PAID", 250), "success");

isOnlineCopy Anchor Link

Bir oyuncunun hâlâ bağlı olup olmadığı. Uzun bir await’ten sonra bir şey vermeden önce kontrol et.

Taraf: Server · Bekler: hayır

isOnline(source: number): boolean

Lua karşılığı yok: GetPlayerName(source) ~= nil.

Dönüş değeri: oyuncu bağlıyken true.

await new Promise((resolve) => setTimeout(resolve, 60_000));
if (!isOnline(source)) return;

Yakındaki oyuncularCopy Anchor Link

Bunlar, server’daki her oyuncuyu dolaşmak yerine ai-core’a hangi oyuncuların birbirinin OneSync menzilinde (yaklaşık 424 metre) olduğunu sorar ve yalnızca o birkaç oyuncuyu ölçer. Yaklaşık 424 m’den büyük bir yarıçap daha uzaktaki kimseyi bulmaz.

playersNearCopy Anchor Link

Bir oyuncuya radius metre içindeki oyuncular.

Taraf: Server · Bekler: hayır

playersNear(source: number, radius: number): number[]

local list = aiLib.playersNear(source, radius) -- integer[]

Dönüş değeri: bir server id dizisi. TypeScript source’un kendisini de içerir; Lua onu dışarıda bırakır.

for (const other of playersNear(source, 20)) if (other !== source) notify(other, "You hear a scream", "warning");

playersNearEntityCopy Anchor Link

Ağa bağlı bir entity’ye (bir araç, bir prop) radius metre içindeki oyuncular: sahibi ve sahibinin menzilindeki oyuncular.

Taraf: Server · Bekler: hayır

playersNearEntity(entity: number, radius: number): number[]

local list = aiLib.playersNearEntity(entity, radius) -- integer[]

Dönüş değeri: bir server id dizisi. Entity yoksa ya da hiçbir oyuncu onun sahibi değilse boş (sahibi yalnızca server olan bir entity’nin yakınında kimse yoktur).

const witnesses = playersNearEntity(vehicle, 30);

nearestPlayerToCopy Anchor Link

Bir oyuncuya metres mesafe içindeki, filtrenden geçen en yakın diğer oyuncu.

Taraf: Server · Bekler: hayır

nearestPlayerTo(source: number, metres: number, filter?: (other: number) => boolean): number | null

local other = aiLib.nearestPlayerTo(source, metres, filter) -- integer ya da nil

Dönüş değeri: en yakın eşleşmenin server id’si ya da hiç yoksa null (Lua’da nil).

const target = nearestPlayerTo(source, 2, (other) => online.character(other) !== null);
if (target === null) return fail("NOBODY_NEAR");

KonumlarCopy Anchor Link

Lua karşılıkları yok: Lua’da vektör matematiği vardır (GetEntityCoords(GetPlayerPed(source)), #(a - b)).

coordsOfCopy Anchor Link

Server’ın gördüğü haliyle bir oyuncunun ped konumu.

Taraf: Server · Bekler: hayır

coordsOf(source: number): Vec3

Dönüş değeri: bir Vec3 { x, y, z }.

const { x, y, z } = coordsOf(source);

entityCoordsCopy Anchor Link

Herhangi bir entity’nin konumu (sahibinin senkronunun server’daki kopyası).

Taraf: Server · Bekler: hayır

entityCoords(entity: number): Vec3

Dönüş değeri: bir Vec3.

import { distance } from "@aicore-fivem/lib/shared";
if (distance(entityCoords(vehicle), coordsOf(source)) > 5) return fail("TOO_FAR");

isNearCopy Anchor Link

Oyuncunun ped’inin bir noktaya metres kadar yakın olup olmadığı. near koruması bunu kullanır.

Taraf: Server · Bekler: hayır

isNear(source: number, point: Vec3, metres: number): boolean

Dönüş değeri: menzil içindeyse true.

if (!isNear(source, { x: 25.7, y: -1347.3, z: 29.5 }, 3)) return fail("TOO_FAR");

vehicleOfCopy Anchor Link

Oyuncunun oturduğu araç.

Taraf: Server · Bekler: hayır

vehicleOf(source: number, options?: { driver?: boolean }): number

Dönüş değeri: araç entity’si ya da yayaysa (veya driver: true ile sürücü koltuğunda değilse) 0.

const vehicle = vehicleOf(source, { driver: true });
if (!vehicle) return fail("NOT_DRIVING");

Oyuncu başına depolarCopy Anchor Link

Bunların hiçbirinin Lua karşılığı yok: bir Lua tablosu kullan ve onu playerDropped’ta temizle. Her depoyu modül seviyesinde bir kez oluştur, asla bir handler içinde değil.

PlayerMapCopy Anchor Link

Oyuncu server id’siyle anahtarlanan ve oyuncu oyundan çıktığında kendini boşaltan bir Map. Oyuncu başına tuttuğun her şey için kullan (açık bir ekran, seçili bir eşya).

Taraf: Server · Bekler: hayır

new PlayerMap<V>(options?: { onDrop?: (source: number, value: V) => void })

Bir JavaScript Map’inin tüm metotlarına sahiptir (get, set, has, delete, size, iterasyon).

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

const carrying = new PlayerMap<string>({
  onDrop: (source, item) => console.log(`${source} left while carrying ${item}`),
});
carrying.set(source, "box");

CooldownsCopy Anchor Link

Oyun saatine göre oyuncu başına cooldown’lar; oyuncu oyundan çıktığında serbest bırakılır.

Taraf: Server · Bekler: hayır

new Cooldowns()
ready(source: number): boolean
start(source: number, ms: number): void
take(source: number, ms: number): boolean
left(source: number): number
clear(source: number): void

import { onClientCallback, Cooldowns } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const searchCooldown = new Cooldowns();

onClientCallback("my-bins:search", (source) => {
  if (!searchCooldown.take(source, 30_000)) return fail("WAIT");
  return { ok: true };
});

KeyedCooldownsCopy Anchor Link

Bir bağlantıdan uzun yaşayan herhangi bir anahtara göre cooldown’lar: bir karakter id’si, bir entity, bir kapı id’si. Süresi dolan girdiler map büyüdükçe temizlenir.

Taraf: Server · Bekler: hayır

new KeyedCooldowns<K = number>()
ready(key: K): boolean
start(key: K, ms: number): void
take(key: K, ms: number): boolean
left(key: K): number
clear(key: K): void

Cooldowns ile aynı metotlar, key’e göre. ms 0 ya da daha az olan bir start cooldown’ı bitirir.

import { KeyedCooldowns, online } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const robbed = new KeyedCooldowns<string>(); // market id’sine göre
const perCharacter = new KeyedCooldowns(); // karakter id’sine göre

function canRob(source: number, store: string) {
  const charId = online.charId(source);
  if (charId === undefined) return fail("NO_CHARACTER");
  if (!robbed.ready(store)) return fail("STORE_EMPTY");
  if (!perCharacter.take(charId, 15 * 60_000)) return fail("WAIT");
  robbed.start(store, 30 * 60_000);
  return { ok: true };
}

SourceLockCopy Anchor Link

Birkaç callback genelinde oyuncu başına çalışan tek bir aksiyon. Bir callback’in kendi lock: true’su yalnızca o callback’i kapsar; birbirini dışlaması gereken iki aksiyon (aynı aracı listelemek ve satmak) tek bir SourceLock paylaşır.

Taraf: Server · Bekler: hayır

new SourceLock()
run<T, B>(source: number, busy: B, task: () => Promise<T>): Promise<T | B>
release(source: number): void

Dönüş değeri (run): görevin sonucu ya da busy. release(source) oyuncuyu serbest bırakır; onu playerDropped’tan çağır (hâlâ çalışan bir görev, sonuçlanana kadar kendi girdisini tutar).

import { onClientCallback, SourceLock } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const dealer = new SourceLock();
on("playerDropped", () => dealer.release(Number(globalThis.source)));

onClientCallback("my-dealer:list", (source) => dealer.run(source, fail("BUSY"), async () => ({ ok: true })));
onClientCallback("my-dealer:sell", (source) => dealer.run(source, fail("BUSY"), async () => ({ ok: true })));

RateLimitCopy Anchor Link

Oyuncu başına bir patlama sınırı: herhangi bir windowMs içinde en fazla count aksiyon. Kapı zaten her girdiye hız sınırı uygular; bunu tek bir aksiyon için ek, daha yavaş bir sınır olarak kullan.

Taraf: Server · Bekler: hayır

new RateLimit(count: number, windowMs: number)
take(source: number): boolean
release(source: number): void

local limit = aiLib.RateLimit.new(count, windowMs)
local allowed = limit:take(source)
limit:release(source)

Dönüş değeri (take): true ve bir aksiyonu sayar ya da oyuncu sınırı aşmışsa false (sayılmaz). release(source) oyuncuyu unutur; onu playerDropped’tan çağır.

import { onClientCallback, RateLimit } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const reports = new RateLimit(3, 60_000);
on("playerDropped", () => reports.release(Number(globalThis.source)));

onClientCallback("my-report:send", (source) => {
  if (!reports.take(source)) return fail("TOO_MANY_REPORTS");
  return { ok: true };
});

KeyWatchersCopy Anchor Link

Tek bir anahtarın canlı değişikliklerini alan oyuncular (bir otoparkın arabaları, açık bir karakter sayfası). Oyuncu başına bir anahtar: yeni bir anahtarı izlemek eskisini bırakır. Oyundan çıkışta serbest bırakılır; her işlem sabit zamanlıdır.

Taraf: Server · Bekler: hayır

new KeyWatchers<K>()
watch(source: number, key: K): void
stop(source: number): void
of(key: K): ReadonlySet<number> | undefined
keyOf(source: number): K | undefined

import { onClientCallback, onClientEvent, KeyWatchers } from "@aicore-fivem/lib/server";
import { oneArg, readText } from "@aicore-fivem/lib/shared";

const lots = new KeyWatchers<string>();

onClientCallback("my-lot:open", { args: oneArg((v) => readText(v, 32)) }, (source, lot) => {
  lots.watch(source, lot);
  return { ok: true, cars: [] }; // snapshot
});
onClientEvent("my-lot:close", (source) => lots.stop(source));

function carChanged(lot: string, car: unknown) {
  for (const source of lots.of(lot) ?? []) emitNet("my-lot:car", source, car); // delta
}