AI Core
API-ReferenzLib: Server

Geld und Banking

money.transfer zwischen zwei Konten, das Banking-Skript über ai-core und Rechnungen über das jeweils laufende Rechnungs-Skript.

TypeScript
import { money, banking, billing } from "@aicore8/lib/server";

money ist jeder Kontostand auf dem Server: die Konten eines geladenen Spielers, das gemeinsame Konto eines Jobs oder einer Gang, ein Transfer, der Geld in einer Transaktion bewegt, und das Ledger. Ein Charakter, der nicht verbunden ist, geht über characters. banking und billing sind die Layer für die Bank- und Rechnungs-Scripts des Servers.

money

money.get

Der Kontostand eines geladenen Spielers in einem Konto.

Seite: Server · Wartet: nein

Signature
money.get(source: number, account: string): number | null
Lua
local balance = aiLib.money.get(source, account)

Parameter

Prop

Type

Rückgabe

number | null: der Kontostand, oder null, wenn der Spieler keinen geladenen Charakter hat oder der Kontotyp nicht existiert. Die Kontostände eines gespeicherten Charakters kommen aus characters.get.

Beispiel

import { money, notify } from "@aicore8/lib/server";

export function tellBalance(source: number): void {
  const bank = money.get(source, "bank");
  notify(source, bank === null ? "Kein Charakter" : `Bank: $${bank}`, bank === null ? "error" : "inform");
}

money.add, money.remove and money.set

Ändert ein Konto eines geladenen Spielers, mit einer Ledger-Zeile. Das sind die Aufrufe für eine Belohnung, einen Preis, ein Gehalt, das dein Script zahlt.

Seite: Server · Wartet: nein

Signature
money.add(source: number, account: string, amount: number, reason?: string): boolean
money.remove(source: number, account: string, amount: number, reason?: string): boolean
money.set(source: number, account: string, amount: number, reason?: string): boolean
Lua
local ok = aiLib.money.add(source, account, amount, reason)
local ok = aiLib.money.remove(source, account, amount, reason)
local ok = aiLib.money.set(source, account, amount, reason)

Parameter

Prop

Type

Rückgabe

boolean: true, wenn die Änderung gemacht wurde. false, wenn der Spieler keinen geladenen Charakter hat, das Konto nicht existiert, der Betrag keine ganze Zahl über 0 ist, oder - bei remove - der Kontostand nicht zahlen kann (außer der Kontotyp darf unter null gehen).

Beispiel

import { money, onClientCallback } from "@aicore8/lib/server";
import { fail } from "@aicore8/lib/shared";

onClientCallback("myshop:buyTools", { lock: true }, (source) => {
  if (!money.remove(source, "cash", 150, "shop:tools")) return fail("NOT_ENOUGH_CASH");
  // hier das Item geben
  return { ok: true };
});

Einen Spieler von einem anderen bezahlen zu lassen ist kein remove plus add: ein Fehler in der Mitte würde Geld erschaffen oder vernichten. Nimm money.transfer, das eine Datenbanktransaktion ist.

money.sharedGet

Der Kontostand eines Job- oder Gang-Kontos - bank ist, was andere Frameworks Society-Geld nennen.

Seite: Server · Wartet: nein

Signature
money.sharedGet(type: "job" | "gang", id: string, account: string): number | null
Lua
local balance = aiLib.money.sharedGet(type, id, account)

Parameter

Prop

Type

Rückgabe

number | null: der Kontostand, oder null, wenn dieser Job oder diese Gang kein solches Konto hat (ein unbekannter Job, oder ein Kontotyp, den der Server nicht hat).

money.sharedAdd and money.sharedRemove

Ändert ein Job- oder Gang-Konto, mit einer Ledger-Zeile - die Einnahmen und Kosten einer Firma.

Seite: Server · Wartet: nein

Signature
money.sharedAdd(type: "job" | "gang", id: string, account: string, amount: number, reason?: string): boolean
money.sharedRemove(type: "job" | "gang", id: string, account: string, amount: number, reason?: string): boolean
Lua
local ok = aiLib.money.sharedAdd(type, id, account, amount, reason)
local ok = aiLib.money.sharedRemove(type, id, account, amount, reason)

Rückgabe

boolean: true, wenn die Änderung gemacht wurde, false bei einem unbekannten Job oder einer unbekannten Gang, einem fehlenden Konto, einem falschen Betrag, oder einem Konto, das nicht zahlen kann.

Beispiel

import { money } from "@aicore8/lib/server";

/** Ein Stadtauftrag, den die Werkstatt verdient, und die Gebühr, die sie für Teile zahlt. */
export function contractDone(job: string, pay: number, parts: number): boolean {
  if (!money.sharedAdd("job", job, "bank", pay, "city contract")) return false;
  return money.sharedRemove("job", job, "bank", parts, "parts");
}

money.transfer

Bewegt Geld in einer einzigen Datenbanktransaktion von einem Konto auf ein anderes, mit einer Buchungszeile auf beiden Seiten. Nutze es für alles, bei dem Geld nicht auf halbem Weg auftauchen oder verschwinden darf: einen anderen Spieler bezahlen, ein Job zahlt einen Bonus, eine Gebühr.

Seite: Server · Wartet: nein

Signatur
money.transfer(from: MoneyRef, to: MoneyRef, amount: number, reason?: string, fee?: number): boolean
Lua
local ok = aiLib.money.transfer(from, to, amount, reason, fee)

Parameter

Prop

Type

Rückgabewert

boolean: true, wenn beide Zeilen geschrieben wurden. false, wenn ein Betrag keine ganze Zahl ist, ein Konto fehlt, beide gleich sind oder from amount plus fee nicht zahlen kann.

Beispiel

import { onClientCallback, money, nearestPlayerTo, notify } from "@aicore8/lib/server";
import { fail, oneArg, readInt } from "@aicore8/lib/shared";

onClientCallback("my-cash:give", { args: oneArg((v) => readInt(v, 1, 100_000)), lock: true }, (source, amount) => {
  const target = nearestPlayerTo(source, 2);
  if (target === null) return fail("NOBODY_NEAR");
  if (!money.transfer({ source, account: "cash" }, { source: target, account: "cash" }, amount, "give:cash"))
    return fail("NOT_ENOUGH_CASH");
  notify(target, `You received $${amount}`, "success");
  return { ok: true };
});

money.history

Die Ledger-Zeilen eines Kontos, neueste zuerst: was sich bewegt hat, der Kontostand danach, der Grund, wer es gemacht hat und wann. Funktioniert für das Konto eines Spielers, ein Job- oder Gang-Konto und das Konto eines gespeicherten Charakters.

Seite: Server · Wartet: ja

Signature
money.history(account: LedgerRef, query?: LedgerQuery): Promise<LedgerPage>
Lua
local page = aiLib.money.history(account, query)

Parameter

Prop

Type

Rückgabe

Eine LedgerPage: rows und das next, das du als before übergibst (null auf der letzten Seite). ai-core schreibt eine Zeile einen Moment nach der Änderung, die neueste kann dem Kontostand also um ein paar Millisekunden nachhängen.

Beispiel

import { money } from "@aicore8/lib/server";

/** Die letzten 20 Bankzeilen eines gespeicherten Charakters. */
export async function statement(charId: number) {
  const page = await money.history({ owner: "character", id: String(charId), account: "bank" }, { limit: 20 });
  return page.rows.map((r) => `${r.at}: ${r.amount} (${r.reason})`);
}

banking

banking spricht über die Banking-Ebene von ai-core mit dem Banking-Skript. Job-Geld selbst bewegt sich immer über money oder die Exports von ai-core.

banking.open

Öffnet den Bildschirm des Banking-Skripts für einen Spieler.

Seite: Server · Wartet: nein

Signatur
banking.open(source: number): boolean
Lua
local ok = aiLib.banking.open(source)

Rückgabewert: true, wenn geöffnet. false, wenn das Skript nicht von außen geöffnet werden kann oder keins läuft.

onClientCallback("my-atm:open", (source) => (banking.open(source) ? { ok: true } : fail("BANK_UNAVAILABLE")));

banking.societyBalance

Der Society-Kontostand eines Jobs, zur Anzeige. Im core-Kontomodus von ai-core ist es das Job-Konto von ai-core; im own-Modus das eigene des Banking-Skripts.

Seite: Server · Wartet: nein

Signatur
banking.societyBalance(job: string): number | null
Lua
local balance = aiLib.banking.societyBalance(job) -- number oder nil

Rückgabewert: der Kontostand, oder null (Lua nil), wenn keins läuft oder das Skript keinen führt.

const balance = banking.societyBalance("mechanic") ?? 0;

banking.provider

Seite: Server · Wartet: nein

Signatur
banking.provider(): string | null
Lua
local name = aiLib.banking.provider()

Rückgabewert: das Banking-Skript, das die Ebene nutzt, oder null.

console.log(`banking through ${banking.provider() ?? "nothing"}`);

billing

billing sendet Rechnungen über das jeweils laufende Rechnungs-Skript; ohne eines die eigenen Rechnungen von ai-core (der Spieler zahlt aus einer Liste auf dem Bildschirm, das Geld bewegt sich, wenn er zahlt). Texte sind bereits übersetzt.

billing.send

Sendet eine Rechnung von einem Job (Bußgelder, Servicegebühren) oder von einem Spieler.

Seite: Server · Wartet: nein

Signatur
billing.send(bill: BillRequest): boolean
Lua
local ok = aiLib.billing.send(bill)

BillRequest

Prop

Type

Rückgabewert

boolean: true, wenn gesendet, false, wenn ungültig oder abgelehnt.

Beispiel

import { billing, nearestPlayerTo, online } from "@aicore8/lib/server";
import { fail } from "@aicore8/lib/shared";

function fine(officer: number, amount: number) {
  if (!online.onDutyIn(officer, ["police"])) return fail("NOT_ON_DUTY");
  const target = nearestPlayerTo(officer, 3);
  if (target === null) return fail("NOBODY_NEAR");
  return billing.send({ to: target, amount, label: "Speeding", from: officer, job: "police" })
    ? { ok: true }
    : fail("BILL_FAILED");
}

billing.unpaid

Die offenen Rechnungen des Spielers.

Seite: Server · Wartet: ja (Promise in TypeScript, hält in Lua den Thread an)

Signatur
billing.unpaid(source: number): Promise<UnpaidBill[] | null>
Lua
local bills = aiLib.billing.unpaid(source) -- table[] oder nil, innerhalb eines Threads aufrufen

Rückgabewert: UnpaidBill[] (id, label, noch geschuldeter amount, sender), oder null, wenn das Rechnungs-Skript sie nicht auflisten kann.

const bills = await billing.unpaid(source);
const owed = bills?.reduce((sum, bill) => sum + bill.amount, 0) ?? 0;

billing.pay

Der Spieler bezahlt eine seiner offenen Rechnungen.

Seite: Server · Wartet: nein

Signatur
billing.pay(source: number, id: string): boolean
Lua
local ok = aiLib.billing.pay(source, id)

Prop

Type

Rückgabewert: true, wenn bezahlt. false, wenn abgelehnt (nicht genug Geld, unbekannte Rechnung) oder das Rechnungs-Skript Zahlungen nur in seinem eigenen Bildschirm annimmt.

if (!billing.pay(source, billId)) return fail("PAY_FAILED");

billing.provider

Seite: Server · Wartet: nein

Signatur
billing.provider(): string | null
Lua
local name = aiLib.billing.provider()

Rückgabewert: das Rechnungs-Skript, an das Rechnungen gehen, "ai-core" für die eigenen Rechnungen von ai-core.

if (billing.provider() === "ai-core") console.log("using ai-core's own bills");

Auf dieser Seite