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.
import { characters } from "@aicore8/lib/server";-- 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
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
characters.get(charId: number): Promise<OfflineCharacter | null>local character = aiLib.characters.get(charId) -- table ou nilParamè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
characters.search(text: string, cursor?: number): Promise<CharacterSearchPage>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
characters.ofUser(user: number | string): Promise<StoredCharacter[]>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
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)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
characters.hasJobMember(job: string): Promise<boolean>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
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)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
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)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
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)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
characters.setMeta(charId: number, key: string, value: unknown): Promise<CharacterResult>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
characters.setInfo(charId: number, patch: CharacterInfoPatch): Promise<CharacterResult>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
characters.remove(charId: number, by?: number | string): Promise<CharacterResult>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
characters.playTime(target: number | { charId: number }): Promise<number | null>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
characters.save(source: number): Promise<boolean>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 voulez | Où |
|---|---|
| Le point d'apparition d'un personnage stocké | characters.setOfflinePosition |
| Qui est connecté, les noms, les métiers et le service | online |
| Les métiers et gangs d'un joueur chargé | jobs |
| L'argent d'un joueur chargé | money |
| Le registre d'un personnage | money.history |
Joueurs et personnages
online, onCharacter, notify, joueurs proches, positions et stockages par joueur : PlayerMap, Cooldowns, KeyedCooldowns, SourceLock, RateLimit, KeyWatchers.
Objets
inventory : donner, retirer et compter des objets, coffres, boutiques et objets utilisables, quel que soit l’inventaire que fait tourner le serveur.