AI Core
API-ReferenzLib: Server

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.

TypeScript
import { characters } from "@aicore8/lib/server";
Lua
-- 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

Signature
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

Signature
characters.get(charId: number): Promise<OfflineCharacter | null>
Lua
local character = aiLib.characters.get(charId) -- Tabelle oder nil

Parameter

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

Signature
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>
Lua
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

Signature
characters.ofUser(user: number | string): Promise<StoredCharacter[]>
Lua
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

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

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

Signature
characters.hasJobMember(job: string): Promise<boolean>
Lua
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

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

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

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

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

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

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

Signature
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>
Lua
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

Signature
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>
Lua
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

Signature
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>
Lua
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

Signature
characters.playTime(target: number | { charId: number }): Promise<number | null>
Lua
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

Signature
characters.save(source: number): Promise<boolean>
Lua
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 willstWo
Den Spawnpunkt eines gespeicherten Charakterscharacters.setOfflinePosition
Wer jetzt verbunden ist, Namen, Jobs und Dienstonline
Jobs und Gangs eines geladenen Spielersjobs
Das Geld eines geladenen Spielersmoney
Das Ledger eines Charaktersmoney.history

Auf dieser Seite