Karakterler ve oyuncular

Bir oyuncu, server id’si (source) olan bağlı bir kişidir. Bir karakter, o oyuncunun oynadığı kişilerden biridir; bir veritabanı id’si (charId) ve bir citizen id’si (citizenid, ABC12345 gibi kısa bir metin) vardır. Bir oyuncu karakter ekranında birini seçtikten sonra yüklü bir karaktere sahip olur. Buradaki export’ların çoğu ondan önce null cevabı verir.

Export çağrıları cevaplarını kopyalar; bu yüzden ihtiyacın olanı bir kez oku ve tekrar sormak yerine ai-core’un event’lerini izle (ai-core:playerLoaded, ai-core:playerUnloaded). Bkz. Event’ler ve durum.

GetPlayerDataCopy Anchor Link

ai-core’un yüklü bir oyuncu için tuttuğu her şey tek nesnede: karakter, para, meslekler, mesai, çeteler ve metadata. Bir resource geç başladığında ve bir oyuncunun tam durumuna bir kez ihtiyaç duyduğunda kullan; tek değerler için aşağıdaki daha küçük export’ları kullan.

Taraf: Server · Bekler: hayır · Lib: server’da yok (client lib’in getPlayerData’sı aynı veriyi oyuncunun oyununda okur)

GetPlayerData(src: number): AiPlayerData | null

local data = exports['ai-core']:GetPlayerData(source) -- tablo ya da nil

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

AiPlayerData | null: oyuncunun verisinin bir kopyası (AiPlayerData). O server id’sine sahip kimsenin yüklü karakteri yoksa (bağlı değil ya da hâlâ karakter ekranında) null. Kopya sonradan değişmez: yeni değerler için tekrar çağır ya da event’leri izle.

ÖrnekCopy Anchor Link

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

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

addCommand("whoami", { help: "Shows your character", restricted: true }, (source) => {
  const data = core.GetPlayerData(source);
  if (!data?.character) return;
  const { firstname, lastname } = data.character;
  console.log(`${firstname} ${lastname}: job ${data.job.job} (grade ${data.job.grade}), cash ${data.money.cash ?? 0}`);
});

GetCharacterCopy Anchor Link

Bir oyuncunun yüklü karakteri: veritabanı id’si, citizen id, slot, adlar, doğum tarihi, cinsiyet ve uyruk. Bir ad göstermek ya da karakter id’sine göre bir şey saklamak için kullan.

Taraf: Server · Bekler: hayır · Lib: yok (online.character(source) aynısını export çağrısı olmadan lib’in aynasından okur)

GetCharacter(src: number): CharacterInfo | null

local character = exports['ai-core']:GetCharacter(source) -- tablo ya da nil

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

CharacterInfo | null: karakter (CharacterInfo). Oyuncunun yüklü karakteri yoksa null.

ÖrnekCopy Anchor Link

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

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

onClientCallback("myscript:profile", (source) => {
  const character = core.GetCharacter(source);
  if (!character) return fail("NO_CHARACTER");
  return { ok: true, name: `${character.firstname} ${character.lastname}`, citizenid: character.citizenid };
});

GetSourceByCharIdCopy Anchor Link

Bir karakteri şu anda oynayan oyuncunun server id’si. Bir karakter id’si sakladığında (bir sahip, bir kişi) ve oyunda o kişiye ulaşman gerektiğinde kullan.

Taraf: Server · Bekler: hayır · Lib: yok

GetSourceByCharId(charId: number): number | null

local src = exports['ai-core']:GetSourceByCharId(charId) -- sayı ya da nil

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

number | null: oyuncunun server id’si. Şu anda o karakteri kimse oynamıyorsa (çevrimdışı ya da başka bir karakter yüklü) null.

ÖrnekCopy Anchor Link

import { notify, resourceExport } from "@aicore-fivem/lib/server";
import { Locale } from "common";

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

/** Bir ev sahibine, sahip çevrimiçiyken birinin zili çaldığını söyler. */
export function ringOwner(ownerCharId: number): void {
  const owner = core.GetSourceByCharId(ownerCharId);
  if (owner !== null) notify(owner, Locale("NOTIFY_DOORBELL"), "info");
}

GetSourceByCitizenIdCopy Anchor Link

GetSourceByCharId ile aynı, citizen id ile. Citizen id saklayan verilerle kullan (çoğu ESX / QB tarzı tablo öyledir).

Taraf: Server · Bekler: hayır · Lib: yok

GetSourceByCitizenId(citizenid: string): number | null

local src = exports['ai-core']:GetSourceByCitizenId(citizenid) -- sayı ya da nil

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

number | null: o karakteri oynayan oyuncunun server id’si. Karakter yüklü değilse null.

ÖrnekCopy Anchor Link

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

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

addCommand("findcid", {
  help: "Finds the player of a citizen id",
  params: [{ name: "citizenid", type: "string" }],
  restricted: true,
}, (source, args) => {
  const target = core.GetSourceByCitizenId(args.citizenid);
  console.log(target === null ? "not online" : `server id ${target}`);
});

GetLoadedSourcesCopy Anchor Link

Yüklü karakteri olan her oyuncunun server id’leri. Seyrek, tüm sunucuyu kapsayan işler için kullan (bir restart uyarısı, bir admin listesi).

Taraf: Server · Bekler: hayır · Lib: online.sources() aynısını lib’in aynasından okur

GetLoadedSources(): number[]

local sources = exports['ai-core']:GetLoadedSources() -- sayı listesi

ParametrelerCopy Anchor Link

Yok.

Dönüş değeriCopy Anchor Link

number[]: yüklü oyuncu başına bir server id, sabit bir sırası yok. Kimsenin karakteri yüklü değilse boş liste. Hâlâ karakter ekranındaki oyuncular içinde yoktur.

ÖrnekCopy Anchor Link

import { addCommand, notify, resourceExport } from "@aicore-fivem/lib/server";
import { Locale } from "common";

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

addCommand("announce", {
  help: "Sends a notification to every player",
  params: [{ name: "text", type: "longString" }],
  restricted: true,
}, (_source, args) => {
  for (const target of core.GetLoadedSources())
    notify(target, Locale("NOTIFY_ANNOUNCEMENT", args.text), "warning");
});

GetUserIdCopy Anchor Link

Bağlı bir oyuncunun hesap id’si: oyuncunun FiveM hesabını ve onun her karakterini tutan ai_core_users satırı. Çoğu export’un aksine, oyuncu hâlâ karakter ekranındayken de cevap verir.

Taraf: Server · Bekler: hayır · Lib: yok

GetUserId(src: number): number | null

local userId = exports['ai-core']:GetUserId(source) -- sayı ya da nil

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

number | null: hesap id’si. Oyuncu bağlı değilse ya da henüz karakter ekranına ulaşmadıysa null.

ÖrnekCopy Anchor Link

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

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

addCommand("account", {
  help: "Shows a player account id",
  params: [{ name: "id", type: "playerId" }],
  restricted: true,
}, (_source, args) => {
  console.log(`account ${core.GetUserId(args.id) ?? "unknown"}`);
});

GetFivemIdCopy Anchor Link

Oyuncunun FiveM (Cfx.re) hesap id’si. ai-core bunu oyuncunun hesabının anahtarı olarak kullanır: bu id’si olmayan bir oyuncu bağlanamaz.

Taraf: Server · Bekler: hayır · Lib: yok

GetFivemId(src: number): string | null

local fivemId = exports['ai-core']:GetFivemId(source) -- string ya da nil

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

string | null: fivem: öneki olmadan id (örneğin 1234567). Oyuncunun yüklü karakteri yoksa null.

ÖrnekCopy Anchor Link

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

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

addCommand("fivemid", {
  help: "Prints the add_principal line for a player",
  params: [{ name: "id", type: "playerId" }],
  restricted: true,
}, (_source, args) => {
  const id = core.GetFivemId(args.id);
  if (id) console.log(`add_principal identifier.fivem:${id} group.admin`);
});

GetCharacterInfoCopy Anchor Link

Veritabanı id’sine göre bir karakter, yüklü olsun olmasın, ait olduğu hesabın id’siyle. Kişi çevrimdışı olabilecekken bir şeyin kime ait olduğunu göstermek için kullan.

Taraf: Server · Bekler: hayır (done ile cevap verir) · Lib: yok

GetCharacterInfo(
  charId: number,
  done: (info: (CharacterInfo & { userId: number }) | null) => void,
): void

exports['ai-core']:GetCharacterInfo(charId, function(info) end) -- info: tablo ya da nil

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

Hiçbir şey. done bir alanı fazla olan bir CharacterInfo alır, userId (hesap id’si); bilinmeyen ya da silinmiş bir karakter, yanlış bir id ya da başarısız bir okumada null alır. done olarak bir fonksiyon verilmezse çağrı hiçbir şey yapmaz.

ÖrnekCopy Anchor Link

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

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

addCommand("charinfo", {
  help: "Shows a character by id",
  params: [{ name: "charId", type: "number" }],
  restricted: true,
}, (_source, args) => {
  core.GetCharacterInfo(args.charId, (info) => {
    if (!info) return console.log("no such character");
    console.log(`${info.firstname} ${info.lastname} (${info.citizenid}), account ${info.userId}`);
  });
});

SwitchCharacterCopy Anchor Link

Bir oyuncuyu sunucudan çıkmadan, çıkış yapar gibi karakter ekranına geri gönderir. ai-core önce karakteri kaydeder ve kaldırır, sonra ekranı açar.

Taraf: Server · Bekler: hayır (kaldırma çağrı döndükten sonra çalışır) · Lib: yok

SwitchCharacter(src: number): boolean

local started = exports['ai-core']:SwitchCharacter(source) -- boolean

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

boolean: değişim başladığında true. Oyuncunun yüklü karakteri yoksa false.

ÖrnekCopy Anchor Link

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

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

// Menündeki bir "Karakter değiştir" düğmesi.
onClientCallback("myscript:logout", (source) =>
  core.SwitchCharacter(source) ? { ok: true } : fail("NO_CHARACTER"),
);

SetOfflinePositionCopy Anchor Link

Yüklü olmayan bir karakterin doğma noktasını taşır: o karakter bir sonraki seçildiğinde orada görünür. Bir şey uyuyan bir bedeni ya da çevrimdışı bir karakteri taşıdığında kullan (taşınıp götürülen bir beden, çekilen bir oyuncu).

Taraf: Server · Bekler: hayır (yazma arka planda gelir) · Lib: characters.setOfflinePosition

SetOfflinePosition(
  charId: number,
  position: { x: number; y: number; z: number; heading?: number },
): boolean

local accepted = exports['ai-core']:SetOfflinePosition(charId, { x = x, y = y, z = z, heading = h })

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

boolean: taşıma kabul edildiğinde true; veritabanı yazması o karakterin hiçbir yüklemesi ya da kaydı çalışmadığında gelir (en fazla 30 saniye bekler). Karakter şu an yüklüyse, charId bir tam sayı değilse ya da bir koordinat eksik veya sonlu bir sayı değilse false. Eksik bir heading 0 olarak saklanır.

ÖrnekCopy Anchor Link

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

const core = resourceExport("ai-core");
const HOSPITAL = { x: 298.6, y: -584.5, z: 43.3, heading: 70 };

/** Dünyada çok uzun kalan bir beden hastaneye taşınır. */
export function sendBodyToHospital(charId: number): void {
  if (!core.SetOfflinePosition(charId, HOSPITAL))
    console.log(`character ${charId} is online, not moved`);
}

GetPlayersInScopeCopy Anchor Link

Başka bir oyuncunun OneSync kapsamındaki oyuncular: oyunu o an o oyuncuyu stream eden herkes, çevresinde yaklaşık 424 metre. ai-core bu listeyi FiveM’in scope event’lerinden her resource için bir kez tutar, böylece diğer resource’lar o event’leri asla kendileri dinlemez.

Taraf: Server · Bekler: hayır · Lib: playersNear(source, radius) ve playersNearEntity(entity, radius) bunun üstüne kurulur ve mesafeye göre süzer

GetPlayersInScope(source: number): number[]

local nearby = exports['ai-core']:GetPlayersInScope(source) -- server id listesi

ParametrelerCopy Anchor Link

Dönüş değeriCopy Anchor Link

number[]: kapsamdaki diğer oyuncuların server id’leri (oyuncunun kendisi listede yoktur). Yalnız bir oyuncu, bilinmeyen bir id ya da sayı olmayan bir değer için boş liste.

ÖrnekCopy Anchor Link

import { coordsOf, resourceExport } from "@aicore-fivem/lib/server";
import { distance } from "@aicore-fivem/lib/shared";

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

/** Bir oyuncunun 30 m çevresindeki herkese bir ses çalar. */
export function playNear(source: number, sound: string): void {
  const at = coordsOf(source);
  for (const other of [source, ...core.GetPlayersInScope(source)])
    if (distance(coordsOf(other), at) <= 30) emitNet("myscript:sound", other, sound);
}