AI Core
Référence de l’APIAI Core : exports serveur

Personnages stockés

Lire et modifier n'importe quel personnage, chargé ou non - le trouver, le lire, son argent, ses métiers, ses gangs, ses métadonnées et son nom, le sauvegarder, le supprimer.

Les exports de Personnages répondent à propos d'un joueur connecté avec un personnage chargé. Ceux de cette page répondent à propos de n'importe quel personnage, connecté ou non : ai-core lit un personnage chargé depuis la mémoire et un personnage stocké depuis la base, et une écriture atteint le personnage vivant quand il est chargé, sinon la ligne en base.

Trois choses à savoir avant :

  • Un personnage est désigné par son id de personnage (charId, un nombre - CharacterInfo.id). Un citizenid est du texte et appartient aux bridges de framework ; convertissez l'un en l'autre avec GetCharIdByCitizenId, jamais à la main.
  • Ces exports répondent par un callback (done), parce qu'un personnage stocké demande une lecture en base et qu'aucune Promise ne traverse la frontière des resources. En TypeScript, le module characters de la lib vous donne une Promise ; en Lua, aiLib.characters attend pour vous.
  • Chaque écriture répond ActionResult : { ok: true }, ou { ok: false, error: "LANG_KEY" } avec une des clés de langue d'ai-core (locales/en.json), que vous pouvez montrer avec callAction ou traduire vous-même.

Ne lisez et n'écrivez jamais les tables d'ai-core (ai_core_characters, ai_core_accounts, ai_core_character_jobs...) avec vos propres requêtes. Les personnages vivent en mémoire et sont écrits selon le calendrier d'ai-core : un SELECT direct peut être périmé, et les colonnes sont internes.

GetCharIdByCitizenId

L'id de personnage derrière un citizenid, chargé ou non. Un personnage chargé répond depuis la mémoire, un personnage stocké avec une lecture indexée.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.idOf

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

Paramètres

Prop

Type

Retour

Rien. La réponse arrive dans done.

Exemple

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

// La lib emballe le callback dans une 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, "Amende");
  return result.ok;
}

GetOfflineCharacter

Tout ce qu'ai-core garde sur un personnage : nom et date de naissance, 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 : non (la réponse arrive dans done) · Lib : characters.get

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

Paramètres

Retour

Rien. done reçoit un OfflineCharacter ou null. Un personnage chargé répond depuis la mémoire : son argent et ses appartenances sont ceux en cours, et source est le joueur.

Exemple

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

export async function describe(charId: number): Promise<string> {
  const c = await characters.get(charId);
  if (!c) return "personnage inconnu";
  const where = c.source === null ? "hors ligne" : `en ligne (${c.source})`;
  return `${c.info.firstname} ${c.info.lastname} (${where}), banque ${c.money.bank ?? 0}`;
}

SearchCharacters

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

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.search

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

Paramètres

Prop

Type

Retour

Rien. done reçoit une CharacterSearchPage : jusqu'à 25 résultats et le curseur next (null sur la dernière page). Un texte vide répond les personnages les plus récents, donc un écran de parcours fonctionne sans terme de recherche.

Exemple

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

Tous les personnages d'un compte, par slot. Pour un écran qui montre à un joueur tous ses personnages, ou pour un outil d'admin qui travaille sur un compte.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.ofUser

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

Paramètres

Prop

Type

Retour

Rien. done reçoit un tableau de StoredCharacter.

Exemple

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

Tous ceux qui ont un métier (ou sont dans un gang), chargés ou non, page par page et avec leur grade. C'est l'effectif dont un écran de gestion a besoin : le miroir online de la lib ne connaît que les joueurs connectés.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.jobMembers

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

Paramètres

Prop

Type

Retour

Rien. done reçoit une MembersPage : les membres et le after de la page suivante (null sur la dernière). Chaque membre porte source : les connectés sont donc les entrées dont source n'est pas null.

Exemple

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

/** Tous les membres 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;
}

La seule question "est-ce que quelqu'un a ce métier ?" lit une ligne : la lib characters.hasJobMember appelle cet export avec limit = 1.

AddOfflineMoney, RemoveOfflineMoney and SetOfflineMoney

L'argent d'un personnage, chargé ou non. Un personnage chargé passe par son portefeuille en cours (le joueur le voit tout de suite), un personnage stocké est écrit en base avec les mêmes règles et la même ligne de registre.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.addMoney

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

Paramètres

Prop

Type

Retour

Rien. done reçoit { ok: true }, ou { ok: false, error } avec une clé de langue : personnage inconnu, compte que le serveur n'a pas, montant fractionnaire ou négatif, ou - pour RemoveOfflineMoney - un solde qui ne peut pas payer (sauf si le type de compte peut passer sous zéro).

Exemple

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

/** Paie une vente, que le vendeur soit en ligne ou non. */
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;
}

SetOfflineJob and RemoveOfflineJob

Embauche un personnage, change son grade ou le licencie, qu'il soit connecté ou non. Les règles de métier du panneau s'appliquent (combien de métiers un personnage peut avoir, si un second est permis), et le métier de chômeur n'est jamais stocké : retirer le dernier métier rend un personnage sans emploi.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.setJob

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

Paramètres

Prop

Type

Retour

Rien. done reçoit { ok: true }, ou { ok: false, error } avec une clé de langue : personnage inconnu, métier inconnu, grade qui n'existe pas, ou la limite de métiers du panneau.

Exemple

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

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

SetOfflineGang and RemoveOfflineGang

Pareil pour les gangs. Un personnage peut être dans plusieurs gangs mais n'agit que pour un à la fois (SetActiveGang le choisit pour un joueur connecté).

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.setGang

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

Paramètres

Prop

Type

Retour

Rien. done reçoit { ok: true } ou { ok: false, error }, comme pour les métiers.

SetOfflineMeta

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 : son HUD et son interface suivent tout de suite.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.setMeta

Signature
SetOfflineMeta(charId: number, key: string, value: unknown, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:SetOfflineMeta(charId, key, value, function(result) end)

Paramètres

Prop

Type

Retour

Rien. done reçoit { ok: true }, ou { ok: false, error } pour un personnage inconnu ou une valeur que JSON ne peut pas porter.

Exemple

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

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

Pour un joueur connecté, GetMeta / SetMeta est le chemin le plus court, et c'est le seul endroit où lire des métadonnées (cette page n'a pas de GetOfflineMeta : lisez tout le personnage avec GetOfflineCharacter et prenez metadata).

SetCharacterInfo

Change les champs propres du personnage : nom, date de naissance, nationalité, sexe et taille. Chaque champ est vérifié comme le formulaire de création le vérifie, donc un outil d'admin ne peut pas écrire un nom que la création refuserait.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.setInfo

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

Paramètres

Prop

Type

Retour

Rien. done reçoit { ok: true }, ou { ok: false, error } avec une clé de langue. sex est refusé pendant que le personnage est chargé, parce que le modèle du ped le suit ; tout le reste atteint un personnage chargé comme un delta.

Exemple

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

const result = await characters.setInfo(12, { lastname: "Doe-Smith", height: 174 });
if (!result.ok) console.log(`changement de nom refusé : ${result.error}`);

DeleteCharacter

Supprime un personnage. C'est une suppression douce : la ligne reste pour les logs et le personnage disparaît de toutes les listes et de toutes les recherches.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.remove

Signature
DeleteCharacter(charId: number, by?: number | string, done?: (result: CharacterResult) => void): void
Lua
exports['ai-core']:DeleteCharacter(charId, by, function(result) end)

Paramètres

Prop

Type

Retour

Rien. done reçoit { ok: true }, ou { ok: false, error } pour un personnage inconnu ou un personnage chargé en ce moment - le joueur doit d'abord revenir à l'écran des personnages. En cas de succès, ai-core déclenche son événement characterDeleted ; voir Événements et state.

GetPlayTime

Combien de temps un personnage a été joué, en secondes : le total sauvegardé plus la session en cours.

Côté : Serveur · Attend : non pour un joueur connecté · Lib : characters.playTime

Signature
GetPlayTime(target: number | { charId: number }, done?: (seconds: number | null) => void): number | null
Lua
local seconds = exports['ai-core']:GetPlayTime(source) -- un joueur connecté : répond tout de suite
exports['ai-core']:GetPlayTime({ charId = 12 }, function(seconds) end)

Paramètres

Prop

Type

Retour

number | null : les secondes, quand elles sont connues sans lecture en base (un id serveur, ou un { charId } chargé). null veut dire « pas ici, attendez done » - ou, pour un id serveur, que le joueur n'a pas de personnage chargé.

SavePlayer

Écrit tout de suite la position et les métadonnées d'un joueur connecté et attend ses écritures en file. À utiliser avant quelque chose qui ne doit pas perdre les dernières minutes : un redémarrage, une reprise, une action d'admin que vous loguez.

Côté : Serveur · Attend : non (la réponse arrive dans done) · Lib : characters.save

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

Paramètres

Prop

Type

Retour

Rien. ai-core sauvegarde tout seul (périodiquement, au déchargement, à l'arrêt) : vous n'en avez besoin que si l'écriture doit avoir eu lieu avant votre étape suivante.

Un personnage qui n'est pas chargé est déjà écrit : il n'y a rien à vider. Pour déplacer le point d'apparition d'un personnage stocké, utilisez characters.setOfflinePosition (SetOfflinePosition).

Sur cette page