AI Core
Référence de l’APILib : serveur

Argent et banque

money.transfer entre deux comptes, le script bancaire via ai-core, et les factures via le script de facturation qui tourne.

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

money est tout solde sur le serveur : les comptes d'un joueur chargé, le compte partagé d'un métier ou d'un gang, un transfert qui déplace l'argent en une seule transaction, et le registre. Un personnage qui n'est pas connecté passe par characters. banking et billing sont les couches pour les scripts de banque et de factures du serveur.

money

money.get

Le solde d'un joueur chargé dans un compte.

Côté : serveur · Attend : non

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

Paramètres

Prop

Type

Retour

number | null : le solde, ou null si le joueur n'a pas de personnage chargé ou si le type de compte n'existe pas. Les soldes d'un personnage stocké viennent de characters.get.

Exemple

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

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

money.add, money.remove and money.set

Change un compte d'un joueur chargé, avec une ligne de registre. Ce sont les appels pour une récompense, un prix, un salaire que votre script paie.

Côté : serveur · Attend : non

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)

Paramètres

Prop

Type

Retour

boolean : true quand le changement a eu lieu. false si le joueur n'a pas de personnage chargé, si le compte n'existe pas, si le montant n'est pas un entier au-dessus de 0, ou - pour remove - si le solde ne peut pas payer (sauf si le type de compte peut passer sous zéro).

Exemple

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");
  // donner l'objet ici
  return { ok: true };
});

Faire payer un joueur par un autre n'est pas un remove plus un add : une erreur au milieu ferait apparaître ou disparaître de l'argent. Utilisez money.transfer, qui est une seule transaction.

money.sharedGet

Le solde du compte d'un métier ou d'un gang - bank est ce que les autres frameworks appellent l'argent de société.

Côté : serveur · Attend : non

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

Paramètres

Prop

Type

Retour

number | null : le solde, ou null quand ce métier ou ce gang n'a pas ce compte (un métier inconnu, ou un type de compte que le serveur n'a pas).

money.sharedAdd and money.sharedRemove

Change le compte d'un métier ou d'un gang, avec une ligne de registre - les revenus et les coûts d'une entreprise.

Côté : serveur · Attend : non

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)

Retour

boolean : true quand le changement a eu lieu, false pour un métier ou un gang inconnu, un compte manquant, un mauvais montant, ou un compte qui ne peut pas payer.

Exemple

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

/** Un contrat de la ville que le garage gagne, et les frais qu'il paie pour les pièces. */
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

Déplace de l’argent d’un compte vers un autre en une seule transaction de base de données, avec une ligne de registre des deux côtés. Utilisez-la pour tout ce où l’argent ne doit pas apparaître ou disparaître à mi-chemin : payer un autre joueur, un métier qui verse une prime, des frais.

Côté : serveur · Attend : non

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

Paramètres

Prop

Type

Retour

boolean : true quand les deux lignes ont été écrites. false quand un montant n’est pas un nombre entier, qu’un compte manque, que les deux sont identiques, ou que from ne peut pas payer amount plus fee.

Exemple

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

Les lignes de registre d'un compte, les plus récentes en premier : ce qui a bougé, le solde après, la raison, qui l'a fait et quand. Fonctionne pour le compte d'un joueur, celui d'un métier ou d'un gang, et celui d'un personnage stocké.

Côté : serveur · Attend : oui

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

Paramètres

Prop

Type

Retour

Une LedgerPage : rows et le next à passer comme before (null sur la dernière page). ai-core écrit une ligne un instant après le changement : la plus récente peut donc avoir quelques millisecondes de retard sur le solde.

Exemple

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

/** Les 20 dernières lignes bancaires d'un personnage stocké. */
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 communique avec le script bancaire via la couche banque d’ai-core. L’argent des métiers lui-même passe toujours par money ou par les exports d’ai-core.

banking.open

Ouvre l’écran du script bancaire pour un joueur.

Côté : serveur · Attend : non

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

Retour true quand l’écran s’ouvre. false quand le script ne peut pas être ouvert de l’extérieur ou qu’aucun ne tourne.

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

banking.societyBalance

Le solde de société d’un métier, pour l’affichage. En mode de compte core d’ai-core, c’est le compte de métier d’ai-core ; en mode own, celui du script bancaire.

Côté : serveur · Attend : non

Signature
banking.societyBalance(job: string): number | null
Lua
local balance = aiLib.banking.societyBalance(job) -- nombre ou nil

Retour le solde, ou null (Lua nil) quand aucun script ne tourne ou que le script n’en garde pas.

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

banking.provider

Côté : serveur · Attend : non

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

Retour le script bancaire utilisé par la couche, ou null.

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

billing

billing envoie les factures via le script de facturation qui tourne ; sans script, ce sont les factures propres à ai-core (le joueur paie depuis une liste à l’écran, l’argent bouge quand il paie). Les textes sont déjà traduits.

billing.send

Envoie une facture de la part d’un métier (amendes, frais de service) ou d’un joueur.

Côté : serveur · Attend : non

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

BillRequest

Prop

Type

Retour

boolean : true quand elle est envoyée, false quand elle est invalide ou refusée.

Exemple

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

Les factures ouvertes du joueur.

Côté : serveur · Attend : oui (Promise en TypeScript, cède la main (yield) dans le thread en Lua)

Signature
billing.unpaid(source: number): Promise<UnpaidBill[] | null>
Lua
local bills = aiLib.billing.unpaid(source) -- table[] ou nil, à appeler dans un thread

Retour UnpaidBill[] (id, label, amount encore dû, sender), ou null quand le script de facturation ne peut pas les lister.

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

billing.pay

Le joueur paie l’une de ses factures ouvertes.

Côté : serveur · Attend : non

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

Prop

Type

Retour true quand elle est payée. false quand le paiement est refusé (pas assez d’argent, facture inconnue) ou que le script de facturation n’accepte les paiements que dans son propre écran.

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

billing.provider

Côté : serveur · Attend : non

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

Retour le script de facturation vers lequel vont les factures, "ai-core" pour les factures propres à ai-core.

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

Sur cette page