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

Personagens guardadas

Ler e alterar qualquer personagem, carregada ou não - encontrá-la, lê-la, o seu dinheiro, empregos, gangues, metadados e nome, guardá-la, apagá-la.

Os exports de Personagens respondem sobre um jogador ligado com uma personagem carregada. Os desta página respondem sobre qualquer personagem, ligada ou não: o ai-core lê uma personagem carregada da memória e uma guardada da base de dados, e uma escrita chega à personagem viva quando está carregada e à linha quando não está.

Três coisas antes de começar:

  • Uma personagem é endereçada pelo seu id de personagem (charId, um número - CharacterInfo.id). Um citizenid é texto e pertence às bridges de framework; converta um no outro com GetCharIdByCitizenId, nunca à mão.
  • Estes exports respondem por um callback (done), porque uma personagem guardada precisa de uma leitura na base de dados e nenhuma Promise atravessa a fronteira dos resources. Em TypeScript o módulo characters da lib dá-lhe uma Promise; em Lua o aiLib.characters espera por você.
  • Cada escrita responde ActionResult: { ok: true }, ou { ok: false, error: "LANG_KEY" } com uma das chaves de idioma do ai-core (locales/en.json), que pode mostrar com callAction ou traduzir você mesmo.

Nunca leia nem escreva as tabelas do ai-core (ai_core_characters, ai_core_accounts, ai_core_character_jobs...) com as suas próprias consultas. As personagens vivem em memória e são escritas no calendário do ai-core, por isso um SELECT direto pode estar desatualizado e as colunas são internas.

GetCharIdByCitizenId

O id de personagem por trás de um citizenid, carregada ou não. Uma personagem carregada responde da memória, uma guardada com uma leitura indexada.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.idOf

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

Parâmetros

Prop

Type

Retorno

Nada. A resposta chega em done.

Exemplo

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

// A lib embrulha o callback numa 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

Tudo o que o ai-core guarda sobre uma personagem: nome e data de nascimento, dinheiro por conta, empregos, gangues, metadados, posição guardada, última gravação, e o id de servidor quando está carregada.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.get

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

Parâmetros

Retorno

Nada. O done recebe um OfflineCharacter ou null. Uma personagem carregada responde da memória, por isso o seu dinheiro e as suas pertenças são os atuais e o source é o jogador.

Exemplo

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

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

SearchCharacters

Personagens a partir de um texto escrito, carregadas ou não: prefixos de nome ou apelido ("jane doe" também), citizenid, id de fivem / license / discord. 25 por página, a personagem mais recente primeiro.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.search

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

Parâmetros

Prop

Type

Retorno

Nada. O done recebe uma CharacterSearchPage: até 25 resultados e o cursor next (null na última página). Um texto vazio responde as personagens mais recentes, por isso um ecrã de listagem funciona sem termo de busca.

Exemplo

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

Todas as personagens de uma conta, por slot. Para um ecrã que mostra a um jogador todas as suas personagens, ou para uma ferramenta de admin que trabalha sobre uma conta.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.ofUser

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

Parâmetros

Prop

Type

Retorno

Nada. O done recebe um array de StoredCharacter.

Exemplo

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 os que têm um emprego (ou estão numa gangue), carregados ou não, página a página e com o seu grau. É o quadro de pessoal de que um ecrã de gestão precisa: o espelho online da lib só conhece os jogadores ligados.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.jobMembers

Assinatura
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

Retorno

Nada. O done recebe uma MembersPage: os membros e o after da página seguinte (null na última). Cada membro leva source, por isso os ligados são as entradas cujo source não é null.

Exemplo

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

/** Todos os membros de um emprego, 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;
}

Só a pergunta "há alguém com este emprego?" lê uma linha: a lib characters.hasJobMember chama este export com limit = 1.

AddOfflineMoney, RemoveOfflineMoney and SetOfflineMoney

O dinheiro de uma personagem, carregada ou não. Uma personagem carregada passa pela sua carteira viva (o jogador vê logo); uma guardada é escrita na base de dados com as mesmas regras e a mesma linha de registo.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.addMoney

Assinatura
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

Retorno

Nada. O done recebe { ok: true }, ou { ok: false, error } com uma chave de idioma: personagem desconhecida, uma conta que o servidor não tem, um valor fracionado ou negativo, ou - no RemoveOfflineMoney - um saldo que não pode pagar (a menos que o tipo de conta possa ir abaixo de zero).

Exemplo

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

/** Paga uma venda, esteja o vendedor online ou não. */
export async function payOut(charId: number, amount: number): Promise<boolean> {
  const result = await characters.addMoney(charId, "bank", amount, "Veículo vendido");
  if (!result.ok) console.log(`pagamento recusado: ${result.error}`);
  return result.ok;
}

SetOfflineJob and RemoveOfflineJob

Contrata uma personagem, muda-lhe o grau ou despede-a, esteja ligada ou não. Aplicam-se as regras de emprego do painel (quantos empregos uma personagem pode ter, se é permitido um segundo), e o emprego de desempregado nunca é guardado: retirar o último emprego é o que deixa uma personagem sem emprego.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.setJob

Assinatura
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

Retorno

Nada. O done recebe { ok: true }, ou { ok: false, error } com uma chave de idioma: personagem desconhecida, emprego desconhecido, um grau que não existe, ou o limite de empregos do painel.

Exemplo

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

/** Despede um membro, online ou não. */
export async function fire(charId: number, job: string): Promise<boolean> {
  return (await characters.removeJob(charId, job)).ok;
}

SetOfflineGang and RemoveOfflineGang

O mesmo para gangues. Uma personagem pode estar em várias gangues mas age por uma de cada vez (SetActiveGang escolhe-a para um jogador ligado).

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.setGang

Assinatura
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

Retorno

Nada. O done recebe { ok: true } ou { ok: false, error }, como nos empregos.

SetOfflineMeta

Um valor de metadados de uma personagem, carregada ou não. Uma personagem carregada recebe-o como um delta no seu próprio jogo, por isso o HUD e a interface seguem logo.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.setMeta

Assinatura
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

Retorno

Nada. O done recebe { ok: true }, ou { ok: false, error } para uma personagem desconhecida ou um valor que o JSON não pode guardar.

Exemplo

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

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

Para um jogador ligado, GetMeta / SetMeta é o caminho curto, e ler metadados só é possível aí (esta página não tem GetOfflineMeta: leia a personagem toda com GetOfflineCharacter e tire o metadata).

SetCharacterInfo

Altera os campos próprios da personagem: nome, data de nascimento, nacionalidade, sexo e altura. Cada campo é verificado como o formulário de criação o verifica, por isso uma ferramenta de admin não pode escrever um nome que a criação recusaria.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.setInfo

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

Parâmetros

Prop

Type

Retorno

Nada. O done recebe { ok: true }, ou { ok: false, error } com uma chave de idioma. O sex é recusado enquanto a personagem está carregada, porque o modelo do ped o segue; todo o resto chega a uma personagem carregada como um delta.

Exemplo

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

const result = await characters.setInfo(12, { lastname: "Doe-Smith", height: 174 });
if (!result.ok) console.log(`mudança de nome recusada: ${result.error}`);

DeleteCharacter

Apaga uma personagem. É um apagamento suave: a linha fica para os logs e a personagem desaparece de todas as listas e de todas as buscas.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.remove

Assinatura
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

Retorno

Nada. O done recebe { ok: true }, ou { ok: false, error } para uma personagem desconhecida ou uma que está carregada agora - o jogador tem de voltar primeiro ao ecrã de personagens. Em caso de sucesso, o ai-core dispara o seu evento characterDeleted; ver Eventos e estado.

GetPlayTime

Quanto tempo uma personagem foi jogada, em segundos: o total guardado mais a sessão a correr.

Lado: Servidor · Espera: não para um jogador ligado · Lib: characters.playTime

Assinatura
GetPlayTime(target: number | { charId: number }, done?: (seconds: number | null) => void): number | null
Lua
local seconds = exports['ai-core']:GetPlayTime(source) -- um jogador ligado: responde logo
exports['ai-core']:GetPlayTime({ charId = 12 }, function(seconds) end)

Parâmetros

Prop

Type

Retorno

number | null: os segundos, quando são conhecidos sem leitura na base de dados (um id de servidor, ou um { charId } carregado). null significa "não está aqui, espere pelo done" - ou, para um id de servidor, que o jogador não tem personagem carregada.

SavePlayer

Escreve agora a posição e os metadados de um jogador ligado e espera pelas suas escritas em fila. Use-o antes de algo que não pode perder os últimos minutos: um reinício, uma passagem, uma ação de admin que registe.

Lado: Servidor · Espera: não (a resposta chega em done) · Lib: characters.save

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

Parâmetros

Prop

Type

Retorno

Nada. O ai-core guarda por si (periodicamente, ao descarregar e ao desligar), por isso só precisa disto quando a escrita tiver de ter acontecido antes do seu passo seguinte.

Uma personagem que não está carregada já está escrita: não há nada para esvaziar. Para mover o ponto de spawn de uma personagem guardada use characters.setOfflinePosition (SetOfflinePosition).

Nesta página