AI Core
Referencia de la APILib: servidor

Dinero y banca

money.transfer entre dos cuentas, el script de banca a través de ai-core y las facturas a través del script de facturación que funcione.

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

money es todo saldo del servidor: las cuentas de un jugador cargado, la cuenta compartida de un trabajo o una banda, una transferencia que mueve el dinero en una sola transacción, y el registro. Un personaje que no está conectado se maneja con characters. banking y billing son las capas para los scripts de banco y de facturas del servidor.

money

money.get

El saldo de un jugador cargado en una cuenta.

Lado: Servidor · Espera: no

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

Parámetros

Prop

Type

Devuelve

number | null: el saldo, o null cuando el jugador no tiene personaje cargado o el tipo de cuenta no existe. Los saldos de un personaje guardado vienen de characters.get.

Ejemplo

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

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

money.add, money.remove and money.set

Cambia una cuenta de un jugador cargado, con una fila de registro. Son las llamadas para una recompensa, un precio, un sueldo que paga tu script.

Lado: Servidor · Espera: no

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

Parámetros

Prop

Type

Devuelve

boolean: true cuando el cambio se hizo. false cuando el jugador no tiene personaje cargado, la cuenta no existe, la cantidad no es un entero mayor que 0, o - en remove - el saldo no puede pagar (salvo que el tipo de cuenta permita bajar de cero).

Ejemplo

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");
  // entrega el objeto aquí
  return { ok: true };
});

Que un jugador pague a otro no es un remove más un add: un fallo a medio camino haría aparecer o desaparecer dinero. Usa money.transfer, que es una sola transacción.

money.sharedGet

El saldo de la cuenta de un trabajo o una banda - bank es lo que otros frameworks llaman dinero de sociedad.

Lado: Servidor · Espera: no

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

Parámetros

Prop

Type

Devuelve

number | null: el saldo, o null cuando ese trabajo o banda no tiene esa cuenta (un trabajo desconocido, o un tipo de cuenta que el servidor no tiene).

money.sharedAdd and money.sharedRemove

Cambia la cuenta de un trabajo o una banda, con una fila de registro - los ingresos y los costes de una empresa.

Lado: Servidor · Espera: no

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

Devuelve

boolean: true cuando el cambio se hizo, false para un trabajo o banda desconocidos, una cuenta que falta, una cantidad errónea, o una cuenta que no puede pagar.

Ejemplo

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

/** Un contrato de la ciudad que gana el taller, y lo que paga por las piezas. */
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

Mueve dinero de una cuenta a otra en una sola transacción de base de datos, con una fila de registro contable en ambos lados. Úsalo para todo aquello en que el dinero no deba aparecer ni desaparecer a medias: pagar a otro jugador, un trabajo que paga una prima, una comisión.

Lado: Servidor · Espera: no

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

Parámetros

Prop

Type

Devuelve

boolean: true cuando se escribieron ambas filas. false cuando una cantidad no es un número entero, falta una cuenta, ambas son la misma, o from no puede pagar amount más fee.

Ejemplo

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

Las filas del registro de una cuenta, las más nuevas primero: qué se movió, el saldo después, el motivo, quién lo hizo y cuándo. Funciona para la cuenta de un jugador, la de un trabajo o banda, y la de un personaje guardado.

Lado: Servidor · Espera: sí

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

Parámetros

Prop

Type

Devuelve

Una LedgerPage: rows y el next que pasas como before (null en la última página). ai-core escribe una fila un momento después del cambio, así que la más nueva puede ir unos milisegundos detrás del saldo.

Ejemplo

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

/** Las últimas 20 filas de banco de un personaje guardado. */
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 habla con el script de banca a través de la capa de banca de ai-core. El dinero de los trabajos en sí siempre se mueve mediante money o los exports de ai-core.

banking.open

Abre la pantalla del script de banca para un jugador.

Lado: Servidor · Espera: no

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

Devuelve true cuando se abrió. false cuando el script no puede abrirse desde fuera o no hay ninguno en marcha.

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

banking.societyBalance

El saldo de la sociedad de un trabajo, para mostrarlo. En el modo de cuenta core de ai-core es la cuenta del trabajo de ai-core; en el modo own, la del propio script de banca.

Lado: Servidor · Espera: no

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

Devuelve el saldo, o null (nil en Lua) cuando no hay ninguno en marcha o el script no lleva ninguno.

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

banking.provider

Lado: Servidor · Espera: no

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

Devuelve el script de banca que usa la capa, o null.

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

billing

billing envía facturas a través del script de facturación que funcione; sin ninguno, las facturas propias de ai-core (el jugador paga desde una lista en pantalla y el dinero se mueve cuando paga). Los textos ya están traducidos.

billing.send

Envía una factura desde un trabajo (multas, tarifas de servicio) o desde un jugador.

Lado: Servidor · Espera: no

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

BillRequest

Prop

Type

Devuelve

boolean: true cuando se envió, false cuando no es válida o se rechazó.

Ejemplo

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

Las facturas abiertas del jugador.

Lado: Servidor · Espera: sí (Promise en TypeScript, cede el hilo en Lua)

Firma
billing.unpaid(source: number): Promise<UnpaidBill[] | null>
Lua
local bills = aiLib.billing.unpaid(source) -- table[] o nil, llamar dentro de un hilo

Devuelve UnpaidBill[] (id, label, amount aún adeudado, sender), o null cuando el script de facturación no puede listarlas.

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

billing.pay

El jugador paga una de sus facturas abiertas.

Lado: Servidor · Espera: no

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

Prop

Type

Devuelve true cuando se pagó. false cuando se rechazó (no hay suficiente dinero, factura desconocida) o el script de facturación solo acepta pagos en su propia pantalla.

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

billing.provider

Lado: Servidor · Espera: no

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

Devuelve el script de facturación al que van las facturas, "ai-core" para las facturas propias de ai-core.

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

En esta página