Gespeicherte Charaktere
Jeden Charakter lesen und ändern, geladen oder nicht - finden, lesen, Geld, Jobs, Gangs, Metadaten und Namen ändern, speichern, löschen.
Die Exports auf Charaktere antworten über einen Spieler, der mit einem geladenen Charakter verbunden ist. Die hier antworten über jeden Charakter, verbunden oder nicht: ai-core liest einen geladenen Charakter aus dem Speicher und einen gespeicherten aus der Datenbank, und ein Schreibvorgang erreicht den lebenden Charakter, wenn er geladen ist, und sonst die Zeile.
Drei Dinge vorab:
- Ein Charakter wird über seine Charakter-ID angesprochen (
charId, eine Zahl -CharacterInfo.id). Eine citizenid ist Text und gehört den Framework-Bridges; rechne die eine mit GetCharIdByCitizenId in die andere um, niemals selbst. - Diese Exports antworten über einen Callback (
done), weil ein gespeicherter Charakter einen Datenbanklesevorgang braucht und keine Promise die Resource-Grenze überschreitet. In TypeScript gibt dir das Lib-Modul characters stattdessen eine Promise; in Lua wartetaiLib.charactersfür dich. - Jeder Schreibvorgang antwortet ActionResult:
{ ok: true }, oder{ ok: false, error: "LANG_KEY" }mit einem von ai-cores eigenen Lang-Keys (locales/en.json), den du mitcallActionzeigen oder selbst übersetzen kannst.
Lies und schreibe ai-cores Tabellen (ai_core_characters, ai_core_accounts, ai_core_character_jobs...) niemals mit eigenen Queries. Charaktere liegen im Speicher und werden nach ai-cores Plan geschrieben, ein direktes SELECT kann also veraltet sein, und die Spalten sind intern.
GetCharIdByCitizenId
Die Charakter-ID hinter einer citizenid, geladen oder nicht. Ein geladener Charakter antwortet aus dem Speicher, ein gespeicherter mit einem indizierten Lesevorgang.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.idOf
GetCharIdByCitizenId(citizenid: string, done: (charId: number | null) => void): voidexports['ai-core']:GetCharIdByCitizenId(citizenid, function(charId) end)Parameter
Prop
Type
Rückgabe
Nichts. Die Antwort kommt in done.
Beispiel
import { characters } from "@aicore8/lib/server";
// Die Lib verpackt den Callback in eine 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, "Bußgeld");
return result.ok;
}GetOfflineCharacter
Alles, was ai-core über einen Charakter führt: Name und Geburtsdatum, Geld pro Konto, Jobs, Gangs, Metadaten, gespeicherte Position, letztes Speichern, und die Server-ID, wenn er geladen ist.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.get
GetOfflineCharacter(charId: number, done: (character: OfflineCharacter | null) => void): voidexports['ai-core']:GetOfflineCharacter(charId, function(character) end)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt einen OfflineCharacter oder null. Ein geladener Charakter antwortet aus dem Speicher, sein Geld und seine Mitgliedschaften sind also die lebenden, und source ist der Spieler.
Beispiel
import { characters } from "@aicore8/lib/server";
export async function describe(charId: number): Promise<string> {
const c = await characters.get(charId);
if (!c) return "unbekannter Charakter";
const where = c.source === null ? "offline" : `online als ${c.source}`;
return `${c.info.firstname} ${c.info.lastname} (${where}), Bank ${c.money.bank ?? 0}`;
}SearchCharacters
Charaktere zu einem getippten Text, geladen oder nicht: Vor- oder Nachname als Präfix ("jane doe" geht auch), citizenid, fivem- / license- / discord-ID. 25 pro Seite, der neueste Charakter zuerst.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.search
SearchCharacters(text: string, done: (page: CharacterSearchPage) => void, cursor?: number): voidexports['ai-core']:SearchCharacters(text, function(page) end, cursor)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt eine CharacterSearchPage: bis zu 25 Treffer und den next-Cursor (null auf der letzten Seite). Ein leerer Text antwortet die neuesten Charaktere, ein Browse-Screen funktioniert also ohne Suchbegriff.
Beispiel
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
Jeder Charakter eines Accounts, nach Slot. Für einen Screen, der einem Spieler alle seine Charaktere zeigt, oder für ein Admin-Werkzeug, das auf einem Account arbeitet.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.ofUser
GetCharactersOfUser(user: number | string, done: (characters: StoredCharacter[]) => void): voidexports['ai-core']:GetCharactersOfUser(user, function(characters) end)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt ein Array von StoredCharacter.
Beispiel
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
Alle, die einen Job halten (oder in einer Gang sind), geladen oder nicht, seitenweise und mit ihrem Grade. Das ist die Belegschaft, die ein Verwaltungs-Screen braucht: der online-Spiegel der Lib kennt nur die verbundenen Spieler.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.jobMembers
GetJobMembers(job: string, done: (page: MembersPage) => void, after?: number, limit?: number): void
GetGangMembers(gang: string, done: (page: MembersPage) => void, after?: number, limit?: number): voidexports['ai-core']:GetJobMembers(job, function(page) end, after, limit)
exports['ai-core']:GetGangMembers(gang, function(page) end, after, limit)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt eine MembersPage: die Mitglieder und das after der nächsten Seite (null auf der letzten). Jedes Mitglied trägt source, die verbundenen sind also die Einträge, deren source nicht null ist.
Beispiel
import { characters } from "@aicore8/lib/server";
/** Jedes Mitglied 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;
}Nur die Frage "hält überhaupt jemand diesen Job?" liest eine Zeile: Lib characters.hasJobMember ruft diesen Export mit limit = 1.
AddOfflineMoney, RemoveOfflineMoney and SetOfflineMoney
Geld eines Charakters, geladen oder nicht. Ein geladener Charakter geht über seine lebende Geldbörse (der Spieler sieht es sofort), ein gespeicherter wird mit denselben Regeln und derselben Ledger-Zeile in der Datenbank geschrieben.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.addMoney
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): voidexports['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)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt { ok: true }, oder { ok: false, error } mit einem Lang-Key: unbekannter Charakter, ein Konto, das der Server nicht hat, ein gebrochener oder negativer Betrag, oder - bei RemoveOfflineMoney - ein Kontostand, der nicht zahlen kann (außer der Kontotyp darf unter null gehen).
Beispiel
import { characters } from "@aicore8/lib/server";
/** Zahlt einen Verkauf aus, ob der Verkäufer online ist oder nicht. */
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;
}SetOfflineJob and RemoveOfflineJob
Stellt einen Charakter ein, ändert seinen Grade oder entlässt ihn, verbunden oder nicht. Die Jobregeln des Panels gelten (wie viele Jobs ein Charakter halten darf, ob ein zweiter erlaubt ist), und der Arbeitslosen-Job wird nie gespeichert: den letzten Job zu entfernen macht einen Charakter arbeitslos.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.setJob
SetOfflineJob(charId: number, job: string, grade: number, done?: (result: CharacterResult) => void): void
RemoveOfflineJob(charId: number, job: string, done?: (result: CharacterResult) => void): voidexports['ai-core']:SetOfflineJob(charId, job, grade, function(result) end)
exports['ai-core']:RemoveOfflineJob(charId, job, function(result) end)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt { ok: true }, oder { ok: false, error } mit einem Lang-Key: unbekannter Charakter, unbekannter Job, ein Grade, den es nicht gibt, oder das Joblimit des Panels.
Beispiel
import { characters } from "@aicore8/lib/server";
/** Entlässt ein Mitglied, online oder nicht. */
export async function fire(charId: number, job: string): Promise<boolean> {
return (await characters.removeJob(charId, job)).ok;
}SetOfflineGang and RemoveOfflineGang
Dasselbe für Gangs. Ein Charakter kann in mehreren Gangs sein, handelt aber für eine zur Zeit (SetActiveGang wählt sie für einen verbundenen Spieler).
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.setGang
SetOfflineGang(charId: number, gang: string, grade: number, done?: (result: CharacterResult) => void): void
RemoveOfflineGang(charId: number, gang: string, done?: (result: CharacterResult) => void): voidexports['ai-core']:SetOfflineGang(charId, gang, grade, function(result) end)
exports['ai-core']:RemoveOfflineGang(charId, gang, function(result) end)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt { ok: true } oder { ok: false, error }, wie bei Jobs.
SetOfflineMeta
Ein Metadaten-Wert eines Charakters, geladen oder nicht. Ein geladener Charakter bekommt ihn als Delta auf seinem eigenen Spiel, HUD und UI folgen also sofort.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.setMeta
SetOfflineMeta(charId: number, key: string, value: unknown, done?: (result: CharacterResult) => void): voidexports['ai-core']:SetOfflineMeta(charId, key, value, function(result) end)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt { ok: true }, oder { ok: false, error } bei einem unbekannten Charakter oder einem Wert, den JSON nicht halten kann.
Beispiel
import { characters } from "@aicore8/lib/server";
await characters.setMeta(12, "myscript_licence", { kind: "drive", since: Date.now() });
await characters.setMeta(12, "myscript_licence", null); // nimmt sie wegFür einen verbundenen Spieler ist GetMeta / SetMeta der kürzere Weg, und Metadaten lesen geht nur dort (diese Seite hat kein GetOfflineMeta: lies den ganzen Charakter mit GetOfflineCharacter und nimm metadata daraus).
SetCharacterInfo
Ändert die eigenen Felder des Charakters: Name, Geburtsdatum, Nationalität, Geschlecht und Größe. Jedes Feld wird so geprüft, wie es das Charaktererstellungs-Formular prüft, ein Admin-Werkzeug kann also keinen Namen schreiben, den die Erstellung ablehnen würde.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.setInfo
SetCharacterInfo(charId: number, patch: CharacterInfoPatch, done?: (result: CharacterResult) => void): voidexports['ai-core']:SetCharacterInfo(charId, patch, function(result) end)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt { ok: true }, oder { ok: false, error } mit einem Lang-Key. sex wird abgelehnt, während der Charakter geladen ist, weil das Ped-Modell ihm folgt; alles andere erreicht einen geladenen Charakter als Delta.
Beispiel
import { characters } from "@aicore8/lib/server";
const result = await characters.setInfo(12, { lastname: "Doe-Smith", height: 174 });
if (!result.ok) console.log(`Namensänderung abgelehnt: ${result.error}`);DeleteCharacter
Löscht einen Charakter. Es ist ein Soft-Delete: die Zeile bleibt für die Logs, und der Charakter verschwindet aus jeder Liste und jeder Suche.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.remove
DeleteCharacter(charId: number, by?: number | string, done?: (result: CharacterResult) => void): voidexports['ai-core']:DeleteCharacter(charId, by, function(result) end)Parameter
Prop
Type
Rückgabe
Nichts. done bekommt { ok: true }, oder { ok: false, error } bei einem unbekannten Charakter oder einem gerade geladenen - der Spieler muss zuerst auf den Charakterbildschirm zurück. Bei Erfolg feuert ai-core sein characterDeleted-Event; siehe Events und State.
GetPlayTime
Wie lange ein Charakter gespielt wurde, in Sekunden: die gespeicherte Summe plus die laufende Sitzung.
Seite: Server · Wartet: nein für einen verbundenen Spieler · Lib: characters.playTime
GetPlayTime(target: number | { charId: number }, done?: (seconds: number | null) => void): number | nulllocal seconds = exports['ai-core']:GetPlayTime(source) -- ein verbundener Spieler: antwortet sofort
exports['ai-core']:GetPlayTime({ charId = 12 }, function(seconds) end)Parameter
Prop
Type
Rückgabe
number | null: die Sekunden, wenn sie ohne Datenbanklesevorgang bekannt sind (eine Server-ID, oder ein geladenes { charId }). null heißt "nicht hier, warte auf done" - oder, bei einer Server-ID, dass der Spieler keinen geladenen Charakter hat.
SavePlayer
Schreibt Position und Metadaten eines verbundenen Spielers jetzt und wartet auf seine eingereihten Schreibvorgänge. Nimm es vor etwas, das die letzten Minuten nicht verlieren darf: ein Restart, eine Übergabe, eine Admin-Aktion, die du loggst.
Seite: Server · Wartet: nein (die Antwort kommt in done) · Lib: characters.save
SavePlayer(source: number, done?: (ok: boolean) => void): voidexports['ai-core']:SavePlayer(source, function(ok) end)Parameter
Prop
Type
Rückgabe
Nichts. ai-core speichert von selbst (periodisch, beim Entladen, beim Herunterfahren), du brauchst das also nur, wenn der Schreibvorgang vor deinem nächsten Schritt passiert sein soll.
Ein Charakter, der nicht geladen ist, ist schon geschrieben: es gibt nichts zu leeren. Um den Spawnpunkt eines gespeicherten Charakters zu verschieben, nimm characters.setOfflinePosition (SetOfflinePosition).
Charaktere und Spieler
Die Daten und den Charakter eines geladenen Spielers lesen, einen Spieler per Charakter-ID oder Citizen-ID finden, den Charakter wechseln, einen Offline-Charakter versetzen, Spieler in Reichweite.
Geld und Konten
Die Kontostände eines Spielers sowie Job- und Gang-Konten lesen und ändern, Geld in einer Transaktion zwischen zwei Konten bewegen, die Kontotypen lesen.