AI Core
Referência da APIAI Core: exports de servidor

Personagens e jogadores

Leia os dados e o personagem de um jogador carregado, encontre um jogador pelo id do personagem ou pelo citizen id, troque de personagem, mova um personagem offline, jogadores no escopo.

Um jogador é uma pessoa conectada com um id de servidor (source). Um personagem é uma das pessoas que esse jogador interpreta; ele tem um id no banco de dados (charId) e um citizen id (citizenid, um texto curto como ABC12345). Um jogador tem um personagem carregado depois de escolher um na tela de personagens. A maioria dos exports aqui responde null antes disso.

As chamadas de export copiam a resposta, então leia o que precisa uma vez e siga os eventos do ai-core (ai-core:playerLoaded, ai-core:playerUnloaded) em vez de perguntar de novo. Veja Eventos e estado.

GetPlayerData

Tudo o que o ai-core guarda para um jogador carregado num só objeto: personagem, dinheiro, empregos, serviço, gangues e metadata. Use quando um recurso inicia tarde e precisa do estado completo de um jogador uma vez; para valores isolados use os exports menores abaixo.

Lado: Servidor · Espera: não · Lib: nenhuma no servidor (o getPlayerData da lib de cliente lê os mesmos dados no jogo do jogador)

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

Parâmetros

Prop

Type

Retorno

AiPlayerData | null: uma cópia dos dados do jogador (AiPlayerData). null quando ninguém com esse id de servidor tem um personagem carregado (não conectado, ou ainda na tela de personagens). A cópia não muda depois: chame de novo ou siga os eventos para valores novos.

Exemplo

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}`);
});

O objeto inteiro é copiado a cada chamada. Nunca o chame num loop sobre todos os jogadores ou num timer: leia valores isolados (GetMoney, GetDutyJob) ou use o espelho online da lib.

GetCharacter

O personagem carregado de um jogador: id no banco de dados, citizen id, slot, nomes, data de nascimento, sexo e nacionalidade. Use para mostrar um nome ou para gravar algo pelo id do personagem.

Lado: Servidor · Espera: não · Lib: nenhuma (online.character(source) lê o mesmo do espelho da lib sem uma chamada de export)

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

Parâmetros

Prop

Type

Retorno

CharacterInfo | null: o personagem (CharacterInfo). null quando o jogador não tem personagem carregado.

Exemplo

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

O id de servidor do jogador que interpreta um personagem agora. Use quando você gravou um id de personagem (um dono, um contato) e precisa alcançar essa pessoa no jogo.

Lado: Servidor · Espera: não · Lib: nenhuma

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

Parâmetros

Prop

Type

Retorno

number | null: o id de servidor do jogador. null quando ninguém interpreta esse personagem agora (offline, ou outro personagem está carregado).

Exemplo

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

O mesmo que GetSourceByCharId, pelo citizen id. Use com dados que gravam citizen ids (a maioria das tabelas no estilo ESX / QB grava).

Lado: Servidor · Espera: não · Lib: nenhuma

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

Parâmetros

Prop

Type

Retorno

number | null: o id de servidor do jogador que interpreta esse personagem. null quando o personagem não está carregado.

Exemplo

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

Os ids de servidor de cada jogador que tem um personagem carregado. Use para trabalho raro que envolve o servidor inteiro (um aviso de restart, uma lista de admin).

Lado: Servidor · Espera: não · Lib: online.sources() lê o mesmo do espelho da lib

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

Parâmetros

Nenhum.

Retorno

number[]: um id de servidor por jogador carregado, sem ordem fixa. Uma lista vazia quando ninguém tem personagem carregado. Jogadores ainda na tela de personagens não estão nela.

Exemplo

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 chame outro export para cada id desta lista num caminho frequente (GetLoadedSources() + GetDutyJob por jogador a cada segundo). Quem está em serviço, nomes e empregos de muitos jogadores vêm do espelho online da lib; quem está perto, de playersNear.

GetUserId

O id da conta de um jogador conectado: a linha em ai_core_users, que guarda a conta FiveM do jogador e cada personagem dela. Ao contrário da maioria dos exports, também responde enquanto o jogador ainda está na tela de personagens.

Lado: Servidor · Espera: não · Lib: nenhuma

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

Parâmetros

Prop

Type

Retorno

number | null: o id da conta. null quando o jogador não está conectado ou ainda não chegou à tela de personagens.

Exemplo

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

O id da conta FiveM (Cfx.re) do jogador. O ai-core o usa como chave da conta do jogador: um jogador sem um não consegue conectar.

Lado: Servidor · Espera: não · Lib: nenhuma

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

Parâmetros

Prop

Type

Retorno

string | null: o id sem o prefixo fivem: (por exemplo 1234567). null quando o jogador não tem personagem carregado.

Exemplo

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

Um personagem pelo id no banco de dados, carregado ou não, com o id da conta a que pertence. Use para mostrar quem é dono de algo quando essa pessoa pode estar offline.

Lado: Servidor · Espera: não (responde por done) · Lib: nenhuma

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

Parâmetros

Prop

Type

Retorno

Nada. done recebe um CharacterInfo com um campo a mais, userId (o id da conta), ou null para um personagem desconhecido ou apagado, um id errado ou uma leitura que falhou. Sem uma função como done a chamada não faz nada.

Exemplo

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}`);
  });
});

Um personagem gravado fica guardado por 5 minutos depois de lido, então um nome alterado no painel de administração pode mostrar o valor antigo por esse tempo. Um personagem carregado sempre responde da memória.

SwitchCharacter

Manda um jogador de volta para a tela de personagens sem sair do servidor, como um logout. O ai-core salva e descarrega o personagem antes e depois abre a tela.

Lado: Servidor · Espera: não (o descarregamento roda depois que a chamada retorna) · Lib: nenhuma

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

Parâmetros

Prop

Type

Retorno

boolean: true quando a troca começou. false quando o jogador não tem personagem carregado.

Exemplo

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

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

// Um botão "Trocar de personagem" no seu menu.
onClientCallback("myscript:logout", (source) =>
  core.SwitchCharacter(source) ? { ok: true } : fail("NO_CHARACTER"),
);

Seu recurso recebe ai-core:playerUnloaded com o motivo "switch" quando o personagem saiu. Limpe o estado por personagem ali, não logo depois desta chamada.

SetOfflinePosition

Move o ponto de spawn de um personagem que não está carregado: na próxima vez que esse personagem for escolhido, ele aparece ali. Use quando algo move um corpo dormindo ou um personagem offline (um corpo levado embora, um jogador rebocado).

Lado: Servidor · Espera: não (a gravação vem em segundo plano) · Lib: characters.setOfflinePosition

Assinatura
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

Retorno

boolean: true quando a mudança é aceita; a gravação no banco de dados vem assim que nenhum carregamento ou salvamento desse personagem estiver rodando (ela espera até 30 segundos). false quando o personagem está carregado agora, charId não é um número inteiro ou uma coordenada falta ou não é um número finito. Um heading ausente é gravado como 0.

Exemplo

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`);
}

Se o personagem for carregado enquanto a gravação espera, a gravação é pulada: o ped de um personagem carregado está onde realmente está.

GetPlayersInScope

Os jogadores no escopo OneSync de outro jogador: todos cujo jogo transmite esse jogador agora, cerca de 424 metros ao redor. O ai-core mantém esta lista a partir dos eventos de escopo do FiveM uma vez para todos os recursos, então os outros recursos nunca escutam esses eventos eles mesmos.

Lado: Servidor · Espera: não · Lib: playersNear(source, radius) e playersNearEntity(entity, radius) se apoiam nele e filtram pela distância

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

Parâmetros

Prop

Type

Retorno

number[]: os ids de servidor dos outros jogadores no escopo (o próprio jogador não está na lista). Uma lista vazia para um jogador sozinho, um id desconhecido ou um valor que não é número.

Exemplo

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

Como chamar os exports de servidor do ai-core de Lua e TypeScript, e a lista de cada grupo de exports.

Dinheiro e contas

Leia e altere os saldos de um jogador e as contas de empregos e gangues, mova dinheiro entre duas contas numa só transação, leia os tipos de conta.

Nesta página

GetPlayerDataParâmetrosRetornoExemploGetCharacterParâmetrosRetornoExemploGetSourceByCharIdParâmetrosRetornoExemploGetSourceByCitizenIdParâmetrosRetornoExemploGetLoadedSourcesParâmetrosRetornoExemploGetUserIdParâmetrosRetornoExemploGetFivemIdParâmetrosRetornoExemploGetCharacterInfoParâmetrosRetornoExemploSwitchCharacterParâmetrosRetornoExemploSetOfflinePositionParâmetrosRetornoExemploGetPlayersInScopeParâmetrosRetornoExemplo