AI Core
Referência da APILib: servidor

Personagens, carregadas ou não

O módulo characters: encontre, leia e altere qualquer personagem através do ai-core - dinheiro, empregos, gangues, metadados, nome, tempo de jogo - com uma Promise em TypeScript e uma espera simples em Lua.

TypeScript
import { characters } from "@aicore8/lib/server";
Lua
-- aiLib.characters, depois de shared_script '@ai-lib/init.lua'

characters é a porta da lib para os exports de personagens guardadas do ai-core. Existe porque esses exports respondem por um callback: a lib transforma cada um numa Promise em TypeScript e numa espera simples em Lua, por isso o seu código lê-se de cima para baixo.

  • Uma personagem é nomeada pelo seu id de personagem (charId, um número). A partir de um citizenid: characters.idOf.
  • Uma personagem carregada responde da memória (dinheiro e pertenças atuais); uma guardada é lida da base de dados enquanto o ai-core a mantém, por isso não pode carregar no meio de uma escrita.
  • Cada escrita responde ActionResult: { ok: true }, ou { ok: false, error } com uma chave de idioma do ai-core.
  • Todas as funções aqui esperam. Em Lua isso significa chamá-las de dentro de uma thread; ver Funções que esperam.

Para o jogador de que a ação trata, o caminho curto costuma ser o ai-core diretamente: GetCharacter, money, jobs. Use characters quando o alvo pode estar offline, ou quando precisa de uma personagem inteira de uma vez.

characters

characters.idOf

O id de personagem por trás de um citizenid.

Lado: Servidor · Espera: sim

Assinatura
characters.idOf(citizenid: string): Promise<number | null>

Sem equivalente em Lua: chame o export GetCharIdByCitizenId do ai-core e espere pelo seu callback.

Parâmetros

Prop

Type

Retorno

Promise<number | null>: o id da personagem, ou null quando nenhuma personagem tem esse citizenid ou foi apagada.

Exemplo

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

/** Uma multa que funciona esteja o condutor online ou não. */
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

Uma personagem com tudo o que o ai-core guarda sobre ela: dados, dinheiro por conta, empregos, gangues, metadados, posição guardada, última gravação, e o id de servidor quando está carregada.

Lado: Servidor · Espera: sim

Assinatura
characters.get(charId: number): Promise<OfflineCharacter | null>
Lua
local character = aiLib.characters.get(charId) -- tabela ou nil

Parâmetros

Prop

Type

Retorno

Um OfflineCharacter, ou null / nil quando o id é desconhecido ou a personagem foi apagada.

Exemplo

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

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

Lado: Servidor · Espera: sim

Assinatura
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>
Lua
local page = aiLib.characters.search(text, cursor)

Parâmetros

Prop

Type

Retorno

Uma CharacterSearchPage: characters (até 25) e next (null na última página). Em caso de erro responde uma página vazia, nunca null.

Exemplo

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

Todas as personagens de uma conta, por slot.

Lado: Servidor · Espera: sim

Assinatura
characters.ofUser(user: number | string): Promise<StoredCharacter[]>
Lua
local list = aiLib.characters.ofUser(user)

Parâmetros

Prop

Type

Retorno

Um array de StoredCharacter, por slot. Vazio para uma conta desconhecida.

characters.jobMembers and characters.gangMembers

Todos os que têm um emprego ou estão numa gangue, carregados ou não - página a página, com o seu grau e com o seu id de servidor quando estão ligados.

Lado: Servidor · Espera: sim

Assinatura
characters.jobMembers(job: string, after?: number, limit?: number): Promise<MembersPage>
characters.gangMembers(gang: string, after?: number, limit?: number): Promise<MembersPage>
Lua
local page = aiLib.characters.jobMembers(job, after, limit)
local page = aiLib.characters.gangMembers(gang, after, limit)

Parâmetros

Prop

Type

Retorno

Uma MembersPage: members e next (null na última página).

Exemplo

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

/** Todo o quadro de pessoal 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;
}

Contar os jogadores ligados de um emprego não é isto: isso é o espelho da lib, online.jobMembers (sem chamada de export e sem leitura na base de dados).

characters.hasJobMember

Se há alguém com um emprego, carregado ou não. É lida uma linha, por isso é barato o suficiente para uma verificação no arranque ("este servidor tem polícia?").

Lado: Servidor · Espera: sim

Assinatura
characters.hasJobMember(job: string): Promise<boolean>
Lua
local anyone = aiLib.characters.hasJobMember(job)

Retorno

true quando ao menos uma personagem tem o emprego.

characters.addMoney, characters.removeMoney and characters.setMoney

O dinheiro de uma personagem, carregada ou não, com uma linha de registo. Uma personagem carregada passa pela sua carteira viva, por isso o jogador vê a alteração logo.

Lado: Servidor · Espera: sim

Assinatura
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>
Lua
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

Retorno

{ ok: true }, ou { ok: false, error } com uma chave de idioma: personagem desconhecida, conta desconhecida, valor fracionado ou negativo, ou um saldo que não pode pagar (removeMoney, a menos que o tipo de conta possa ir abaixo de zero).

Exemplo

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

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

Mover dinheiro entre duas contas é uma chamada e uma transação: money.transfer. O registo de uma personagem guardada é money.history com { owner: "character", id, account }.

characters.setJob and characters.removeJob

Contrata uma personagem, muda-lhe o grau ou despede-a, online ou não. Aplicam-se as regras de emprego do painel, e o emprego de desempregado nunca é guardado: retirar o último emprego deixa a personagem sem emprego.

Lado: Servidor · Espera: sim

Assinatura
characters.setJob(charId: number, job: string, grade: number): Promise<CharacterResult>
characters.removeJob(charId: number, job: string): Promise<CharacterResult>
Lua
local result = aiLib.characters.setJob(charId, job, grade)
local result = aiLib.characters.removeJob(charId, job)

Parâmetros

Prop

Type

Retorno

{ ok: true }, ou { ok: false, error }: personagem desconhecida, emprego desconhecido, grau desconhecido, ou o limite do painel sobre quantos empregos uma personagem pode ter.

Exemplo

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

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

characters.setGang and characters.removeGang

O mesmo para gangues.

Lado: Servidor · Espera: sim

Assinatura
characters.setGang(charId: number, gang: string, grade: number): Promise<CharacterResult>
characters.removeGang(charId: number, gang: string): Promise<CharacterResult>
Lua
local result = aiLib.characters.setGang(charId, gang, grade)
local result = aiLib.characters.removeGang(charId, gang)

Retorno

{ ok: true } ou { ok: false, error }, como nos empregos.

characters.setMeta

Um valor de metadados de uma personagem, carregada ou não. Uma personagem carregada recebe-o como um delta no seu próprio jogo.

Lado: Servidor · Espera: sim

Assinatura
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>
Lua
local result = aiLib.characters.setMeta(charId, key, value)

Parâmetros

Prop

Type

Retorno

{ ok: true }, ou { ok: false, error } para uma personagem desconhecida ou um valor que o JSON não pode guardar. Ler metadados faz parte de characters.get; para um jogador ligado use GetMeta.

characters.setInfo

Nome, data de nascimento, nacionalidade, sexo e altura, cada um verificado como o formulário de criação o verifica.

Lado: Servidor · Espera: sim

Assinatura
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>
Lua
local result = aiLib.characters.setInfo(charId, patch)

Parâmetros

Prop

Type

Retorno

{ ok: true }, ou { ok: false, error } com uma chave de idioma (um nome que a criação recusaria, uma data que não é YYYY-MM-DD, sex numa personagem carregada).

characters.remove

Apaga uma personagem (apagamento suave: a linha fica para os logs).

Lado: Servidor · Espera: sim

Assinatura
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>
Lua
local result = aiLib.characters.remove(charId, by)

Parâmetros

Prop

Type

Retorno

{ ok: true }, ou { ok: false, error } para uma personagem desconhecida ou uma que está carregada agora.

characters.playTime

Os segundos de jogo de uma personagem: o total guardado mais a sessão a correr.

Lado: Servidor · Espera: sim

Assinatura
characters.playTime(target: number | { charId: number }): Promise<number | null>
Lua
local seconds = aiLib.characters.playTime(target)

Parâmetros

Prop

Type

Retorno

Os segundos, ou null para uma personagem desconhecida (ou um id de servidor sem personagem carregada).

characters.save

Escreve agora a posição e os metadados de um jogador ligado e espera pelas suas escritas em fila.

Lado: Servidor · Espera: sim

Assinatura
characters.save(source: number): Promise<boolean>
Lua
local ok = aiLib.characters.save(source)

Retorno

true quando tudo está escrito, false quando o jogador não tem personagem carregada. O ai-core guarda por si (periodicamente, ao descarregar, ao desligar): use isto só quando a escrita tiver de ter acontecido antes do seu passo seguinte.

Noutros lugares da lib

QuerOnde
O ponto de spawn de uma personagem guardadacharacters.setOfflinePosition
Quem está ligado, os nomes, os empregos e o serviçoonline
Os empregos e gangues de um jogador carregadojobs
O dinheiro de um jogador carregadomoney
O registo de uma personagemmoney.history

Nesta página