AI Core
API başvurusuAI Core: server export’ları

Kayıtlı karakterler

Yüklü olsun olmasın her karakteri oku ve değiştir - bul, oku, parasını, mesleklerini, çetelerini, metadata'sını ve adını değiştir, kaydet, sil.

Karakterler sayfasındaki export'lar yüklü karakteriyle bağlı olan bir oyuncu hakkında cevap verir. Buradakiler her karakter hakkında cevap verir, bağlı olsun ya da olmasın: ai-core yüklü bir karakteri bellekten, kayıtlı olanı veritabanından okur; bir yazma işlemi karakter yüklüyse canlı karaktere, değilse satıra ulaşır.

Kullanmadan önce bilinmesi gereken üç şey:

  • Bir karakter, karakter id'si ile adreslenir (charId, bir sayı - CharacterInfo.id). citizenid metindir ve framework köprülerine aittir; birini diğerine GetCharIdByCitizenId ile çevir, asla değeri kendin dönüştürerek değil.
  • Bu export'lar bir callback ile cevap verir (done), çünkü kayıtlı bir karakter için veritabanı okuması gerekir ve resource sınırını hiçbir promise geçmez. TypeScript'te lib'in characters modülü bunun yerine Promise verir; Lua'da aiLib.characters bir thread içinde senin yerine bekler.
  • Her yazma işlemi ActionResult döner: { ok: true } ya da ai-core'un kendi dil anahtarlarından biriyle (locales/en.json) { ok: false, error: "LANG_KEY" }; böylece callAction ile gösterebilir ya da kendin çevirebilirsin.

ai-core'un tablolarını (ai_core_characters, ai_core_accounts, ai_core_character_jobs...) kendi sorgularınla asla okuma ve yazma. Karakterler bellekte durur ve ai-core'un takvimiyle yazılır; doğrudan bir SELECT eski veri verebilir ve kolonlar içeridir.

GetCharIdByCitizenId

Bir citizenid'nin arkasındaki karakter id'si, yüklü olsun olmasın. Yüklü bir karakter bellekten, kayıtlı olan tek indeksli okumayla cevap verir.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.idOf

İmza
GetCharIdByCitizenId(citizenid: string, done: (charId: number | null) => void): void
Lua
exports['ai-core']:GetCharIdByCitizenId(citizenid, function(charId) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. Cevap done içinde gelir.

Örnek

import { characters } from "@aicore8/lib/server";

// Lib callback'i bir Promise'e sarar.
export async function fine(citizenid: string, amount: number): Promise<boolean> {
  const charId = await characters.idOf(citizenid);
  if (charId === null) return false;
  const result = await characters.removeMoney(charId, "bank", amount, "Hız cezası");
  return result.ok;
}

GetOfflineCharacter

ai-core'un bir karakter hakkında tuttuğu her şey: ad ve doğum tarihi, hesap başına para, meslekler, çeteler, metadata, kayıtlı konum, son kayıt ve karakter yüklüyse server id'si.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.get

İmza
GetOfflineCharacter(charId: number, done: (character: OfflineCharacter | null) => void): void
Lua
exports['ai-core']:GetOfflineCharacter(charId, function(character) end)

Parametreler

Dönüş değeri

Hiçbir şey. done bir OfflineCharacter ya da null alır. Yüklü bir karakter bellekten cevap verir; yani parası ve üyelikleri canlı olanlardır ve source oyuncudur.

Örnek

import { characters } from "@aicore8/lib/server";

export async function describe(charId: number): Promise<string> {
  const c = await characters.get(charId);
  if (!c) return "bilinmeyen karakter";
  const where = c.source === null ? "çevrimdışı" : `çevrimiçi, server id ${c.source}`;
  return `${c.info.firstname} ${c.info.lastname} (${where}), banka ${c.money.bank ?? 0}`;
}

SearchCharacters

Yazılan bir metne göre karakterler, yüklü olsun olmasın: ad ya da soyad başlangıcı ("jane doe" da olur), citizenid, fivem / license / discord id. Sayfa başına 25, en yeni karakter başta.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.search

İmza
SearchCharacters(text: string, done: (page: CharacterSearchPage) => void, cursor?: number): void
Lua
exports['ai-core']:SearchCharacters(text, function(page) end, cursor)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done bir CharacterSearchPage alır: en çok 25 eşleşme ve next cursor'ı (son sayfada null). Boş metin en yeni karakterleri döner, yani bir listeleme ekranı arama terimi olmadan da çalışır.

Örnek

import { characters, onClientCallback } from "@aicore8/lib/server";
import { oneArg, readText } from "@aicore8/lib/shared";

onClientCallback(
  "myscript:searchPeople",
  { args: oneArg((v) => readText(v, 64)), rate: { count: 10, windowMs: 10_000 } },
  async (_source, text) => {
    const page = await characters.search(text);
    return { ok: true, people: page.characters, next: page.next };
  },
);

GetCharactersOfUser

Bir hesabın her karakteri, slot sırasıyla. Bir oyuncuya bütün karakterlerini gösteren bir ekran ya da hesap üzerinde çalışan bir admin aracı için.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.ofUser

İmza
GetCharactersOfUser(user: number | string, done: (characters: StoredCharacter[]) => void): void
Lua
exports['ai-core']:GetCharactersOfUser(user, function(characters) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done bir StoredCharacter dizisi alır.

Örnek

import { characters, resourceExport } from "@aicore8/lib/server";

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

export async function slotsOf(source: number): Promise<number[]> {
  const userId = core.GetUserId(source);
  if (userId === null) return [];
  return (await characters.ofUser(userId)).map((c) => c.slot);
}

GetJobMembers and GetGangMembers

Bir mesleği tutan (ya da bir çetede olan) herkes, yüklü olsun olmasın, sayfa sayfa ve derecesiyle. Bir yönetim ekranının ihtiyaç duyduğu kadro budur: lib'in online aynası yalnızca bağlı oyuncuları bilir.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.jobMembers

İmza
GetJobMembers(job: string, done: (page: MembersPage) => void, after?: number, limit?: number): void
GetGangMembers(gang: string, done: (page: MembersPage) => void, after?: number, limit?: number): void
Lua
exports['ai-core']:GetJobMembers(job, function(page) end, after, limit)
exports['ai-core']:GetGangMembers(gang, function(page) end, after, limit)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done bir MembersPage alır: üyeler ve sonraki sayfanın after değeri (son sayfada null). Her üye source taşır, yani bağlı olanlar source değeri null olmayan kayıtlardır.

Örnek

import { characters } from "@aicore8/lib/server";

/** Bir mesleğin bütün üyeleri, sayfa sayfa. */
export async function roster(job: string) {
  const all = [];
  let after: number | undefined;
  do {
    const page = await characters.jobMembers(job, after);
    all.push(...page.members);
    after = page.next ?? undefined;
  } while (after !== undefined);
  return all;
}

Yalnızca "bu mesleği tutan var mı?" sorusu tek satır okur: lib characters.hasJobMember, bu export'u limit = 1 ile çağırır.

AddOfflineMoney, RemoveOfflineMoney and SetOfflineMoney

Bir karakterin parası, yüklü olsun olmasın. Yüklü bir karakter canlı cüzdanından geçer (oyuncu anında görür), kayıtlı olan aynı kurallarla ve aynı defter satırıyla veritabanında yazılır.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.addMoney

İmza
AddOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
RemoveOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
SetOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:AddOfflineMoney(charId, account, amount, reason, function(result) end)
exports['ai-core']:RemoveOfflineMoney(charId, account, amount, reason, function(result) end)
exports['ai-core']:SetOfflineMoney(charId, account, amount, reason, function(result) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done { ok: true } ya da bir dil anahtarıyla { ok: false, error } alır: bilinmeyen karakter, sunucuda olmayan bir hesap, ondalıklı ya da negatif miktar, veya RemoveOfflineMoney için ödemeye yetmeyen bakiye (hesap tipi sıfırın altına inmeye izin vermiyorsa).

Örnek

import { characters } from "@aicore8/lib/server";

/** Satıcı çevrimiçi olsun olmasın satış ödemesini yapar. */
export async function payOut(charId: number, amount: number): Promise<boolean> {
  const result = await characters.addMoney(charId, "bank", amount, "Araç satıldı");
  if (!result.ok) console.log(`ödeme reddedildi: ${result.error}`);
  return result.ok;
}

SetOfflineJob and RemoveOfflineJob

Bir karakteri işe alır, derecesini değiştirir ya da işten çıkarır; bağlı olsun olmasın. Panelin meslek kuralları geçerlidir (bir karakterin kaç meslek tutabileceği, ikinci mesleğe izin verilip verilmediği) ve işsizlik mesleği asla kaydedilmez: son mesleği kaldırmak bir karakteri işsiz yapar.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.setJob

İmza
SetOfflineJob(charId: number, job: string, grade: number, done?: (result: CharacterResult) => void): void
RemoveOfflineJob(charId: number, job: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineJob(charId, job, grade, function(result) end)
exports['ai-core']:RemoveOfflineJob(charId, job, function(result) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done { ok: true } ya da bir dil anahtarıyla { ok: false, error } alır: bilinmeyen karakter, bilinmeyen meslek, olmayan bir derece ya da panelin meslek sınırı.

Örnek

import { characters } from "@aicore8/lib/server";

/** Bir üyeyi meslekten çıkarır, çevrimiçi olsun olmasın. */
export async function fire(charId: number, job: string): Promise<boolean> {
  return (await characters.removeJob(charId, job)).ok;
}

SetOfflineGang and RemoveOfflineGang

Çeteler için aynısı. Bir karakter birkaç çetede olabilir ama bir seferde biri adına hareket eder (SetActiveGang bağlı bir oyuncu için onu seçer).

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.setGang

İmza
SetOfflineGang(charId: number, gang: string, grade: number, done?: (result: CharacterResult) => void): void
RemoveOfflineGang(charId: number, gang: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineGang(charId, gang, grade, function(result) end)
exports['ai-core']:RemoveOfflineGang(charId, gang, function(result) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done, mesleklerde olduğu gibi { ok: true } ya da { ok: false, error } alır.

SetOfflineMeta

Bir karakterin tek bir metadata değeri, yüklü olsun olmasın. Yüklü bir karakter bunu kendi oyununda bir delta olarak alır, yani HUD'u ve arayüzü anında takip eder.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.setMeta

İmza
SetOfflineMeta(charId: number, key: string, value: unknown, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineMeta(charId, key, value, function(result) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done { ok: true } ya da bilinmeyen karakter veya JSON'un tutamadığı bir değer için { ok: false, error } alır.

Örnek

import { characters } from "@aicore8/lib/server";

await characters.setMeta(12, "myscript_licence", { kind: "drive", since: Date.now() });
await characters.setMeta(12, "myscript_licence", null); // geri alır

Bağlı bir oyuncu için GetMeta / SetMeta daha kısa yoldur ve metadata okumak yalnızca orada mümkündür (bu sayfada GetOfflineMeta yok: karakterin tamamını GetOfflineCharacter ile oku ve metadata alanını al).

SetCharacterInfo

Karakterin kendi alanlarını değiştirir: ad, doğum tarihi, uyruk, cinsiyet ve boy. Her alan, karakter oluşturma formunun kontrol ettiği gibi kontrol edilir; yani bir admin aracı, oluşturucunun reddedeceği bir adı yazamaz.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.setInfo

İmza
SetCharacterInfo(charId: number, patch: CharacterInfoPatch, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetCharacterInfo(charId, patch, function(result) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done { ok: true } ya da bir dil anahtarıyla { ok: false, error } alır. Karakter yüklüyken sex reddedilir, çünkü ped modeli onu takip eder; geri kalan her şey yüklü karaktere delta olarak ulaşır.

Örnek

import { characters } from "@aicore8/lib/server";

const result = await characters.setInfo(12, { lastname: "Doe-Smith", height: 174 });
if (!result.ok) console.log(`ad değişikliği reddedildi: ${result.error}`);

DeleteCharacter

Bir karakteri siler. Bu yumuşak bir silmedir: satır loglar için kalır, karakter her listeden ve her aramadan kaybolur.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.remove

İmza
DeleteCharacter(charId: number, by?: number | string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:DeleteCharacter(charId, by, function(result) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. done { ok: true } ya da bilinmeyen karakter veya şu anda yüklü olan bir karakter için { ok: false, error } alır - oyuncunun önce karakter ekranına dönmesi gerekir. Başarıda ai-core characterDeleted event'ini tetikler; bkz. Event'ler ve durum.

GetPlayTime

Bir karakterin ne kadar oynandığı, saniye cinsinden: kayıtlı toplam artı süren oturum.

Taraf: Server · Bekler: bağlı bir oyuncu için hayır · Lib: characters.playTime

İmza
GetPlayTime(target: number | { charId: number }, done?: (seconds: number | null) => void): number | null
Lua
local seconds = exports['ai-core']:GetPlayTime(source) -- bağlı bir oyuncu: anında cevap verir
exports['ai-core']:GetPlayTime({ charId = 12 }, function(seconds) end)

Parametreler

Prop

Type

Dönüş değeri

number | null: veritabanı okuması olmadan bilinebiliyorsa saniye (bir server id ya da yüklü bir { charId }). null "burada yok, done'ı bekle" demektir - ya da bir server id için oyuncunun yüklü karakteri olmadığını.

SavePlayer

Bağlı bir oyuncunun konumunu ve metadata'sını hemen yazar ve bekleyen yazmalarını bekler. Son dakikaları kaybetmemesi gereken bir şeyden önce kullan: bir restart, bir devir, loglanan bir admin işlemi.

Taraf: Server · Bekler: hayır (cevap done içinde gelir) · Lib: characters.save

İmza
SavePlayer(source: number, done?: (ok: boolean) => void): void
Lua
exports['ai-core']:SavePlayer(source, function(ok) end)

Parametreler

Prop

Type

Dönüş değeri

Hiçbir şey. ai-core kendi kendine kaydeder (periyodik olarak, karakter çıkarken ve kapanışta); buna yalnızca yazmanın sıradaki adımından önce olmuş olmasını istediğinde ihtiyacın var.

Yüklü olmayan bir karakter zaten yazılmıştır: boşaltılacak bir şey yoktur. Kayıtlı bir karakterin doğma noktasını değiştirmek için characters.setOfflinePosition (SetOfflinePosition) kullan.

Bu sayfada