Руководство по FiveM State Bags: Синхронизация данных без событий

What Are State Bags?

State bags , встроенная функция FiveM для синхронизации данных между сервером и клиентами без написания обработчиков событий. Они предоставляют хранилище ключ-значение, прикреплённое к сущностям, игрокам или глобальному состоянию, которое автоматически реплицирует изменения по сети. Когда сервер устанавливает значение в player state bag, все клиенты, которым нужна эта информация, получают её автоматически. Это заменяет распространённый паттерн ручного вызова событий для синхронизации данных и значительно сокращает шаблонный код.

Player State Bags

Каждому подключённому игроку доступен state bag через Player(source).state на сервере и LocalPlayer.state на клиенте. Вы можете установить любую пару ключ-значение в состоянии игрока, и она автоматически синхронизируется с соответствующими клиентами. Это идеально подходит для данных, таких как статус дежурства, должность, принадлежность к банде или пользовательские индикаторы статуса, которые должны читать другие игроки или ресурсы. Устанавливайте значения на сервере для безопасности и читайте их на клиенте для отображения UI или изменения поведения в зависимости от состояния игрока.

Entity State Bags

Помимо игроков, к любому сетевому объекту в FiveM можно прикрепить данные state bag. Получайте доступ к состоянию объекта с помощью Entity(entityHandle).state на клиенте и сервере. Это полезно для хранения метаданных о транспортных средствах, таких как уровень топлива, состояние замков или владение, без ведения отдельных таблиц отслеживания. Когда игрок подходит к транспортному средству, клиент может прочитать его state bag, чтобы отобразить уровень топлива на HUD без запроса данных у сервера. State bags сущностей сохраняются, пока существует сущность, и автоматически очищаются при её удалении.

Глобальное состояние

GlobalState является state bag, который разделяется по всему серверу и всем клиентам. Используйте его для настроек сервера, таких как погода, время суток, флаги событий или модификаторы экономики. Когда сервер устанавливает GlobalState.weather = 'rain' , каждый подключенный клиент получает это обновление и может соответствующим образом реагировать. Это эффективнее, чем рассылка событий всем игрокам, потому что state bags автоматически обрабатывают подключения новых игроков. Игрок, присоединившийся в середине сессии, сразу получает текущее глобальное состояние без необходимости отдельного события синхронизации.

Обработчики State Bag

Вы можете реагировать на изменения state bag, регистрируя обработчики через AddStateBagChangeHandler. Эта функция принимает фильтр ключа, фильтр сумки и callback, который срабатывает при изменении указанного состояния. Обработчик получает имя сумки, ключ, значение и другие метаданные. Используйте обработчики для запуска визуальных эффектов при выходе игрока на дежурство, обновления UI при изменении данных инвентаря или логирования изменений состояния для отладки. Обработчики работают как на клиенте, так и на сервере, давая гибкость в обработке обновлений состояния.

Лучшие практики и ограничения

State bags не предназначены для обновлений с высокой частотой. Установка значений state bag вызывает сетевую синхронизацию, поэтому избегайте обновления их каждый кадр. Используйте их для данных, которые меняются время от времени, таких как флаги статуса, конфигурационные значения и метаданные, а не для постоянно меняющихся значений, например позиции или скорости. Храните значения маленькими и сериализуемыми, так как они передаются по сети. Когда нужны сложные объекты, преобразуйте их в простые пары ключ-значение или используйте JSON-строки. Всегда устанавливайте состояние с сервера, когда данные должны быть авторитетными, чтобы предотвратить манипуляции на стороне клиента.