AI Core
Référence de l’APILib : serveur

Personnages, chargés ou non

Le module characters : trouver, lire et modifier n'importe quel personnage via ai-core - argent, métiers, gangs, métadonnées, nom, temps de jeu - avec une Promise en TypeScript et une attente simple en Lua.

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

characters est la porte de la lib vers les exports de personnages stockés d'ai-core. Elle existe parce que ces exports répondent par un callback : la lib en fait une Promise en TypeScript et une attente simple en Lua, votre code se lit donc de haut en bas.

  • Un personnage est nommé par son id de personnage (charId, un nombre). À partir d'un citizenid : characters.idOf.
  • Un personnage chargé répond depuis la mémoire (argent et appartenances en cours) ; un personnage stocké est lu en base pendant qu'ai-core le tient, il ne peut donc pas se charger au milieu d'une écriture.
  • Chaque écriture répond ActionResult : { ok: true }, ou { ok: false, error } avec une clé de langue d'ai-core.
  • Toutes les fonctions ici attendent. En Lua, cela veut dire les appeler depuis un thread ; voir Fonctions qui attendent.

Pour le joueur dont il est question, le chemin le plus court est souvent ai-core directement : GetCharacter, money, jobs. Utilisez characters quand la cible peut être hors ligne, ou quand vous voulez un personnage entier d'un coup.

characters

characters.idOf

L'id de personnage derrière un citizenid.

Côté : serveur · Attend : oui

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

Pas d'équivalent Lua : appelez l'export GetCharIdByCitizenId d'ai-core et attendez son callback.

Paramètres

Prop

Type

Retour

Promise<number | null> : l'id du personnage, ou null si aucun personnage n'a ce citizenid ou s'il a été supprimé.

Exemple

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

/** Une amende qui marche, que le conducteur soit en ligne ou non. */
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, "Amende")).ok;
}

characters.get

Un personnage avec tout ce qu'ai-core garde sur lui : infos, argent par compte, métiers, gangs, métadonnées, position stockée, dernière sauvegarde, et l'id serveur quand il est chargé.

Côté : serveur · Attend : oui

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

Paramètres

Prop

Type

Retour

Un OfflineCharacter, ou null / nil si l'id est inconnu ou le personnage supprimé.

Exemple

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

Des personnages à partir d'un texte tapé, chargés ou non : préfixes de nom ("jane doe" aussi), citizenid, id fivem / license / discord. 25 par page, les plus récents en premier.

Côté : serveur · Attend : oui

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

Paramètres

Prop

Type

Retour

Une CharacterSearchPage : characters (jusqu'à 25) et next (null sur la dernière page). En cas d'erreur, elle répond une page vide, jamais null.

Exemple

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

Tous les personnages d'un compte, par slot.

Côté : serveur · Attend : oui

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

Paramètres

Prop

Type

Retour

Un tableau de StoredCharacter, par slot. Vide pour un compte inconnu.

characters.jobMembers and characters.gangMembers

Tous ceux qui ont un métier ou sont dans un gang, chargés ou non - page par page, avec leur grade et leur id serveur quand ils sont connectés.

Côté : serveur · Attend : oui

Signature
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)

Paramètres

Prop

Type

Retour

Une MembersPage : members et next (null sur la dernière page).

Exemple

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

/** Tout l'effectif d'un métier, page par page. */
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;
}

Compter les joueurs connectés d'un métier, ce n'est pas ceci : c'est le miroir de la lib, online.jobMembers (aucun appel d'export, aucune lecture en base).

characters.hasJobMember

Si quelqu'un a ce métier, chargé ou non. Une seule ligne est lue : assez léger pour une vérification au démarrage (« ce serveur a-t-il une police ? »).

Côté : serveur · Attend : oui

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

Retour

true quand au moins un personnage a ce métier.

characters.addMoney, characters.removeMoney and characters.setMoney

L'argent d'un personnage, chargé ou non, avec une ligne de registre. Un personnage chargé passe par son portefeuille en cours : le joueur voit le changement tout de suite.

Côté : serveur · Attend : oui

Signature
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)

Paramètres

Prop

Type

Retour

{ ok: true }, ou { ok: false, error } avec une clé de langue : personnage inconnu, compte inconnu, montant fractionnaire ou négatif, ou un solde qui ne peut pas payer (removeMoney, sauf si le type de compte peut passer sous zéro).

Exemple

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

export async function payOut(charId: number, amount: number): Promise<boolean> {
  const result = await characters.addMoney(charId, "bank", amount, "Véhicule vendu");
  if (!result.ok) console.log(`paiement refusé : ${result.error}`);
  return result.ok;
}

Déplacer de l'argent entre deux comptes est un seul appel et une seule transaction : money.transfer. Le registre d'un personnage stocké est money.history avec { owner: "character", id, account }.

characters.setJob and characters.removeJob

Embauche un personnage, change son grade ou le licencie, en ligne ou non. Les règles de métier du panneau s'appliquent, et le métier de chômeur n'est jamais stocké : retirer le dernier métier rend le personnage sans emploi.

Côté : serveur · Attend : oui

Signature
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)

Paramètres

Prop

Type

Retour

{ ok: true }, ou { ok: false, error } : personnage inconnu, métier inconnu, grade inconnu, ou la limite du panneau sur le nombre de métiers.

Exemple

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

/** Licencier un membre, en ligne ou non. */
export async function fire(charId: number, job: string): Promise<boolean> {
  return (await characters.removeJob(charId, job)).ok;
}

characters.setGang and characters.removeGang

Pareil pour les gangs.

Côté : serveur · Attend : oui

Signature
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)

Retour

{ ok: true } ou { ok: false, error }, comme pour les métiers.

characters.setMeta

Une valeur de métadonnées d'un personnage, chargé ou non. Un personnage chargé la reçoit comme un delta sur son propre jeu.

Côté : serveur · Attend : oui

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

Paramètres

Prop

Type

Retour

{ ok: true }, ou { ok: false, error } pour un personnage inconnu ou une valeur que JSON ne peut pas porter. Lire les métadonnées fait partie de characters.get ; pour un joueur connecté, utilisez GetMeta.

characters.setInfo

Nom, date de naissance, nationalité, sexe et taille, chacun vérifié comme le formulaire de création le vérifie.

Côté : serveur · Attend : oui

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

Paramètres

Prop

Type

Retour

{ ok: true }, ou { ok: false, error } avec une clé de langue (un nom que la création refuserait, une date qui n'est pas YYYY-MM-DD, sex sur un personnage chargé).

characters.remove

Supprime un personnage (suppression douce : la ligne reste pour les logs).

Côté : serveur · Attend : oui

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

Paramètres

Prop

Type

Retour

{ ok: true }, ou { ok: false, error } pour un personnage inconnu ou un personnage chargé en ce moment.

characters.playTime

Les secondes de jeu d'un personnage : le total sauvegardé plus la session en cours.

Côté : serveur · Attend : oui

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

Paramètres

Prop

Type

Retour

Les secondes, ou null pour un personnage inconnu (ou un id serveur sans personnage chargé).

characters.save

Écrit tout de suite la position et les métadonnées d'un joueur connecté et attend ses écritures en file.

Côté : serveur · Attend : oui

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

Retour

true quand tout est écrit, false quand le joueur n'a pas de personnage chargé. ai-core sauvegarde tout seul (périodiquement, au déchargement, à l'arrêt) : n'utilisez ceci que si l'écriture doit avoir eu lieu avant votre étape suivante.

Ailleurs dans la lib

Vous voulezOù
Le point d'apparition d'un personnage stockécharacters.setOfflinePosition
Qui est connecté, les noms, les métiers et le serviceonline
Les métiers et gangs d'un joueur chargéjobs
L'argent d'un joueur chargémoney
Le registre d'un personnagemoney.history

Sur cette page