Données du panneau

Les réglages de votre script se trouvent dans des fichiers data/*.json que le propriétaire du serveur modifie dans le panneau d’administration d’ai-core (voir Panneau d’administration). Le panneau vérifie les valeurs par rapport à votre schema.ts, mais un fichier peut tout de même être ancien, modifié à la main ou privé d’un champ. Les lecteurs de cette page ne refusent jamais : une valeur manquante ou fausse donne la valeur de repli que vous passez, et le script démarre donc toujours.

Pour les valeurs qu’envoie un client, utilisez plutôt les lecteurs stricts de Actions et entrées du client : eux refusent une mauvaise valeur.

import { num, int, bool, str, record, vec4, spec, readRecords, withoutSchemaKey } from "@aicore-fivem/lib/shared";

Lua : aucun de ces utilitaires n’a d’équivalent Lua (le panneau d’administration et ses fichiers de données sont uniquement en TypeScript).

Lecteurs de valeursCopy Anchor Link

numCopy Anchor Link

Un nombre fini borné à [min, max], sinon la valeur de repli.

Côté : client, serveur et NUI · Attend : non

num(value: unknown, fallback: number, min?: number, max?: number): number

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number : la valeur bornée dans l’intervalle, ou fallback (non borné).

ExempleCopy Anchor Link

import { num } from "@aicore-fivem/lib/shared";

num(25, 2.5, 1, 20);      // 20 (borné)
num("big", 2.5, 1, 20);   // 2.5 (repli)

intCopy Anchor Link

Comme num, puis arrondi à un nombre entier.

Côté : client, serveur et NUI · Attend : non

int(value: unknown, fallback: number, min?: number, max?: number): number

ParamètresCopy Anchor Link

RetourCopy Anchor Link

number : un nombre entier (la valeur de repli est arrondie aussi).

ExempleCopy Anchor Link

import { int } from "@aicore-fivem/lib/shared";

int(12.6, 10, 0, 100); // 13
int(null, 10, 0, 100); // 10

boolCopy Anchor Link

Un booléen, sinon la valeur de repli.

Côté : client, serveur et NUI · Attend : non

bool(value: unknown, fallback: boolean): boolean

ParamètresCopy Anchor Link

RetourCopy Anchor Link

boolean.

ExempleCopy Anchor Link

import { bool } from "@aicore-fivem/lib/shared";

bool(true, false);   // true
bool("yes", false);  // false (repli)

strCopy Anchor Link

Une chaîne non vide, sans espaces autour, coupée à max caractères, sinon la valeur de repli.

Côté : client, serveur et NUI · Attend : non

str(value: unknown, fallback: string, max?: number): string

ParamètresCopy Anchor Link

RetourCopy Anchor Link

string.

ExempleCopy Anchor Link

import { str } from "@aicore-fivem/lib/shared";

str("  City Hall ", "Hall", 48); // "City Hall"
str("", "Hall", 48);             // "Hall"

recordCopy Anchor Link

La valeur sous forme d’objet simple, ou un objet vide {}. Utilisez-le avant de lire les champs d’une valeur qui peut manquer.

Côté : client, serveur et NUI · Attend : non

record(value: unknown): Record<string, unknown>

ParamètresCopy Anchor Link

RetourCopy Anchor Link

value lui-même quand c’est un objet simple, sinon un nouveau {} (aussi pour les tableaux et null).

ExempleCopy Anchor Link

import { num, record } from "@aicore-fivem/lib/shared";

function readCoords(raw: unknown) {
  const c = record(raw); // {} quand le champ manque
  return { x: num(c.x, 0), y: num(c.y, 0), z: num(c.z, 0) };
}

vec4Copy Anchor Link

Une position avec un cap ; chaque champ manquant ou faux vient de la valeur de repli.

Côté : client, serveur et NUI · Attend : non

vec4(value: unknown, fallback: Vec4): Vec4

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Un nouveau Vec4.

ExempleCopy Anchor Link

import { vec4 } from "@aicore-fivem/lib/shared";

vec4({ x: 10, y: 20, z: 30 }, { x: 0, y: 0, z: 0, heading: 90 }); // { x: 10, y: 20, z: 30, heading: 90 }

Utilitaires de schémaCopy Anchor Link

specCopy Anchor Link

Des constructeurs pour les champs numériques de votre schema.ts de panneau, pour ne pas écrire le même objet DataSpec à la main.

Côté : client, serveur et NUI · Attend : non

spec.int(min: number, max: number, optional?: boolean): DataSpec
spec.num(min: number, max: number, optional?: boolean): DataSpec

ParamètresCopy Anchor Link

RetourCopy Anchor Link

DataSpec : { type: "number", min, max }, plus integer: true pour spec.int et optional: true sur demande.

ExempleCopy Anchor Link

import { spec } from "@aicore-fivem/lib/shared";
import type { PanelSchema } from "@aicore-fivem/shared";

export const schema: PanelSchema = {
  title: "ADMIN_TITLE",
  icon: "store",
  files: {
    settings: {
      kind: "settings",
      sync: "admin",
      sections: {
        prices: { type: "object", fields: { water: spec.int(0, 1_000_000), tax: spec.num(0, 0.5) } },
      },
    },
  },
  tabs: [], // la disposition du panneau (cartes et champs), voir Panneau d’administration
};

withoutSchemaKeyCopy Anchor Link

Retire la clé "$schema" du contenu d’un fichier de données. La clé n’est là que pour que les éditeurs de code puissent vérifier le fichier ; votre lecteur ne doit pas la voir.

Côté : client, serveur et NUI · Attend : non

withoutSchemaKey(value: unknown): unknown

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Une copie sans $schema quand la valeur est un objet qui l’a ; sinon value inchangé.

ExempleCopy Anchor Link

import { withoutSchemaKey } from "@aicore-fivem/lib/shared";

withoutSchemaKey({ $schema: "./schemas/shops.schema.json", legion: { label: "Legion" } });
// { legion: { label: "Legion" } }

Fichiers d’enregistrementsCopy Anchor Link

Un fichier d’enregistrements (records) contient de nombreuses entrées par clé ({ "legion": {...}, "pillbox": {...} }) : magasins, garages, mairies. Chaque entrée est lue par votre propre fonction de lecture (RecordReader<T> = (key: string, raw: Record<string, unknown>) => T | null), construite avec les lecteurs de valeurs ci-dessus.

readRecordsCopy Anchor Link

Lit en une fois tout un fichier d’enregistrements dans une Map, une entrée par clé, via votre lecteur. Les entrées qui ne sont pas des objets, ou pour lesquelles votre lecteur renvoie null, sont laissées de côté.

Côté : client, serveur et NUI · Attend : non

readRecords<T>(raw: unknown, readOne: RecordReader<T>): Map<string, T>

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Map<string, T> : les entrées parsées par clé.

ExempleCopy Anchor Link

import { readRecords, str, num, record } from "@aicore-fivem/lib/shared";

type Shop = { label: string; x: number; y: number; z: number };

const readShop = (key: string, v: Record<string, unknown>): Shop => {
  const c = record(v.coords);
  return { label: str(v.label, key, 48), x: num(c.x, 0), y: num(c.y, 0), z: num(c.z, 0) };
};

const shops = readRecords({ legion: { label: "Legion", coords: { x: 25.7, y: -1347.3, z: 29.5 } } }, readShop);
shops.get("legion"); // { label: "Legion", x: 25.7, y: -1347.3, z: 29.5 }

RecordObjectsCopy Anchor Link

Garde les objets du monde d’un fichier d’enregistrements (points, blips, peds, zones) synchronisés avec le panneau, une entrée à la fois : une entrée modifiée ne reconstruit que ses propres objets. Elle est exportée depuis @aicore-fivem/lib/shared et n’a pas d’équivalent Lua. Sa référence complète (constructeur, fonction build, rebuild, rebuildAll, exemple) se trouve sur Points d’interaction : RecordObjects.