State bags

Un state bag est une valeur que FiveM copie du serveur vers les clients qui en ont besoin : le carburant d’un véhicule (Entity(vehicle).state.fuel), le fait qu’un joueur soit à terre (Player(id).state.dead), un indicateur valable pour tout le serveur (GlobalState["ai:pvp"]).

Lire un bag directement est lent : chaque lecture construit des proxys, appelle plusieurs natives et décode à nouveau la valeur. Ces classes gardent un seul gestionnaire de changement par clé et une copie de chaque valeur en mémoire : une lecture n’est donc qu’une recherche dans une map. Utilisez-les pour tout bag que vous lisez plus d’une fois.

import { EntityState, PlayerState, GlobalKey, GlobalGroup, stateNumber, stateBoolean, stateString } from "@aicore-fivem/lib/client";

import { EntityState, PlayerState, GlobalKey, GlobalGroup, stateNumber, stateBoolean, stateString } from "@aicore-fivem/lib/server";

Les classes ne sont pas sur @aicore-fivem/lib/fivem : importez-les depuis l’entrée client ou serveur. Seul le serveur écrit les state bags (sv_stateBagStrictMode) ; un client demande au serveur via un callback et le serveur définit la valeur. Les méthodes set du serveur se trouvent sur Lib : serveur, State bags.

Lua : aucun de ces utilitaires n’a d’équivalent Lua. Lua lit les bags lui-même (Entity(vehicle).state.fuel, Player(id).state.dead, GlobalState['ai:pvp']) et les écoute avec AddStateBagChangeHandler.

Les clés qu’utilisent ai-core et les scripts ai-* sont listées sur Événements et état.

ParseursCopy Anchor Link

Chaque classe prend un parseur : une fonction qui transforme la valeur répliquée brute en votre type, ou en undefined quand ce n’est pas une valeur valide. Le type est StateParse<T> = (value: unknown) => T | undefined. Un bag vidé (null) est toujours lu comme undefined ; le parseur ne le voit jamais.

stateNumberCopy Anchor Link

Accepte un nombre fini ; toute autre chose (texte, NaN, Infinity) est lue comme undefined.

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

stateNumber: StateParse<number>

ExempleCopy Anchor Link

import { EntityState, stateNumber } from "@aicore-fivem/lib/client";

const fuel = new EntityState("fuel", stateNumber); // 0-100, défini par le script de carburant

stateBooleanCopy Anchor Link

Accepte true ou false ; toute autre chose est lue comme undefined.

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

stateBoolean: StateParse<boolean>

ExempleCopy Anchor Link

import { PlayerState, stateBoolean } from "@aicore-fivem/lib/client";

const dead = new PlayerState("dead", stateBoolean); // true tant que le joueur est à terre (ai-death)

stateStringCopy Anchor Link

Accepte une chaîne ; toute autre chose est lue comme undefined.

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

stateString: StateParse<string>

ExempleCopy Anchor Link

import { GlobalKey, stateString } from "@aicore-fivem/lib/client";

const inventoryScript = new GlobalKey("ai:inventory", stateString); // le nom de ressource de l’inventaire actif

import { PlayerState, type StateParse } from "@aicore-fivem/lib/client";

type Proximity = { index: number; distance: number; mode: string };
const proximity: StateParse<Proximity> = (v) => {
  if (typeof v !== "object" || v === null) return undefined;
  const { index, distance, mode } = v as Record<string, unknown>;
  return typeof index === "number" && typeof distance === "number" && typeof mode === "string"
    ? { index, distance, mode }
    : undefined;
};
const voiceRange = new PlayerState("proximity", proximity); // la portée de pma-voice, écrite par ai-voice

ClassesCopy Anchor Link

EntityStateCopy Anchor Link

Une clé des state bags d’entité (fuel, ai:owned...), pour chaque entité réseau. Les valeurs sont gardées par network id ; une lecture prend le handle de l’entité.

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

new EntityState<T>(key: string, parse: StateParse<T>)

ParamètresCopy Anchor Link

MéthodesCopy Anchor Link

ExempleCopy Anchor Link

import { EntityState, stateNumber, cache, every } from "@aicore-fivem/lib/client";

const fuel = new EntityState("fuel", stateNumber);

every(1000, () => {
  if (cache.vehicle === false) return;
  SendNUIMessage({ action: "fuel", value: fuel.get(cache.vehicle) ?? 100 });
});

PlayerStateCopy Anchor Link

Une clé des state bags de joueur (dead, cuffed, proximity de pma-voice...), par server id.

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

new PlayerState<T>(key: string, parse: StateParse<T>)

ParamètresCopy Anchor Link

MéthodesCopy Anchor Link

ExempleCopy Anchor Link

import { PlayerState, stateBoolean, onClientCallback } from "@aicore-fivem/lib/server";
import { fail } from "@aicore-fivem/lib/shared";

const dead = new PlayerState("dead", stateBoolean);
const cuffed = new PlayerState("cuffed", stateBoolean);

onClientCallback("my-shop:open", (source) => {
  if (dead.get(source) || cuffed.get(source)) return fail("CANNOT_NOW");
  return { ok: true };
});

GlobalKeyCopy Anchor Link

Une clé de GlobalState : une valeur dont chaque joueur a besoin (l’interrupteur PvP, l’inventaire actif). Lue une fois au démarrage, puis tenue à jour par son gestionnaire de changement.

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

new GlobalKey<T>(key: string, parse: StateParse<T>)

ParamètresCopy Anchor Link

MéthodesCopy Anchor Link

ExempleCopy Anchor Link

import { GlobalKey, stateBoolean } from "@aicore-fivem/lib/client";

const pvp = new GlobalKey("ai:pvp", stateBoolean);

pvp.onChange((_id, on) => SendNUIMessage({ action: "pvp", value: on === true }));

GlobalGroupCopy Anchor Link

Plusieurs clés de GlobalState qui partagent un préfixe (ai:duty:police, ai:duty:ambulance), lues par la partie qui suit le préfixe. Tous les groupes d’une ressource partagent un seul gestionnaire.

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

new GlobalGroup<T>(prefix: string, parse: StateParse<T>)

ParamètresCopy Anchor Link

MéthodesCopy Anchor Link

ExempleCopy Anchor Link

ai-core publie le nombre de joueurs en service par métier sous ai:duty:<job> :

import { GlobalGroup, stateNumber } from "@aicore-fivem/lib/client";

const onDuty = new GlobalGroup("ai:duty:", stateNumber);

function policeOnline(): number {
  return onDuty.get("police") ?? 0;
}