State bags

State bag это значение, которое FiveM копирует с сервера на клиенты, которым оно нужно: топливо транспорта (Entity(vehicle).state.fuel), лежит ли игрок без сознания (Player(id).state.dead), флаг на весь сервер (GlobalState["ai:pvp"]).

Прямое чтение bag медленное: каждое чтение создаёт прокси, вызывает несколько нативов и заново декодирует значение. Эти классы держат один обработчик изменений на ключ и копию каждого значения в памяти, поэтому чтение сводится к поиску в Map. Используйте их для любого bag, который читаете больше одного раза.

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

Этих классов нет в @aicore-fivem/lib/fivem: импортируйте их из точки входа клиента или сервера. State bags пишет только сервер (sv_stateBagStrictMode); клиент просит сервер через колбэк, и сервер задаёт значение. Серверные методы set описаны на странице Lib: сервер, State bags.

Lua: ни у одного из них нет Lua-аналога. Lua сам читает bags (Entity(vehicle).state.fuel, Player(id).state.dead, GlobalState['ai:pvp']) и слушает их через AddStateBagChangeHandler.

Ключи, которые используют ai-core и скрипты ai-*, перечислены на странице События и состояние.

ПарсерыCopy Anchor Link

Каждый класс принимает парсер: функцию, которая превращает сырое реплицированное значение в ваш тип или в undefined, если значение неверное. Тип: StateParse<T> = (value: unknown) => T | undefined. Очищенный bag (null) всегда читается как undefined; парсер его не видит.

stateNumberCopy Anchor Link

Принимает конечное число; всё остальное (текст, NaN, Infinity) читается как undefined.

Сторона: Клиент и сервер · Ждёт: нет

stateNumber: StateParse<number>

ПримерCopy Anchor Link

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

const fuel = new EntityState("fuel", stateNumber); // 0-100, задаёт скрипт топлива

stateBooleanCopy Anchor Link

Принимает true или false; всё остальное читается как undefined.

Сторона: Клиент и сервер · Ждёт: нет

stateBoolean: StateParse<boolean>

ПримерCopy Anchor Link

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

const dead = new PlayerState("dead", stateBoolean); // true, пока игрок без сознания (ai-death)

stateStringCopy Anchor Link

Принимает строку; всё остальное читается как undefined.

Сторона: Клиент и сервер · Ждёт: нет

stateString: StateParse<string>

ПримерCopy Anchor Link

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

const inventoryScript = new GlobalKey("ai:inventory", stateString); // имя ресурса активного инвентаря

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); // дальность pma-voice, которую записывает ai-voice

КлассыCopy Anchor Link

EntityStateCopy Anchor Link

Один ключ state bags сущностей (fuel, ai:owned...) для каждой сетевой сущности. Значения хранятся по сетевому id; чтение принимает хэндл сущности.

Сторона: Клиент и сервер · Ждёт: нет

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

ПараметрыCopy Anchor Link

МетодыCopy Anchor Link

ПримерCopy 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

Один ключ state bags игроков (dead, cuffed, proximity из pma-voice...) по серверному id.

Сторона: Клиент и сервер · Ждёт: нет

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

ПараметрыCopy Anchor Link

МетодыCopy Anchor Link

ПримерCopy 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

Один ключ GlobalState: значение, которое нужно каждому игроку (переключатель PvP, активный инвентарь). Читается один раз при старте, затем поддерживается в актуальном виде обработчиком изменений.

Сторона: Клиент и сервер · Ждёт: нет

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

ПараметрыCopy Anchor Link

МетодыCopy Anchor Link

ПримерCopy 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

Много ключей GlobalState с общим префиксом (ai:duty:police, ai:duty:ambulance), которые читаются по части после префикса. Все группы ресурса делят один обработчик.

Сторона: Клиент и сервер · Ждёт: нет

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

ПараметрыCopy Anchor Link

МетодыCopy Anchor Link

ПримерCopy Anchor Link

ai-core публикует, сколько игроков на дежурстве в каждой работе, под ключом 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;
}