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.
import { characters } from "@aicore8/lib/server";-- 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
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
characters.get(charId: number): Promise<OfflineCharacter | null>local character = aiLib.characters.get(charId) -- tabela ou nilParâ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
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>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
characters.ofUser(user: number | string): Promise<StoredCharacter[]>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
characters.jobMembers(job: string, after?: number, limit?: number): Promise<MembersPage>
characters.gangMembers(gang: string, after?: number, limit?: number): Promise<MembersPage>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
characters.hasJobMember(job: string): Promise<boolean>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
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>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
characters.setJob(charId: number, job: string, grade: number): Promise<CharacterResult>
characters.removeJob(charId: number, job: string): Promise<CharacterResult>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
characters.setGang(charId: number, gang: string, grade: number): Promise<CharacterResult>
characters.removeGang(charId: number, gang: string): Promise<CharacterResult>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
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>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
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>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
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>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
characters.playTime(target: number | { charId: number }): Promise<number | null>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
characters.save(source: number): Promise<boolean>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
| Quer | Onde |
|---|---|
| O ponto de spawn de uma personagem guardada | characters.setOfflinePosition |
| Quem está ligado, os nomes, os empregos e o serviço | online |
| Os empregos e gangues de um jogador carregado | jobs |
| O dinheiro de um jogador carregado | money |
| O registo de uma personagem | money.history |