AI Core
Dokumentacja APIAI Core: eksporty serwerowe

Zapisane postacie

Czytaj i zmieniaj dowolną postać, wczytaną albo nie - znajdź ją, przeczytaj, zmień jej pieniądze, prace, gangi, metadane i imię, zapisz ją, usuń ją.

Eksporty na stronie Postacie odpowiadają o graczu połączonym z wczytaną postacią. Te tutaj odpowiadają o każdej postaci, połączonej albo nie: ai-core czyta wczytaną postać z pamięci, a zapisaną z bazy danych, a zapis trafia do żywej postaci, gdy jest wczytana, i do wiersza, gdy nie jest.

Trzy rzeczy na początek:

  • Postać adresuje się jej id postaci (charId, liczba - CharacterInfo.id). citizenid to tekst i należy do bridge'y frameworków; przelicz jedno na drugie przez GetCharIdByCitizenId, nigdy ręcznie.
  • Te eksporty odpowiadają przez callback (done), bo zapisana postać wymaga czytania z bazy, a żadna Promise nie przekracza granicy resource'ów. W TypeScripcie moduł characters z liba daje Promise; w Lua aiLib.characters czeka za Ciebie.
  • Każdy zapis odpowiada ActionResult: { ok: true } albo { ok: false, error: "LANG_KEY" } z jednym z kluczy językowych ai-core (locales/en.json), który pokażesz przez callAction albo przetłumaczysz sam.

Nigdy nie czytaj i nie zapisuj tabel ai-core (ai_core_characters, ai_core_accounts, ai_core_character_jobs...) własnymi zapytaniami. Postacie żyją w pamięci i są zapisywane w rytmie ai-core, więc bezpośredni SELECT może być przedawniony, a kolumny są wewnętrzne.

GetCharIdByCitizenId

Id postaci stojące za citizenid, wczytanej albo nie. Wczytana postać odpowiada z pamięci, zapisana jednym indeksowanym czytaniem.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.idOf

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

Parametry

Prop

Type

Zwraca

Nic. Odpowiedź przychodzi w done.

Przykład

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

// Lib zawija callback w Promise.
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, "Mandat");
  return result.ok;
}

GetOfflineCharacter

Wszystko, co ai-core trzyma o postaci: imię i data urodzenia, pieniądze na konto, prace, gangi, metadane, zapisana pozycja, ostatni zapis i id serwera, gdy jest wczytana.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.get

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

Parametry

Zwraca

Nic. done dostaje OfflineCharacter albo null. Wczytana postać odpowiada z pamięci, więc jej pieniądze i przynależności są aktualne, a source to gracz.

Przykład

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

export async function describe(charId: number): Promise<string> {
  const c = await characters.get(charId);
  if (!c) return "nieznana postać";
  const where = c.source === null ? "offline" : `online jako ${c.source}`;
  return `${c.info.firstname} ${c.info.lastname} (${where}), bank ${c.money.bank ?? 0}`;
}

SearchCharacters

Postacie po wpisanym tekście, wczytane albo nie: prefiksy imienia lub nazwiska ("jane doe" też), citizenid, id fivem / license / discord. 25 na stronę, najnowsza postać pierwsza.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.search

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

Parametry

Prop

Type

Zwraca

Nic. done dostaje CharacterSearchPage: do 25 trafień i kursor next (null na ostatniej stronie). Pusty tekst odpowiada najnowszymi postaciami, więc ekran przeglądania działa bez frazy.

Przykład

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

Wszystkie postacie jednego konta, po slocie. Do ekranu, który pokazuje graczowi wszystkie jego postacie, albo do narzędzia admina działającego na koncie.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.ofUser

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

Parametry

Prop

Type

Zwraca

Nic. done dostaje tablicę StoredCharacter.

Przykład

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

Wszyscy, którzy mają pracę (albo są w gangu), wczytani albo nie, strona po stronie i ze swoim stopniem. To właśnie kadra, jakiej potrzebuje ekran zarządzania: lustro online z liba zna tylko graczy połączonych.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.jobMembers

Sygnatura
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)

Parametry

Prop

Type

Zwraca

Nic. done dostaje MembersPage: członków i after następnej strony (null na ostatniej). Każdy członek nosi source, więc połączeni to wpisy, w których source nie jest null.

Przykład

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

/** Wszyscy członkowie pracy, strona po stronie. */
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;
}

Samo pytanie "czy ktokolwiek ma tę pracę?" czyta jeden wiersz: lib characters.hasJobMember woła ten eksport z limit = 1.

AddOfflineMoney, RemoveOfflineMoney and SetOfflineMoney

Pieniądze postaci, wczytanej albo nie. Wczytana postać idzie przez swój żywy portfel (gracz widzi to od razu), zapisana jest zapisywana w bazie z tymi samymi regułami i tym samym wierszem księgi.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.addMoney

Sygnatura
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)

Parametry

Prop

Type

Zwraca

Nic. done dostaje { ok: true } albo { ok: false, error } z kluczem językowym: nieznana postać, konto, którego serwer nie ma, kwota niecałkowita lub ujemna, albo - w RemoveOfflineMoney - stan konta, który nie może zapłacić (chyba że typ konta może zejść poniżej zera).

Przykład

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

/** Wypłaca sprzedaż, czy sprzedający jest online, czy nie. */
export async function payOut(charId: number, amount: number): Promise<boolean> {
  const result = await characters.addMoney(charId, "bank", amount, "Pojazd sprzedany");
  if (!result.ok) console.log(`wypłata odrzucona: ${result.error}`);
  return result.ok;
}

SetOfflineJob and RemoveOfflineJob

Zatrudnia postać, zmienia jej stopień albo ją zwalnia, połączoną albo nie. Obowiązują reguły prac z panelu (ile prac może mieć postać, czy druga jest dozwolona), a praca bezrobotnego nigdy nie jest zapisywana: zabranie ostatniej pracy czyni postać bezrobotną.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.setJob

Sygnatura
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)

Parametry

Prop

Type

Zwraca

Nic. done dostaje { ok: true } albo { ok: false, error } z kluczem językowym: nieznana postać, nieznana praca, stopień, który nie istnieje, albo limit prac z panelu.

Przykład

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

/** Zwalnia członka, online albo nie. */
export async function fire(charId: number, job: string): Promise<boolean> {
  return (await characters.removeJob(charId, job)).ok;
}

SetOfflineGang and RemoveOfflineGang

To samo dla gangów. Postać może być w kilku gangach, ale działa dla jednego naraz (SetActiveGang wybiera go dla połączonego gracza).

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.setGang

Sygnatura
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)

Parametry

Prop

Type

Zwraca

Nic. done dostaje { ok: true } albo { ok: false, error }, jak przy pracach.

SetOfflineMeta

Jedna wartość metadanych postaci, wczytanej albo nie. Wczytana postać dostaje ją jako deltę na własnej grze, więc HUD i interfejs od razu nadążają.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.setMeta

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

Parametry

Prop

Type

Zwraca

Nic. done dostaje { ok: true } albo { ok: false, error } przy nieznanej postaci lub wartości, której JSON nie uniesie.

Przykład

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

await characters.setMeta(12, "myscript_licence", { kind: "drive", since: Date.now() });
await characters.setMeta(12, "myscript_licence", null); // zabiera ją

Dla gracza połączonego krótszą drogą jest GetMeta / SetMeta, i tylko tam da się metadane czytać (ta strona nie ma GetOfflineMeta: przeczytaj całą postać przez GetOfflineCharacter i weź metadata).

SetCharacterInfo

Zmienia własne pola postaci: imię, datę urodzenia, narodowość, płeć i wzrost. Każde pole jest sprawdzane tak, jak sprawdza je formularz tworzenia postaci, więc narzędzie admina nie zapisze imienia, które tworzenie by odrzuciło.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.setInfo

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

Parametry

Prop

Type

Zwraca

Nic. done dostaje { ok: true } albo { ok: false, error } z kluczem językowym. sex jest odrzucany, dopóki postać jest wczytana, bo model peda za nim idzie; wszystko inne trafia do wczytanej postaci jako delta.

Przykład

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

const result = await characters.setInfo(12, { lastname: "Doe-Smith", height: 174 });
if (!result.ok) console.log(`zmiana nazwiska odrzucona: ${result.error}`);

DeleteCharacter

Usuwa postać. To miękkie usunięcie: wiersz zostaje dla logów, a postać znika z każdej listy i z każdego wyszukiwania.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.remove

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

Parametry

Prop

Type

Zwraca

Nic. done dostaje { ok: true } albo { ok: false, error } przy nieznanej postaci lub postaci wczytanej w tej chwili - gracz musi najpierw wrócić na ekran postaci. Po sukcesie ai-core wywołuje swoje zdarzenie characterDeleted; zobacz Zdarzenia i stan.

GetPlayTime

Ile postać była grana, w sekundach: zapisana suma plus trwająca sesja.

Strona: Serwer · Czeka: nie dla połączonego gracza · Lib: characters.playTime

Sygnatura
GetPlayTime(target: number | { charId: number }, done?: (seconds: number | null) => void): number | null
Lua
local seconds = exports['ai-core']:GetPlayTime(source) -- połączony gracz: odpowiada od razu
exports['ai-core']:GetPlayTime({ charId = 12 }, function(seconds) end)

Parametry

Prop

Type

Zwraca

number | null: sekundy, gdy są znane bez czytania z bazy (id serwera albo wczytane { charId }). null znaczy "nie tutaj, czekaj na done" - albo, przy id serwera, że gracz nie ma wczytanej postaci.

SavePlayer

Zapisuje teraz pozycję i metadane połączonego gracza i czeka na jego zakolejkowane zapisy. Użyj przed czymś, co nie może stracić ostatnich minut: restart, przekazanie, akcja admina, którą logujesz.

Strona: Serwer · Czeka: nie (odpowiedź przychodzi w done) · Lib: characters.save

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

Parametry

Prop

Type

Zwraca

Nic. ai-core zapisuje sam (okresowo, przy wyładowaniu i przy wyłączaniu), więc potrzebujesz tego tylko wtedy, gdy zapis ma się wydarzyć przed Twoim następnym krokiem.

Postać, która nie jest wczytana, jest już zapisana: nie ma czego opróżniać. Żeby przesunąć punkt spawnu zapisanej postaci, użyj characters.setOfflinePosition (SetOfflinePosition).

Na tej stronie