State bags

Um state bag é um valor que o FiveM copia do servidor para os clientes que precisam dele: o combustível de um veículo (Entity(vehicle).state.fuel), se um jogador está caído (Player(id).state.dead), uma flag do servidor inteiro (GlobalState["ai:pvp"]).

Ler um bag diretamente é lento: toda leitura cria proxies, chama várias natives e decodifica o valor de novo. Estas classes mantêm um handler de mudança por chave e uma cópia de todo valor em memória, então uma leitura é uma consulta em um mapa. Use-as para qualquer bag que você lê mais de uma 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";

As classes não estão em @aicore-fivem/lib/fivem: importe-as da entrada de cliente ou de servidor. Só o servidor escreve state bags (sv_stateBagStrictMode); um cliente pede ao servidor por um callback e o servidor define o valor. Os métodos set do servidor estão em Lib: servidor, State bags.

Lua: nenhum destes tem equivalente em Lua. Lua lê os bags diretamente (Entity(vehicle).state.fuel, Player(id).state.dead, GlobalState['ai:pvp']) e escuta com AddStateBagChangeHandler.

As chaves que o ai-core e os scripts ai-* usam estão listadas em Eventos e estado.

ParsersCopy Anchor Link

Toda classe recebe um parser: uma função que transforma o valor replicado bruto no seu tipo, ou undefined quando não é um valor válido. O tipo é StateParse<T> = (value: unknown) => T | undefined. Um bag limpo (null) sempre é lido como undefined; o parser nunca o vê.

stateNumberCopy Anchor Link

Aceita um número finito; qualquer outra coisa (texto, NaN, Infinity) é lida como undefined.

Lado: Cliente e servidor · Espera: não

stateNumber: StateParse<number>

ExemploCopy Anchor Link

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

const fuel = new EntityState("fuel", stateNumber); // 0-100, definido pelo script de combustível

stateBooleanCopy Anchor Link

Aceita true ou false; qualquer outra coisa é lida como undefined.

Lado: Cliente e servidor · Espera: não

stateBoolean: StateParse<boolean>

ExemploCopy Anchor Link

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

const dead = new PlayerState("dead", stateBoolean); // true enquanto caído (ai-death)

stateStringCopy Anchor Link

Aceita uma string; qualquer outra coisa é lida como undefined.

Lado: Cliente e servidor · Espera: não

stateString: StateParse<string>

ExemploCopy Anchor Link

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

const inventoryScript = new GlobalKey("ai:inventory", stateString); // o nome do recurso do inventário ativo

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); // o alcance do pma-voice, escrito pelo ai-voice

ClassesCopy Anchor Link

EntityStateCopy Anchor Link

Uma chave dos state bags de entidade (fuel, ai:owned...), para toda entidade em rede. Os valores são guardados por network id; uma leitura recebe o handle da entidade.

Lado: Cliente e servidor · Espera: não

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

ParâmetrosCopy Anchor Link

MétodosCopy Anchor Link

ExemploCopy 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

Uma chave dos state bags de jogador (dead, cuffed, o proximity do pma-voice...), por id de servidor.

Lado: Cliente e servidor · Espera: não

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

ParâmetrosCopy Anchor Link

MétodosCopy Anchor Link

ExemploCopy 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

Uma chave do GlobalState: um valor de que todo jogador precisa (a chave de PvP, o inventário ativo). Lida uma vez na inicialização, depois mantida atualizada pelo handler de mudança dela.

Lado: Cliente e servidor · Espera: não

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

ParâmetrosCopy Anchor Link

MétodosCopy Anchor Link

ExemploCopy 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

Muitas chaves do GlobalState que compartilham um prefixo (ai:duty:police, ai:duty:ambulance), lidas pela parte depois do prefixo. Todos os grupos de um recurso compartilham um handler.

Lado: Cliente e servidor · Espera: não

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

ParâmetrosCopy Anchor Link

MétodosCopy Anchor Link

ExemploCopy Anchor Link

O ai-core publica quantos jogadores estão em serviço por emprego em 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;
}