AI Core
Referencia de la APIAI Core: exports de servidor

Personajes y jugadores

Lee los datos y el personaje de un jugador cargado, encuentra a un jugador por id de personaje o citizen id, cambia de personaje, mueve a un personaje desconectado, jugadores en el scope.

Un jugador es una persona conectada con un id de servidor (source). Un personaje es una de las personas que interpreta ese jugador; tiene un id en la base de datos (charId) y un citizen id (citizenid, un texto corto como ABC12345). Un jugador tiene un personaje cargado después de elegir uno en la pantalla de personajes. La mayoría de los exports de aquí responden null antes de eso.

Las llamadas a exports copian su respuesta, así que lee lo que necesitas una vez y sigue los eventos de ai-core (ai-core:playerLoaded, ai-core:playerUnloaded) en lugar de volver a preguntar. Consulta Eventos y estado.

GetPlayerData

Todo lo que ai-core guarda de un jugador cargado en un solo objeto: personaje, dinero, trabajos, servicio, bandas y metadatos. Úsalo cuando un recurso se inicia tarde y necesita una vez el estado completo de un jugador; para valores sueltos usa los exports más pequeños de abajo.

Lado: Servidor · Espera: no · Lib: ninguna en el servidor (el getPlayerData de la lib de cliente lee los mismos datos en el juego del jugador)

Firma
GetPlayerData(src: number): AiPlayerData | null
Lua
local data = exports['ai-core']:GetPlayerData(source) -- table o nil

Parámetros

Prop

Type

Devuelve

AiPlayerData | null: una copia de los datos del jugador (AiPlayerData). null cuando nadie con ese id de servidor tiene un personaje cargado (no conectado, o aún en la pantalla de personajes). La copia no cambia después: vuelve a llamar o sigue los eventos para tener valores nuevos.

Ejemplo

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

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

addCommand("whoami", { help: "Shows your character", restricted: true }, (source) => {
  const data = core.GetPlayerData(source);
  if (!data?.character) return;
  const { firstname, lastname } = data.character;
  console.log(`${firstname} ${lastname}: job ${data.job.job} (grade ${data.job.grade}), cash ${data.money.cash ?? 0}`);
});

El objeto entero se copia en cada llamada. Nunca lo llames en un bucle sobre todos los jugadores ni con un temporizador: lee valores sueltos (GetMoney, GetDutyJob) o usa el espejo online de la lib.

GetCharacter

El personaje cargado de un jugador: id en la base de datos, citizen id, ranura, nombres, fecha de nacimiento, sexo y nacionalidad. Úsalo para mostrar un nombre o para guardar algo por id de personaje.

Lado: Servidor · Espera: no · Lib: ninguna (online.character(source) lee lo mismo del espejo de la lib sin llamar a un export)

Firma
GetCharacter(src: number): CharacterInfo | null
Lua
local character = exports['ai-core']:GetCharacter(source) -- table o nil

Parámetros

Prop

Type

Devuelve

CharacterInfo | null: el personaje (CharacterInfo). null cuando el jugador no tiene un personaje cargado.

Ejemplo

import { onClientCallback, resourceExport } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

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

onClientCallback("myscript:profile", (source) => {
  const character = core.GetCharacter(source);
  if (!character) return fail("NO_CHARACTER");
  return { ok: true, name: `${character.firstname} ${character.lastname}`, citizenid: character.citizenid };
});

GetSourceByCharId

El id de servidor del jugador que interpreta ahora mismo a un personaje. Úsalo cuando guardaste un id de personaje (un dueño, un contacto) y necesitas llegar a esa persona en el juego.

Lado: Servidor · Espera: no · Lib: ninguna

Firma
GetSourceByCharId(charId: number): number | null
Lua
local src = exports['ai-core']:GetSourceByCharId(charId) -- number o nil

Parámetros

Prop

Type

Devuelve

number | null: el id de servidor del jugador. null cuando nadie interpreta ahora a ese personaje (desconectado, o hay otro personaje cargado).

Ejemplo

import { notify, resourceExport } from "@aicore-fivem/lib/server";
import { Locale } from "common";

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

/** Tells a house owner that someone rang, when the owner is online. */
export function ringOwner(ownerCharId: number): void {
  const owner = core.GetSourceByCharId(ownerCharId);
  if (owner !== null) notify(owner, Locale("NOTIFY_DOORBELL"), "info");
}

GetSourceByCitizenId

Lo mismo que GetSourceByCharId, por citizen id. Úsalo con datos que guardan citizen ids (la mayoría de las tablas al estilo ESX / QB lo hacen).

Lado: Servidor · Espera: no · Lib: ninguna

Firma
GetSourceByCitizenId(citizenid: string): number | null
Lua
local src = exports['ai-core']:GetSourceByCitizenId(citizenid) -- number o nil

Parámetros

Prop

Type

Devuelve

number | null: el id de servidor del jugador que interpreta a ese personaje. null cuando el personaje no está cargado.

Ejemplo

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

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

addCommand("findcid", {
  help: "Finds the player of a citizen id",
  params: [{ name: "citizenid", type: "string" }],
  restricted: true,
}, (source, args) => {
  const target = core.GetSourceByCitizenId(args.citizenid);
  console.log(target === null ? "not online" : `server id ${target}`);
});

GetLoadedSources

Los ids de servidor de cada jugador que tiene un personaje cargado. Úsalo para trabajos raros que abarcan todo el servidor (un aviso de reinicio, una lista de admin).

Lado: Servidor · Espera: no · Lib: online.sources() lee lo mismo del espejo de la lib

Firma
GetLoadedSources(): number[]
Lua
local sources = exports['ai-core']:GetLoadedSources() -- lista de números

Parámetros

Ninguno.

Devuelve

number[]: un id de servidor por jugador cargado, sin un orden fijo. Una lista vacía cuando nadie tiene un personaje cargado. Los jugadores que siguen en la pantalla de personajes no están en ella.

Ejemplo

import { addCommand, notify, resourceExport } from "@aicore-fivem/lib/server";
import { Locale } from "common";

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

addCommand("announce", {
  help: "Sends a notification to every player",
  params: [{ name: "text", type: "longString" }],
  restricted: true,
}, (_source, args) => {
  for (const target of core.GetLoadedSources())
    notify(target, Locale("NOTIFY_ANNOUNCEMENT", args.text), "warning");
});

Nunca llames a otro export por cada id de esta lista en una ruta frecuente (GetLoadedSources() + GetDutyJob por jugador cada segundo). Quién está de servicio, los nombres y los trabajos de muchos jugadores salen del espejo online de la lib; quién está cerca, de playersNear.

GetUserId

El id de cuenta de un jugador conectado: la fila de ai_core_users, que contiene la cuenta de FiveM del jugador y cada uno de sus personajes. A diferencia de la mayoría de los exports, también responde mientras el jugador sigue en la pantalla de personajes.

Lado: Servidor · Espera: no · Lib: ninguna

Firma
GetUserId(src: number): number | null
Lua
local userId = exports['ai-core']:GetUserId(source) -- number o nil

Parámetros

Prop

Type

Devuelve

number | null: el id de cuenta. null cuando el jugador no está conectado o aún no ha llegado a la pantalla de personajes.

Ejemplo

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

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

addCommand("account", {
  help: "Shows a player account id",
  params: [{ name: "id", type: "playerId" }],
  restricted: true,
}, (_source, args) => {
  console.log(`account ${core.GetUserId(args.id) ?? "unknown"}`);
});

GetFivemId

El id de cuenta de FiveM (Cfx.re) del jugador. ai-core lo usa como clave de la cuenta del jugador: un jugador sin él no puede conectarse.

Lado: Servidor · Espera: no · Lib: ninguna

Firma
GetFivemId(src: number): string | null
Lua
local fivemId = exports['ai-core']:GetFivemId(source) -- string o nil

Parámetros

Prop

Type

Devuelve

string | null: el id sin el prefijo fivem: (por ejemplo 1234567). null cuando el jugador no tiene un personaje cargado.

Ejemplo

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

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

addCommand("fivemid", {
  help: "Prints the add_principal line for a player",
  params: [{ name: "id", type: "playerId" }],
  restricted: true,
}, (_source, args) => {
  const id = core.GetFivemId(args.id);
  if (id) console.log(`add_principal identifier.fivem:${id} group.admin`);
});

GetCharacterInfo

Un personaje por id de la base de datos, cargado o no, con el id de la cuenta a la que pertenece. Úsalo para mostrar quién es dueño de algo cuando esa persona puede estar desconectada.

Lado: Servidor · Espera: no (responde mediante done) · Lib: ninguna

Firma
GetCharacterInfo(
  charId: number,
  done: (info: (CharacterInfo & { userId: number }) | null) => void,
): void
Lua
exports['ai-core']:GetCharacterInfo(charId, function(info) end) -- info: table o nil

Parámetros

Prop

Type

Devuelve

Nada. done recibe un CharacterInfo con un campo más, userId (el id de cuenta), o null para un personaje desconocido o borrado, un id erróneo o una lectura fallida. Sin una función como done la llamada no hace nada.

Ejemplo

import { addCommand, resourceExport } from "@aicore-fivem/lib/server";

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

addCommand("charinfo", {
  help: "Shows a character by id",
  params: [{ name: "charId", type: "number" }],
  restricted: true,
}, (_source, args) => {
  core.GetCharacterInfo(args.charId, (info) => {
    if (!info) return console.log("no such character");
    console.log(`${info.firstname} ${info.lastname} (${info.citizenid}), account ${info.userId}`);
  });
});

Un personaje guardado se conserva 5 minutos después de leerlo, así que un nombre cambiado en el panel de administración puede mostrar el valor anterior durante ese tiempo. Un personaje cargado siempre responde desde la memoria.

SwitchCharacter

Envía a un jugador de vuelta a la pantalla de personajes sin salir del servidor, como un cierre de sesión. ai-core guarda y descarga primero el personaje, y después abre la pantalla.

Lado: Servidor · Espera: no (la descarga se ejecuta después de que vuelva la llamada) · Lib: ninguna

Firma
SwitchCharacter(src: number): boolean
Lua
local started = exports['ai-core']:SwitchCharacter(source) -- boolean

Parámetros

Prop

Type

Devuelve

boolean: true cuando empezó el cambio. false cuando el jugador no tiene un personaje cargado.

Ejemplo

import { onClientCallback, resourceExport } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

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

// Un botón "Cambiar de personaje" en tu menú.
onClientCallback("myscript:logout", (source) =>
  core.SwitchCharacter(source) ? { ok: true } : fail("NO_CHARACTER"),
);

Tu recurso recibe ai-core:playerUnloaded con el motivo "switch" cuando el personaje ya no está. Limpia ahí el estado por personaje, no justo después de esta llamada.

SetOfflinePosition

Mueve el punto de aparición de un personaje que no está cargado: la próxima vez que se elija ese personaje, aparece ahí. Úsalo cuando algo mueve un cuerpo dormido o un personaje desconectado (un cuerpo que se llevan, un jugador remolcado).

Lado: Servidor · Espera: no (la escritura sigue en segundo plano) · Lib: characters.setOfflinePosition

Firma
SetOfflinePosition(
  charId: number,
  position: { x: number; y: number; z: number; heading?: number },
): boolean
Lua
local accepted = exports['ai-core']:SetOfflinePosition(charId, { x = x, y = y, z = z, heading = h })

Parámetros

Prop

Type

Devuelve

boolean: true cuando se acepta el movimiento; la escritura en la base de datos sigue en cuanto no hay ninguna carga ni guardado de ese personaje en curso (espera hasta 30 segundos). false cuando el personaje está cargado ahora, charId no es un número entero o falta una coordenada o no es un número finito. Un heading ausente se guarda como 0.

Ejemplo

import { resourceExport } from "@aicore-fivem/lib/server";

const core = resourceExport("ai-core");
const HOSPITAL = { x: 298.6, y: -584.5, z: 43.3, heading: 70 };

/** A body left in the world too long is moved to the hospital. */
export function sendBodyToHospital(charId: number): void {
  if (!core.SetOfflinePosition(charId, HOSPITAL))
    console.log(`character ${charId} is online, not moved`);
}

Si el personaje se carga mientras la escritura espera, la escritura se omite: el ped de un personaje cargado está donde está de verdad.

GetPlayersInScope

Los jugadores en el scope de OneSync de otro jugador: todos aquellos cuyo juego está transmitiendo ahora a ese jugador, unos 424 metros alrededor. ai-core mantiene esta lista a partir de los eventos de scope de FiveM una sola vez para todos los recursos, así que los demás recursos nunca escuchan esos eventos por sí mismos.

Lado: Servidor · Espera: no · Lib: playersNear(source, radius) y playersNearEntity(entity, radius) se basan en él y filtran por distancia

Firma
GetPlayersInScope(source: number): number[]
Lua
local nearby = exports['ai-core']:GetPlayersInScope(source) -- lista de ids de servidor

Parámetros

Prop

Type

Devuelve

number[]: los ids de servidor de los demás jugadores en el scope (el propio jugador no está en la lista). Una lista vacía para un jugador solo, un id desconocido o un valor que no es un número.

Ejemplo

import { coordsOf, resourceExport } from "@aicore-fivem/lib/server";
import { distance } from "@aicore-fivem/lib/shared";

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

/** Plays a sound for everyone within 30 m of a player. */
export function playNear(source: number, sound: string): void {
  const at = coordsOf(source);
  for (const other of [source, ...core.GetPlayersInScope(source)])
    if (distance(coordsOf(other), at) <= 30) emitNet("myscript:sound", other, sound);
}

Exports de servidor

Cómo llamar a los exports de servidor de ai-core desde Lua y TypeScript, y la lista de cada grupo de exports.

Dinero y cuentas

Lee y cambia los saldos de un jugador y las cuentas de trabajos y bandas, mueve dinero entre dos cuentas en una sola transacción, lee los tipos de cuenta.

En esta página

GetPlayerDataParámetrosDevuelveEjemploGetCharacterParámetrosDevuelveEjemploGetSourceByCharIdParámetrosDevuelveEjemploGetSourceByCitizenIdParámetrosDevuelveEjemploGetLoadedSourcesParámetrosDevuelveEjemploGetUserIdParámetrosDevuelveEjemploGetFivemIdParámetrosDevuelveEjemploGetCharacterInfoParámetrosDevuelveEjemploSwitchCharacterParámetrosDevuelveEjemploSetOfflinePositionParámetrosDevuelveEjemploGetPlayersInScopeParámetrosDevuelveEjemplo