AI Core
Referencia de la APILib: servidor

Personajes, cargados o no

El módulo characters: encuentra, lee y cambia cualquier personaje a través de ai-core - dinero, trabajos, bandas, metadatos, nombre, tiempo jugado - con una Promise en TypeScript y una espera simple en Lua.

TypeScript
import { characters } from "@aicore8/lib/server";
Lua
-- aiLib.characters, tras shared_script '@ai-lib/init.lua'

characters es la puerta de la lib a los exports de personajes guardados de ai-core. Existe porque esos exports responden por un callback: la lib convierte cada uno en una Promise en TypeScript y en una espera simple en Lua, así tu código se lee de arriba abajo.

  • Un personaje se nombra por su id de personaje (charId, un número). Desde un citizenid: characters.idOf.
  • Un personaje cargado responde desde la memoria (dinero y pertenencias vivos); uno guardado se lee de la base de datos mientras ai-core lo retiene, así que no puede cargarse en medio de una escritura.
  • Cada escritura responde ActionResult: { ok: true }, o { ok: false, error } con una clave de idioma de ai-core.
  • Todas las funciones de aquí esperan. En Lua eso significa llamarlas desde un thread; ver Funciones que esperan.

Para el jugador del que trata la acción, el camino corto suele ser ai-core directamente: GetCharacter, money, jobs. Usa characters cuando el objetivo pueda estar desconectado, o cuando necesites un personaje entero de una vez.

characters

characters.idOf

El id de personaje detrás de un citizenid.

Lado: Servidor · Espera: sí

Firma
characters.idOf(citizenid: string): Promise<number | null>

Sin equivalente en Lua: llama al export GetCharIdByCitizenId de ai-core y espera su callback.

Parámetros

Prop

Type

Devuelve

Promise<number | null>: el id del personaje, o null cuando ningún personaje tiene ese citizenid o fue borrado.

Ejemplo

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

/** Una multa que funciona esté el conductor conectado o no. */
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, "Multa")).ok;
}

characters.get

Un personaje con todo lo que ai-core guarda de él: datos, dinero por cuenta, trabajos, bandas, metadatos, posición guardada, último guardado, y el id de servidor cuando está cargado.

Lado: Servidor · Espera: sí

Firma
characters.get(charId: number): Promise<OfflineCharacter | null>
Lua
local character = aiLib.characters.get(charId) -- tabla o nil

Parámetros

Prop

Type

Devuelve

Un OfflineCharacter, o null / nil cuando el id es desconocido o el personaje fue borrado.

Ejemplo

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

Personajes a partir de un texto escrito, cargados o no: prefijos de nombre ("jane doe" también), citizenid, id de fivem / license / discord. 25 por página, los más nuevos primero.

Lado: Servidor · Espera: sí

Firma
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>
Lua
local page = aiLib.characters.search(text, cursor)

Parámetros

Prop

Type

Devuelve

Una CharacterSearchPage: characters (hasta 25) y next (null en la última página). Ante un error responde una página vacía, nunca null.

Ejemplo

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

Todos los personajes de una cuenta, por slot.

Lado: Servidor · Espera: sí

Firma
characters.ofUser(user: number | string): Promise<StoredCharacter[]>
Lua
local list = aiLib.characters.ofUser(user)

Parámetros

Prop

Type

Devuelve

Un array de StoredCharacter, por slot. Vacío para una cuenta desconocida.

characters.jobMembers and characters.gangMembers

Todos los que tienen un trabajo o están en una banda, cargados o no - página a página, con su grado y con su id de servidor cuando están conectados.

Lado: Servidor · Espera: sí

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

Parámetros

Prop

Type

Devuelve

Una MembersPage: members y next (null en la última página).

Ejemplo

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

/** Toda la plantilla de un trabajo, página a página. */
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;
}

Contar los jugadores conectados de un trabajo no es esto: eso es el espejo de la lib, online.jobMembers (sin llamada a export y sin lectura en la base de datos).

characters.hasJobMember

Si alguien tiene un trabajo, cargado o no. Se lee una fila, así que es bastante barato para una comprobación al arrancar ("¿tiene este servidor una policía?").

Lado: Servidor · Espera: sí

Firma
characters.hasJobMember(job: string): Promise<boolean>
Lua
local anyone = aiLib.characters.hasJobMember(job)

Devuelve

true cuando al menos un personaje tiene el trabajo.

characters.addMoney, characters.removeMoney and characters.setMoney

El dinero de un personaje, cargado o no, con una fila de registro. Un personaje cargado pasa por su cartera viva, así que el jugador ve el cambio al momento.

Lado: Servidor · Espera: sí

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

Parámetros

Prop

Type

Devuelve

{ ok: true }, o { ok: false, error } con una clave de idioma: personaje desconocido, cuenta desconocida, cantidad fraccionaria o negativa, o un saldo que no puede pagar (removeMoney, salvo que el tipo de cuenta permita bajar de cero).

Ejemplo

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

export async function payOut(charId: number, amount: number): Promise<boolean> {
  const result = await characters.addMoney(charId, "bank", amount, "Vehículo vendido");
  if (!result.ok) console.log(`pago rechazado: ${result.error}`);
  return result.ok;
}

Mover dinero entre dos cuentas es una llamada y una transacción: money.transfer. El registro de un personaje guardado es money.history con { owner: "character", id, account }.

characters.setJob and characters.removeJob

Contrata a un personaje, le cambia el grado o lo despide, conectado o no. Se aplican las reglas de trabajo del panel, y el trabajo de desempleado nunca se guarda: quitar el último trabajo deja al personaje sin empleo.

Lado: Servidor · Espera: sí

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

Parámetros

Prop

Type

Devuelve

{ ok: true }, o { ok: false, error }: personaje desconocido, trabajo desconocido, grado desconocido, o el límite del panel sobre cuántos trabajos puede tener un personaje.

Ejemplo

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

/** Despedir a un miembro, conectado o no. */
export async function fire(charId: number, job: string): Promise<boolean> {
  return (await characters.removeJob(charId, job)).ok;
}

characters.setGang and characters.removeGang

Lo mismo para bandas.

Lado: Servidor · Espera: sí

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

Devuelve

{ ok: true } o { ok: false, error }, como con los trabajos.

characters.setMeta

Un valor de metadatos de un personaje, cargado o no. Un personaje cargado lo recibe como un delta en su propio juego.

Lado: Servidor · Espera: sí

Firma
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>
Lua
local result = aiLib.characters.setMeta(charId, key, value)

Parámetros

Prop

Type

Devuelve

{ ok: true }, o { ok: false, error } para un personaje desconocido o un valor que JSON no puede guardar. Leer metadatos es parte de characters.get; para un jugador conectado usa GetMeta.

characters.setInfo

Nombre, fecha de nacimiento, nacionalidad, sexo y altura, cada uno comprobado como lo comprueba el formulario de creación.

Lado: Servidor · Espera: sí

Firma
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>
Lua
local result = aiLib.characters.setInfo(charId, patch)

Parámetros

Prop

Type

Devuelve

{ ok: true }, o { ok: false, error } con una clave de idioma (un nombre que la creación rechazaría, una fecha que no es YYYY-MM-DD, sex en un personaje cargado).

characters.remove

Borra un personaje (borrado suave: la fila queda para los logs).

Lado: Servidor · Espera: sí

Firma
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>
Lua
local result = aiLib.characters.remove(charId, by)

Parámetros

Prop

Type

Devuelve

{ ok: true }, o { ok: false, error } para un personaje desconocido o uno que está cargado ahora mismo.

characters.playTime

Los segundos que se ha jugado un personaje: el total guardado más la sesión en curso.

Lado: Servidor · Espera: sí

Firma
characters.playTime(target: number | { charId: number }): Promise<number | null>
Lua
local seconds = aiLib.characters.playTime(target)

Parámetros

Prop

Type

Devuelve

Los segundos, o null para un personaje desconocido (o un id de servidor sin personaje cargado).

characters.save

Escribe ahora la posición y los metadatos de un jugador conectado y espera sus escrituras en cola.

Lado: Servidor · Espera: sí

Firma
characters.save(source: number): Promise<boolean>
Lua
local ok = aiLib.characters.save(source)

Devuelve

true cuando todo está escrito, false cuando el jugador no tiene personaje cargado. ai-core guarda por su cuenta (periódicamente, al descargar, al apagar): usa esto solo cuando la escritura tenga que haber ocurrido antes de tu siguiente paso.

En otras partes de la lib

QuieresDónde
El punto de aparición de un personaje guardadocharacters.setOfflinePosition
Quién está conectado, sus nombres, trabajos y servicioonline
Los trabajos y bandas de un jugador cargadojobs
El dinero de un jugador cargadomoney
El registro de un personajemoney.history

En esta página