AI Core
Referencia de la APIAI Core: exports de servidor

Personajes guardados

Lee y cambia cualquier personaje, cargado o no - encontrarlo, leerlo, su dinero, trabajos, bandas, metadatos y nombre, guardarlo, borrarlo.

Los exports de Personajes responden sobre un jugador conectado con un personaje cargado. Los de esta página responden sobre cualquier personaje, conectado o no: ai-core lee un personaje cargado de la memoria y uno guardado de la base de datos, y una escritura llega al personaje vivo cuando está cargado y a la fila cuando no.

Tres cosas antes de empezar:

  • Un personaje se direcciona por su id de personaje (charId, un número - CharacterInfo.id). Un citizenid es texto y pertenece a los bridges de framework; convierte uno en otro con GetCharIdByCitizenId, nunca a mano.
  • Estos exports responden por un callback (done), porque un personaje guardado necesita una lectura en la base de datos y ninguna Promise cruza la frontera de los resources. En TypeScript el módulo characters de la lib te da una Promise; en Lua aiLib.characters espera por ti.
  • Cada escritura responde ActionResult: { ok: true }, o { ok: false, error: "LANG_KEY" } con una de las claves de idioma de ai-core (locales/en.json), que puedes mostrar con callAction o traducir tú mismo.

Nunca leas ni escribas las tablas de ai-core (ai_core_characters, ai_core_accounts, ai_core_character_jobs...) con tus propias consultas. Los personajes viven en memoria y se escriben según el calendario de ai-core, así que un SELECT directo puede estar desactualizado y las columnas son internas.

GetCharIdByCitizenId

El id de personaje detrás de un citizenid, cargado o no. Un personaje cargado responde desde la memoria, uno guardado con una lectura indexada.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.idOf

Firma
GetCharIdByCitizenId(citizenid: string, done: (charId: number | null) => void): void
Lua
exports['ai-core']:GetCharIdByCitizenId(citizenid, function(charId) end)

Parámetros

Prop

Type

Devuelve

Nada. La respuesta llega en done.

Ejemplo

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

// La lib envuelve el callback en una Promise.
export async function fine(citizenid: string, amount: number): Promise<boolean> {
  const charId = await characters.idOf(citizenid);
  if (charId === null) return false;
  const result = await characters.removeMoney(charId, "bank", amount, "Multa");
  return result.ok;
}

GetOfflineCharacter

Todo lo que ai-core guarda de un personaje: nombre y fecha de nacimiento, dinero por cuenta, trabajos, bandas, metadatos, posición guardada, último guardado, y el id de servidor cuando está cargado.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.get

Firma
GetOfflineCharacter(charId: number, done: (character: OfflineCharacter | null) => void): void
Lua
exports['ai-core']:GetOfflineCharacter(charId, function(character) end)

Parámetros

Devuelve

Nada. done recibe un OfflineCharacter o null. Un personaje cargado responde desde la memoria, así que su dinero y sus pertenencias son los vivos y source es el jugador.

Ejemplo

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

export async function describe(charId: number): Promise<string> {
  const c = await characters.get(charId);
  if (!c) return "personaje desconocido";
  const where = c.source === null ? "desconectado" : `conectado como ${c.source}`;
  return `${c.info.firstname} ${c.info.lastname} (${where}), banco ${c.money.bank ?? 0}`;
}

SearchCharacters

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

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.search

Firma
SearchCharacters(text: string, done: (page: CharacterSearchPage) => void, cursor?: number): void
Lua
exports['ai-core']:SearchCharacters(text, function(page) end, cursor)

Parámetros

Prop

Type

Devuelve

Nada. done recibe una CharacterSearchPage: hasta 25 coincidencias y el cursor next (null en la última página). Un texto vacío responde los personajes más nuevos, así que una pantalla de listado funciona sin término de búsqueda.

Ejemplo

import { characters, onClientCallback } from "@aicore8/lib/server";
import { oneArg, readText } from "@aicore8/lib/shared";

onClientCallback(
  "myscript:searchPeople",
  { args: oneArg((v) => readText(v, 64)), rate: { count: 10, windowMs: 10_000 } },
  async (_source, text) => {
    const page = await characters.search(text);
    return { ok: true, people: page.characters, next: page.next };
  },
);

GetCharactersOfUser

Todos los personajes de una cuenta, por slot. Para una pantalla que muestra a un jugador todos sus personajes, o para una herramienta de admin que trabaja sobre una cuenta.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.ofUser

Firma
GetCharactersOfUser(user: number | string, done: (characters: StoredCharacter[]) => void): void
Lua
exports['ai-core']:GetCharactersOfUser(user, function(characters) end)

Parámetros

Prop

Type

Devuelve

Nada. done recibe un array de StoredCharacter.

Ejemplo

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

const core = resourceExport("ai-core");

export async function slotsOf(source: number): Promise<number[]> {
  const userId = core.GetUserId(source);
  if (userId === null) return [];
  return (await characters.ofUser(userId)).map((c) => c.slot);
}

GetJobMembers and GetGangMembers

Todos los que tienen un trabajo (o están en una banda), cargados o no, página a página y con su grado. Esta es la plantilla que necesita una pantalla de gestión: el espejo online de la lib solo conoce a los jugadores conectados.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.jobMembers

Firma
GetJobMembers(job: string, done: (page: MembersPage) => void, after?: number, limit?: number): void
GetGangMembers(gang: string, done: (page: MembersPage) => void, after?: number, limit?: number): void
Lua
exports['ai-core']:GetJobMembers(job, function(page) end, after, limit)
exports['ai-core']:GetGangMembers(gang, function(page) end, after, limit)

Parámetros

Prop

Type

Devuelve

Nada. done recibe una MembersPage: los miembros y el after de la página siguiente (null en la última). Cada miembro lleva source, así que los conectados son las entradas cuyo source no es null.

Ejemplo

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

/** Todos los miembros 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;
}

Solo preguntar "¿alguien tiene este trabajo?" lee una fila: la lib characters.hasJobMember llama a este export con limit = 1.

AddOfflineMoney, RemoveOfflineMoney and SetOfflineMoney

El dinero de un personaje, cargado o no. Un personaje cargado pasa por su cartera viva (el jugador lo ve al momento); uno guardado se escribe en la base de datos con las mismas reglas y la misma fila de registro.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.addMoney

Firma
AddOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
RemoveOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
SetOfflineMoney(charId: number, account: string, amount: number, reason?: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:AddOfflineMoney(charId, account, amount, reason, function(result) end)
exports['ai-core']:RemoveOfflineMoney(charId, account, amount, reason, function(result) end)
exports['ai-core']:SetOfflineMoney(charId, account, amount, reason, function(result) end)

Parámetros

Prop

Type

Devuelve

Nada. done recibe { ok: true }, o { ok: false, error } con una clave de idioma: personaje desconocido, una cuenta que el servidor no tiene, una cantidad fraccionaria o negativa, o - en RemoveOfflineMoney - un saldo que no puede pagar (salvo que el tipo de cuenta permita bajar de cero).

Ejemplo

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

/** Paga una venta, esté el vendedor conectado o no. */
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;
}

SetOfflineJob and RemoveOfflineJob

Contrata a un personaje, le cambia el grado o lo despide, esté conectado o no. Se aplican las reglas de trabajo del panel (cuántos trabajos puede tener un personaje, si se permite un segundo), y el trabajo de desempleado nunca se guarda: quitar el último trabajo es lo que deja a un personaje sin empleo.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.setJob

Firma
SetOfflineJob(charId: number, job: string, grade: number, done?: (result: CharacterResult) => void): void
RemoveOfflineJob(charId: number, job: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineJob(charId, job, grade, function(result) end)
exports['ai-core']:RemoveOfflineJob(charId, job, function(result) end)

Parámetros

Prop

Type

Devuelve

Nada. done recibe { ok: true }, o { ok: false, error } con una clave de idioma: personaje desconocido, trabajo desconocido, un grado que no existe, o el límite de trabajos del panel.

Ejemplo

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

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

SetOfflineGang and RemoveOfflineGang

Lo mismo para bandas. Un personaje puede estar en varias bandas pero actúa por una a la vez (SetActiveGang la elige para un jugador conectado).

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.setGang

Firma
SetOfflineGang(charId: number, gang: string, grade: number, done?: (result: CharacterResult) => void): void
RemoveOfflineGang(charId: number, gang: string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineGang(charId, gang, grade, function(result) end)
exports['ai-core']:RemoveOfflineGang(charId, gang, function(result) end)

Parámetros

Prop

Type

Devuelve

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

SetOfflineMeta

Un valor de metadatos de un personaje, cargado o no. Un personaje cargado lo recibe como un delta en su propio juego, así que su HUD y su interfaz lo siguen al momento.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.setMeta

Firma
SetOfflineMeta(charId: number, key: string, value: unknown, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineMeta(charId, key, value, function(result) end)

Parámetros

Prop

Type

Devuelve

Nada. done recibe { ok: true }, o { ok: false, error } para un personaje desconocido o un valor que JSON no puede guardar.

Ejemplo

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

await characters.setMeta(12, "myscript_licence", { kind: "drive", since: Date.now() });
await characters.setMeta(12, "myscript_licence", null); // la quita

Para un jugador conectado, GetMeta / SetMeta es el camino corto, y leer metadatos solo es posible ahí (esta página no tiene GetOfflineMeta: lee el personaje completo con GetOfflineCharacter y toma metadata).

SetCharacterInfo

Cambia los campos propios del personaje: nombre, fecha de nacimiento, nacionalidad, sexo y altura. Cada campo se comprueba como lo comprueba el formulario de creación, así que una herramienta de admin no puede escribir un nombre que la creación rechazaría.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.setInfo

Firma
SetCharacterInfo(charId: number, patch: CharacterInfoPatch, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetCharacterInfo(charId, patch, function(result) end)

Parámetros

Prop

Type

Devuelve

Nada. done recibe { ok: true }, o { ok: false, error } con una clave de idioma. sex se rechaza mientras el personaje está cargado, porque el modelo del ped lo sigue; todo lo demás llega al personaje cargado como un delta.

Ejemplo

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

const result = await characters.setInfo(12, { lastname: "Doe-Smith", height: 174 });
if (!result.ok) console.log(`cambio de nombre rechazado: ${result.error}`);

DeleteCharacter

Borra un personaje. Es un borrado suave: la fila queda para los logs y el personaje desaparece de toda lista y de toda búsqueda.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.remove

Firma
DeleteCharacter(charId: number, by?: number | string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:DeleteCharacter(charId, by, function(result) end)

Parámetros

Prop

Type

Devuelve

Nada. done recibe { ok: true }, o { ok: false, error } para un personaje desconocido o uno que está cargado ahora mismo - el jugador tiene que volver primero a la pantalla de personajes. Al tener éxito, ai-core dispara su evento characterDeleted; ver Eventos y estado.

GetPlayTime

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

Lado: Servidor · Espera: no para un jugador conectado · Lib: characters.playTime

Firma
GetPlayTime(target: number | { charId: number }, done?: (seconds: number | null) => void): number | null
Lua
local seconds = exports['ai-core']:GetPlayTime(source) -- un jugador conectado: responde al momento
exports['ai-core']:GetPlayTime({ charId = 12 }, function(seconds) end)

Parámetros

Prop

Type

Devuelve

number | null: los segundos, cuando se saben sin leer la base de datos (un id de servidor, o un { charId } cargado). null significa "no está aquí, espera a done" - o, para un id de servidor, que el jugador no tiene personaje cargado.

SavePlayer

Escribe ahora la posición y los metadatos de un jugador conectado y espera sus escrituras en cola. Úsalo antes de algo que no debe perder los últimos minutos: un reinicio, un traspaso, una acción de admin que registras.

Lado: Servidor · Espera: no (la respuesta llega en done) · Lib: characters.save

Firma
SavePlayer(source: number, done?: (ok: boolean) => void): void
Lua
exports['ai-core']:SavePlayer(source, function(ok) end)

Parámetros

Prop

Type

Devuelve

Nada. ai-core guarda por su cuenta (periódicamente, al descargar y al apagar), así que solo necesitas esto cuando la escritura deba haber ocurrido antes de tu siguiente paso.

Un personaje que no está cargado ya está escrito: no hay nada que vaciar. Para mover el punto de aparición de un personaje guardado usa characters.setOfflinePosition (SetOfflinePosition).

En esta página