State bags

Un state bag es un valor que FiveM copia del servidor a los clientes que lo necesitan: el combustible de un vehículo (Entity(vehicle).state.fuel), si un jugador está derribado (Player(id).state.dead), un indicador de todo el servidor (GlobalState["ai:pvp"]).

Leer un state bag directamente es lento: cada lectura construye proxies, llama a varios natives y decodifica el valor otra vez. Estas clases mantienen un handler de cambios por clave y una copia de cada valor en memoria, así que una lectura es una consulta en un mapa. Úsalas para cualquier state bag que leas más de una vez.

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";

Las clases no están en @aicore-fivem/lib/fivem: impórtalas desde la entrada de cliente o de servidor. Solo el servidor escribe state bags (sv_stateBagStrictMode); un cliente se lo pide al servidor mediante un callback y el servidor fija el valor. Los métodos set del servidor están en Lib: servidor, State bags.

Lua: ninguna de estas tiene equivalente en Lua. Lua lee los state bags por sí mismo (Entity(vehicle).state.fuel, Player(id).state.dead, GlobalState['ai:pvp']) y escucha con AddStateBagChangeHandler.

Las claves que usan ai-core y los scripts ai-* se listan en Eventos y estado.

ParsersCopy Anchor Link

Cada clase recibe un parser: una función que convierte el valor replicado en bruto en tu tipo, o undefined cuando no es un valor válido. El tipo es StateParse<T> = (value: unknown) => T | undefined. Un state bag vaciado (null) siempre se lee como undefined; el parser nunca lo ve.

stateNumberCopy Anchor Link

Acepta un número finito; cualquier otra cosa (texto, NaN, Infinity) se lee como undefined.

Lado: Cliente y servidor · Espera: no

stateNumber: StateParse<number>

EjemploCopy Anchor Link

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

const fuel = new EntityState("fuel", stateNumber); // 0-100, lo fija el script de combustible

stateBooleanCopy Anchor Link

Acepta true o false; cualquier otra cosa se lee como undefined.

Lado: Cliente y servidor · Espera: no

stateBoolean: StateParse<boolean>

EjemploCopy Anchor Link

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

const dead = new PlayerState("dead", stateBoolean); // true mientras está derribado (ai-death)

stateStringCopy Anchor Link

Acepta un string; cualquier otra cosa se lee como undefined.

Lado: Cliente y servidor · Espera: no

stateString: StateParse<string>

EjemploCopy Anchor Link

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

const inventoryScript = new GlobalKey("ai:inventory", stateString); // el nombre del recurso del inventario activo

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); // el alcance de pma-voice, escrito por ai-voice

ClasesCopy Anchor Link

EntityStateCopy Anchor Link

Una clave de los state bags de entidad (fuel, ai:owned...), para cada entidad en red. Los valores se guardan por network id; una lectura recibe el handle de la entidad.

Lado: Cliente y servidor · Espera: no

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

ParámetrosCopy Anchor Link

MétodosCopy Anchor Link

EjemploCopy 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

Una clave de los state bags de jugador (dead, cuffed, el proximity de pma-voice...), por id de servidor.

Lado: Cliente y servidor · Espera: no

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

ParámetrosCopy Anchor Link

MétodosCopy Anchor Link

EjemploCopy 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

Una clave de GlobalState: un valor que necesita cada jugador (el interruptor de PvP, el inventario activo). Se lee una vez al arrancar y después se mantiene al día con su handler de cambios.

Lado: Cliente y servidor · Espera: no

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

ParámetrosCopy Anchor Link

MétodosCopy Anchor Link

EjemploCopy 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

Muchas claves de GlobalState que comparten un prefijo (ai:duty:police, ai:duty:ambulance), leídas por la parte que va después del prefijo. Todos los grupos de un recurso comparten un handler.

Lado: Cliente y servidor · Espera: no

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

ParámetrosCopy Anchor Link

MétodosCopy Anchor Link

EjemploCopy Anchor Link

ai-core publica cuántos jugadores están de servicio por trabajo bajo 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;
}