Charaktere, geladen oder nicht
Das characters-Modul: jeden Charakter über ai-core finden, lesen und ändern - Geld, Jobs, Gangs, Metadaten, Name, Spielzeit - mit einer Promise in TypeScript und einfachem Warten in Lua.
import { characters } from "@aicore8/lib/server";-- aiLib.characters, nach shared_script '@ai-lib/init.lua'characters ist die Tür der Lib zu ai-cores Exports für gespeicherte Charaktere. Es gibt sie, weil diese Exports über einen Callback antworten: die Lib macht daraus in TypeScript eine Promise und in Lua ein einfaches Warten, dein Code liest sich also von oben nach unten.
- Ein Charakter wird über seine Charakter-ID (
charId, eine Zahl) benannt. Von einer citizenid aus:characters.idOf. - Ein geladener Charakter antwortet aus dem Speicher (lebendes Geld, lebende Mitgliedschaften); ein gespeicherter wird aus der Datenbank gelesen, während ai-core ihn hält, er kann also nicht mitten in einem Schreibvorgang laden.
- Jeder Schreibvorgang antwortet ActionResult:
{ ok: true }, oder{ ok: false, error }mit einem ai-core-Lang-Key. - Jede Funktion hier wartet. In Lua heißt das: aus einem Thread rufen; siehe Funktionen, die warten.
Für den Spieler, um den es gerade geht, ist der kürzere Weg oft ai-core direkt: GetCharacter, money, jobs. Nimm characters, wenn das Ziel offline sein kann oder du einen ganzen Charakter auf einmal brauchst.
characters
characters.idOf
Die Charakter-ID hinter einer citizenid.
Seite: Server · Wartet: ja
characters.idOf(citizenid: string): Promise<number | null>Kein Lua-Zwilling: ruf ai-cores Export GetCharIdByCitizenId und warte auf seinen Callback.
Parameter
Prop
Type
Rückgabe
Promise<number | null>: die Charakter-ID, oder null, wenn kein Charakter diese citizenid hat oder er gelöscht wurde.
Beispiel
import { characters } from "@aicore8/lib/server";
/** Ein Bußgeld, das wirkt, ob der Fahrer online ist oder nicht. */
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, "Bußgeld")).ok;
}characters.get
Ein Charakter mit allem, was ai-core über ihn führt: Infos, Geld pro Konto, Jobs, Gangs, Metadaten, gespeicherte Position, letztes Speichern, und die Server-ID, wenn er geladen ist.
Seite: Server · Wartet: ja
characters.get(charId: number): Promise<OfflineCharacter | null>local character = aiLib.characters.get(charId) -- Tabelle oder nilParameter
Prop
Type
Rückgabe
Ein OfflineCharacter, oder null / nil, wenn die ID unbekannt ist oder der Charakter gelöscht wurde.
Beispiel
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
Charaktere zu einem getippten Text, geladen oder nicht: Namenspräfixe ("jane doe" auch), citizenid, fivem- / license- / discord-ID. 25 pro Seite, neueste zuerst.
Seite: Server · Wartet: ja
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>local page = aiLib.characters.search(text, cursor)Parameter
Prop
Type
Rückgabe
Eine CharacterSearchPage: characters (bis zu 25) und next (null auf der letzten Seite). Bei einem Fehler antwortet sie eine leere Seite, nie null.
Beispiel
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
Jeder Charakter eines Accounts, nach Slot.
Seite: Server · Wartet: ja
characters.ofUser(user: number | string): Promise<StoredCharacter[]>local list = aiLib.characters.ofUser(user)Parameter
Prop
Type
Rückgabe
Ein Array von StoredCharacter, nach Slot. Leer für einen unbekannten Account.
characters.jobMembers and characters.gangMembers
Alle, die einen Job halten oder in einer Gang sind, geladen oder nicht - seitenweise, mit Grade und mit ihrer Server-ID, wenn sie verbunden sind.
Seite: Server · Wartet: ja
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)Parameter
Prop
Type
Rückgabe
Eine MembersPage: members und next (null auf der letzten Seite).
Beispiel
import { characters } from "@aicore8/lib/server";
/** Die ganze Belegschaft eines Jobs, Seite für Seite. */
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;
}Die verbundenen Spieler eines Jobs zu zählen ist das nicht: das ist der Spiegel der Lib, online.jobMembers (kein Export-Aufruf, kein Datenbanklesevorgang).
characters.hasJobMember
Ob überhaupt jemand einen Job hält, geladen oder nicht. Es wird eine Zeile gelesen, also billig genug für eine Prüfung beim Start ("hat dieser Server eine Polizei?").
Seite: Server · Wartet: ja
characters.hasJobMember(job: string): Promise<boolean>local anyone = aiLib.characters.hasJobMember(job)Rückgabe
true, wenn mindestens ein Charakter den Job hält.
characters.addMoney, characters.removeMoney and characters.setMoney
Geld eines Charakters, geladen oder nicht, mit einer Ledger-Zeile. Ein geladener Charakter geht über seine lebende Geldbörse, der Spieler sieht die Änderung also sofort.
Seite: Server · Wartet: ja
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)Parameter
Prop
Type
Rückgabe
{ ok: true }, oder { ok: false, error } mit einem Lang-Key: unbekannter Charakter, unbekanntes Konto, gebrochener oder negativer Betrag, oder ein Kontostand, der nicht zahlen kann (removeMoney, außer der Kontotyp darf unter null).
Beispiel
import { characters } from "@aicore8/lib/server";
export async function payOut(charId: number, amount: number): Promise<boolean> {
const result = await characters.addMoney(charId, "bank", amount, "Fahrzeug verkauft");
if (!result.ok) console.log(`Auszahlung abgelehnt: ${result.error}`);
return result.ok;
}Geld zwischen zwei Konten zu bewegen ist ein Aufruf und eine Transaktion: money.transfer. Das Ledger eines gespeicherten Charakters ist money.history mit { owner: "character", id, account }.
characters.setJob and characters.removeJob
Stellt einen Charakter ein, ändert seinen Grade oder entlässt ihn, online oder nicht. Die Jobregeln des Panels gelten, und der Arbeitslosen-Job wird nie gespeichert: den letzten Job zu entfernen macht den Charakter arbeitslos.
Seite: Server · Wartet: ja
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)Parameter
Prop
Type
Rückgabe
{ ok: true }, oder { ok: false, error }: unbekannter Charakter, unbekannter Job, unbekannter Grade, oder das Limit des Panels, wie viele Jobs ein Charakter halten darf.
Beispiel
import { characters } from "@aicore8/lib/server";
/** Ein Mitglied entlassen, ob online oder nicht. */
export async function fire(charId: number, job: string): Promise<boolean> {
return (await characters.removeJob(charId, job)).ok;
}characters.setGang and characters.removeGang
Dasselbe für Gangs.
Seite: Server · Wartet: ja
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)Rückgabe
{ ok: true } oder { ok: false, error }, wie bei Jobs.
characters.setMeta
Ein Metadaten-Wert eines Charakters, geladen oder nicht. Ein geladener Charakter bekommt ihn als Delta auf seinem eigenen Spiel.
Seite: Server · Wartet: ja
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>local result = aiLib.characters.setMeta(charId, key, value)Parameter
Prop
Type
Rückgabe
{ ok: true }, oder { ok: false, error } bei einem unbekannten Charakter oder einem Wert, den JSON nicht halten kann. Metadaten lesen ist Teil von characters.get; für einen verbundenen Spieler nimm GetMeta.
characters.setInfo
Name, Geburtsdatum, Nationalität, Geschlecht und Größe, jedes so geprüft, wie es das Charaktererstellungs-Formular prüft.
Seite: Server · Wartet: ja
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>local result = aiLib.characters.setInfo(charId, patch)Parameter
Prop
Type
Rückgabe
{ ok: true }, oder { ok: false, error } mit einem Lang-Key (ein Name, den die Erstellung ablehnen würde, ein Datum, das nicht YYYY-MM-DD ist, sex bei einem geladenen Charakter).
characters.remove
Löscht einen Charakter (Soft-Delete: die Zeile bleibt für die Logs).
Seite: Server · Wartet: ja
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>local result = aiLib.characters.remove(charId, by)Parameter
Prop
Type
Rückgabe
{ ok: true }, oder { ok: false, error } bei einem unbekannten Charakter oder einem gerade geladenen.
characters.playTime
Sekunden, die ein Charakter gespielt wurde: die gespeicherte Summe plus die laufende Sitzung.
Seite: Server · Wartet: ja
characters.playTime(target: number | { charId: number }): Promise<number | null>local seconds = aiLib.characters.playTime(target)Parameter
Prop
Type
Rückgabe
Die Sekunden, oder null bei einem unbekannten Charakter (oder einer Server-ID ohne geladenen Charakter).
characters.save
Schreibt Position und Metadaten eines verbundenen Spielers jetzt und wartet auf seine eingereihten Schreibvorgänge.
Seite: Server · Wartet: ja
characters.save(source: number): Promise<boolean>local ok = aiLib.characters.save(source)Rückgabe
true, sobald alles geschrieben ist, false, wenn der Spieler keinen geladenen Charakter hat. ai-core speichert von selbst (periodisch, beim Entladen, beim Herunterfahren): nimm das nur, wenn der Schreibvorgang vor deinem nächsten Schritt passiert sein muss.
Woanders in der Lib
| Du willst | Wo |
|---|---|
| Den Spawnpunkt eines gespeicherten Charakters | characters.setOfflinePosition |
| Wer jetzt verbunden ist, Namen, Jobs und Dienst | online |
| Jobs und Gangs eines geladenen Spielers | jobs |
| Das Geld eines geladenen Spielers | money |
| Das Ledger eines Charakters | money.history |
Spieler und Charaktere
online, onCharacter, notify, Spieler in der Nähe, Positionen und Speicher pro Spieler: PlayerMap, Cooldowns, KeyedCooldowns, SourceLock, RateLimit, KeyWatchers.
Items
inventory: Items geben, nehmen und zählen, Lager, Shops und benutzbare Items über das Inventar, das der Server betreibt.