AI Core
API-ReferenzAI Core: Server-Exports

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 wartet aiLib.characters fü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 mit callAction zeigen 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

Signature
GetCharIdByCitizenId(citizenid: string, done: (charId: number | null) => void): void
Lua
exports['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

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

Parameter

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

Signature
SearchCharacters(text: string, done: (page: CharacterSearchPage) => void, cursor?: number): void
Lua
exports['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

Signature
GetCharactersOfUser(user: number | string, done: (characters: StoredCharacter[]) => void): void
Lua
exports['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

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

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

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

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

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

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

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

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

Signature
SetOfflineMeta(charId: number, key: string, value: unknown, done?: (result: CharacterResult) => void): void
Lua
exports['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 weg

Fü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

Signature
SetCharacterInfo(charId: number, patch: CharacterInfoPatch, done?: (result: CharacterResult) => void): void
Lua
exports['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

Signature
DeleteCharacter(charId: number, by?: number | string, done?: (result: CharacterResult) => void): void
Lua
exports['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

Signature
GetPlayTime(target: number | { charId: number }, done?: (seconds: number | null) => void): number | null
Lua
local 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

Signature
SavePlayer(source: number, done?: (ok: boolean) => void): void
Lua
exports['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).

Auf dieser Seite