AI Core
Dokumentacja APILib: serwer

Postacie, wczytane albo nie

Moduł characters: znajdź, przeczytaj i zmień dowolną postać przez ai-core - pieniądze, prace, gangi, metadane, imię, czas gry - z Promise w TypeScripcie i zwykłym czekaniem w Lua.

TypeScript
import { characters } from "@aicore8/lib/server";
Lua
-- aiLib.characters, po shared_script '@ai-lib/init.lua'

characters to drzwi liba do eksportów zapisanych postaci ai-core. Istnieje, bo te eksporty odpowiadają przez callback: lib zamienia każdy z nich na Promise w TypeScripcie i na zwykłe czekanie w Lua, więc Twój kod czyta się od góry do dołu.

  • Postać nazywa się jej id postaci (charId, liczba). Z citizenid: characters.idOf.
  • Wczytana postać odpowiada z pamięci (aktualne pieniądze i przynależności); zapisana jest czytana z bazy, gdy ai-core ją trzyma, więc nie wczyta się w środku zapisu.
  • Każdy zapis odpowiada ActionResult: { ok: true } albo { ok: false, error } z kluczem językowym ai-core.
  • Każda funkcja tutaj czeka. W Lua znaczy to wołanie jej z wątku; zobacz Funkcje, które czekają.

Dla gracza, o którego chodzi w danej akcji, krótszą drogą jest zwykle ai-core bezpośrednio: GetCharacter, money, jobs. Użyj characters, gdy cel może być offline albo gdy potrzebujesz całej postaci naraz.

characters

characters.idOf

Id postaci stojące za citizenid.

Strona: Serwer · Czeka: tak

Sygnatura
characters.idOf(citizenid: string): Promise<number | null>

Bez odpowiednika w Lua: zawołaj eksport GetCharIdByCitizenId ai-core i poczekaj na jego callback.

Parametry

Prop

Type

Zwraca

Promise<number | null>: id postaci albo null, gdy żadna postać nie ma tego citizenid lub została usunięta.

Przykład

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

/** Mandat, który działa, czy kierowca jest online, czy nie. */
export async function fine(citizenid: string, amount: number): Promise<boolean> {
  const charId = await characters.idOf(citizenid);
  if (charId === null) return false;
  return (await characters.removeMoney(charId, "bank", amount, "Mandat")).ok;
}

characters.get

Jedna postać z wszystkim, co ai-core o niej trzyma: dane, pieniądze na konto, prace, gangi, metadane, zapisana pozycja, ostatni zapis i id serwera, gdy jest wczytana.

Strona: Serwer · Czeka: tak

Sygnatura
characters.get(charId: number): Promise<OfflineCharacter | null>
Lua
local character = aiLib.characters.get(charId) -- tabela albo nil

Parametry

Prop

Type

Zwraca

OfflineCharacter albo null / nil, gdy id jest nieznane lub postać została usunięta.

Przykład

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

export async function bankOf(charId: number): Promise<number> {
  const c = await characters.get(charId);
  return c?.money.bank ?? 0;
}

characters.search

Postacie po wpisanym tekście, wczytane albo nie: prefiksy imion ("jane doe" też), citizenid, id fivem / license / discord. 25 na stronę, najnowsze pierwsze.

Strona: Serwer · Czeka: tak

Sygnatura
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>
Lua
local page = aiLib.characters.search(text, cursor)

Parametry

Prop

Type

Zwraca

CharacterSearchPage: characters (do 25) i next (null na ostatniej stronie). Przy błędzie odpowiada pustą stroną, nigdy null.

Przykład

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

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

characters.ofUser

Wszystkie postacie jednego konta, po slocie.

Strona: Serwer · Czeka: tak

Sygnatura
characters.ofUser(user: number | string): Promise<StoredCharacter[]>
Lua
local list = aiLib.characters.ofUser(user)

Parametry

Prop

Type

Zwraca

Tablicę StoredCharacter, w kolejności slotów. Pustą dla nieznanego konta.

characters.jobMembers and characters.gangMembers

Wszyscy, którzy mają pracę albo są w gangu, wczytani albo nie - strona po stronie, ze stopniem i z id serwera, gdy są połączeni.

Strona: Serwer · Czeka: tak

Sygnatura
characters.jobMembers(job: string, after?: number, limit?: number): Promise<MembersPage>
characters.gangMembers(gang: string, after?: number, limit?: number): Promise<MembersPage>
Lua
local page = aiLib.characters.jobMembers(job, after, limit)
local page = aiLib.characters.gangMembers(gang, after, limit)

Parametry

Prop

Type

Zwraca

MembersPage: members i next (null na ostatniej stronie).

Przykład

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

/** Cała kadra 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;
}

Liczenie graczy połączonych w danej pracy to nie to: to lustro liba, online.jobMembers (bez wołania eksportu i bez czytania z bazy).

characters.hasJobMember

Czy ktokolwiek ma daną pracę, wczytany albo nie. Czytany jest jeden wiersz, więc jest dość tani na sprawdzenie przy starcie ("czy ten serwer ma policję?").

Strona: Serwer · Czeka: tak

Sygnatura
characters.hasJobMember(job: string): Promise<boolean>
Lua
local anyone = aiLib.characters.hasJobMember(job)

Zwraca

true, gdy co najmniej jedna postać ma tę pracę.

characters.addMoney, characters.removeMoney and characters.setMoney

Pieniądze postaci, wczytanej albo nie, z wierszem księgi. Wczytana postać idzie przez swój żywy portfel, więc gracz widzi zmianę od razu.

Strona: Serwer · Czeka: tak

Sygnatura
characters.addMoney(charId: number, account: string, amount: number, reason?: string): Promise<CharacterResult>
characters.removeMoney(charId: number, account: string, amount: number, reason?: string): Promise<CharacterResult>
characters.setMoney(charId: number, account: string, amount: number, reason?: string): Promise<CharacterResult>
Lua
local result = aiLib.characters.addMoney(charId, account, amount, reason)
local result = aiLib.characters.removeMoney(charId, account, amount, reason)
local result = aiLib.characters.setMoney(charId, account, amount, reason)

Parametry

Prop

Type

Zwraca

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

Przykład

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

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;
}

Przeniesienie pieniędzy między dwoma kontami to jedno wywołanie i jedna transakcja: money.transfer. Księga zapisanej postaci to money.history z { owner: "character", id, account }.

characters.setJob and characters.removeJob

Zatrudnia postać, zmienia jej stopień albo ją zwalnia, online albo nie. Obowiązują reguły prac z panelu, a praca bezrobotnego nigdy nie jest zapisywana: zabranie ostatniej pracy czyni postać bezrobotną.

Strona: Serwer · Czeka: tak

Sygnatura
characters.setJob(charId: number, job: string, grade: number): Promise<CharacterResult>
characters.removeJob(charId: number, job: string): Promise<CharacterResult>
Lua
local result = aiLib.characters.setJob(charId, job, grade)
local result = aiLib.characters.removeJob(charId, job)

Parametry

Prop

Type

Zwraca

{ ok: true } albo { ok: false, error }: nieznana postać, nieznana praca, nieznany stopień albo limit panelu, ile prac może mieć postać.

Przykład

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

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

characters.setGang and characters.removeGang

To samo dla gangów.

Strona: Serwer · Czeka: tak

Sygnatura
characters.setGang(charId: number, gang: string, grade: number): Promise<CharacterResult>
characters.removeGang(charId: number, gang: string): Promise<CharacterResult>
Lua
local result = aiLib.characters.setGang(charId, gang, grade)
local result = aiLib.characters.removeGang(charId, gang)

Zwraca

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

characters.setMeta

Jedna wartość metadanych postaci, wczytanej albo nie. Wczytana postać dostaje ją jako deltę na własnej grze.

Strona: Serwer · Czeka: tak

Sygnatura
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>
Lua
local result = aiLib.characters.setMeta(charId, key, value)

Parametry

Prop

Type

Zwraca

{ ok: true } albo { ok: false, error } przy nieznanej postaci lub wartości, której JSON nie uniesie. Czytanie metadanych jest częścią characters.get; dla połączonego gracza użyj GetMeta.

characters.setInfo

Imię, data urodzenia, narodowość, płeć i wzrost, każde sprawdzane tak, jak sprawdza je formularz tworzenia postaci.

Strona: Serwer · Czeka: tak

Sygnatura
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>
Lua
local result = aiLib.characters.setInfo(charId, patch)

Parametry

Prop

Type

Zwraca

{ ok: true } albo { ok: false, error } z kluczem językowym (imię, które tworzenie by odrzuciło, data nie w formacie YYYY-MM-DD, sex przy wczytanej postaci).

characters.remove

Usuwa postać (miękkie usunięcie: wiersz zostaje dla logów).

Strona: Serwer · Czeka: tak

Sygnatura
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>
Lua
local result = aiLib.characters.remove(charId, by)

Parametry

Prop

Type

Zwraca

{ ok: true } albo { ok: false, error } przy nieznanej postaci lub postaci wczytanej w tej chwili.

characters.playTime

Sekundy gry postaci: zapisana suma plus trwająca sesja.

Strona: Serwer · Czeka: tak

Sygnatura
characters.playTime(target: number | { charId: number }): Promise<number | null>
Lua
local seconds = aiLib.characters.playTime(target)

Parametry

Prop

Type

Zwraca

Sekundy albo null przy nieznanej postaci (lub id serwera bez wczytanej postaci).

characters.save

Zapisuje teraz pozycję i metadane połączonego gracza i czeka na jego zakolejkowane zapisy.

Strona: Serwer · Czeka: tak

Sygnatura
characters.save(source: number): Promise<boolean>
Lua
local ok = aiLib.characters.save(source)

Zwraca

true, gdy wszystko jest zapisane, false, gdy gracz nie ma wczytanej postaci. ai-core zapisuje sam (okresowo, przy wyładowaniu, przy wyłączaniu): użyj tego tylko wtedy, gdy zapis musi się wydarzyć przed Twoim następnym krokiem.

Gdzie indziej w libie

ChceszGdzie
Punkt spawnu zapisanej postacicharacters.setOfflinePosition
Kto jest teraz połączony, imiona, prace i służbaonline
Prace i gangi wczytanego graczajobs
Pieniądze wczytanego graczamoney
Księgę postacimoney.history

Na tej stronie