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.
import { characters } from "@aicore8/lib/server";-- 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
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
characters.get(charId: number): Promise<OfflineCharacter | null>local character = aiLib.characters.get(charId) -- tabela albo nilParametry
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
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>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
characters.ofUser(user: number | string): Promise<StoredCharacter[]>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
characters.jobMembers(job: string, after?: number, limit?: number): Promise<MembersPage>
characters.gangMembers(gang: string, after?: number, limit?: number): Promise<MembersPage>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
characters.hasJobMember(job: string): Promise<boolean>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
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>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
characters.setJob(charId: number, job: string, grade: number): Promise<CharacterResult>
characters.removeJob(charId: number, job: string): Promise<CharacterResult>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
characters.setGang(charId: number, gang: string, grade: number): Promise<CharacterResult>
characters.removeGang(charId: number, gang: string): Promise<CharacterResult>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
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>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
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>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
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>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
characters.playTime(target: number | { charId: number }): Promise<number | null>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
characters.save(source: number): Promise<boolean>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
| Chcesz | Gdzie |
|---|---|
| Punkt spawnu zapisanej postaci | characters.setOfflinePosition |
| Kto jest teraz połączony, imiona, prace i służba | online |
| Prace i gangi wczytanego gracza | jobs |
| Pieniądze wczytanego gracza | money |
| Księgę postaci | money.history |
Gracze i postacie
online, onCharacter, notify, gracze w pobliżu, pozycje i magazyny na gracza: PlayerMap, Cooldowns, KeyedCooldowns, SourceLock, RateLimit, KeyWatchers.
Przedmioty
inventory: dawanie, zabieranie i liczenie przedmiotów, schowki, sklepy i przedmioty używalne przez dowolny ekwipunek, którego używa serwer.