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.
import { characters } from "@aicore8/lib/server";-- 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í
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í
characters.get(charId: number): Promise<OfflineCharacter | null>local character = aiLib.characters.get(charId) -- tabla o nilPará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í
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>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í
characters.ofUser(user: number | string): Promise<StoredCharacter[]>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í
characters.jobMembers(job: string, after?: number, limit?: number): Promise<MembersPage>
characters.gangMembers(gang: string, after?: number, limit?: number): Promise<MembersPage>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í
characters.hasJobMember(job: string): Promise<boolean>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í
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>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í
characters.setJob(charId: number, job: string, grade: number): Promise<CharacterResult>
characters.removeJob(charId: number, job: string): Promise<CharacterResult>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í
characters.setGang(charId: number, gang: string, grade: number): Promise<CharacterResult>
characters.removeGang(charId: number, gang: string): Promise<CharacterResult>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í
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>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í
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>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í
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>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í
characters.playTime(target: number | { charId: number }): Promise<number | null>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í
characters.save(source: number): Promise<boolean>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
| Quieres | Dónde |
|---|---|
| El punto de aparición de un personaje guardado | characters.setOfflinePosition |
| Quién está conectado, sus nombres, trabajos y servicio | online |
| Los trabajos y bandas de un jugador cargado | jobs |
| El dinero de un jugador cargado | money |
| El registro de un personaje | money.history |
Jugadores y personajes
online, onCharacter, notify, jugadores cercanos, posiciones y almacenes por jugador: PlayerMap, Cooldowns, KeyedCooldowns, SourceLock, RateLimit, KeyWatchers.
Objetos
inventory: dar, quitar y contar objetos, almacenes, tiendas y objetos usables a través del inventario que use el servidor.