¿Qué son las state bags?
Las state bags son una funcionalidad integrada de FiveM para sincronizar datos entre el servidor y los clientes sin escribir handlers de eventos personalizados. Ofrecen un almacén clave-valor asociado a entidades, jugadores o al estado global que replica automáticamente los cambios por la red. Cuando el servidor fija un valor en la state bag de un jugador, todos los clientes que necesitan esa información la reciben automáticamente. Esto sustituye el patrón común de disparar eventos manualmente para sincronizar datos y reduce bastante el código boilerplate.
State bags de jugador
Cada jugador conectado tiene una state bag accesible desde Player(source).state en el servidor y LocalPlayer.state en el cliente. Puedes fijar cualquier pareja clave-valor en el estado del jugador y se sincronizará a los clientes relevantes automáticamente. Es perfecto para datos como estado de servicio, puesto del trabajo, afiliación a banda o indicadores personalizados que otros jugadores o recursos necesiten leer. Fija los valores en el servidor por seguridad y léelos en el cliente para renderizar UI o ajustar comportamiento según el estado del jugador.
State bags de entidades
Más allá de los jugadores, cada entidad networked en FiveM puede tener datos de state bag asociados. Accede al estado de una entidad con Entity(entityHandle).state tanto en cliente como en servidor. Es útil para guardar metadatos en vehículos como nivel de combustible, estado de cerradura o propiedad sin mantener tablas de seguimiento separadas. Cuando un jugador se acerca a un vehículo, el cliente puede leer su state bag para mostrar el combustible en un HUD sin pedir datos al servidor. Las state bags de entidad persisten mientras exista la entidad y se limpian automáticamente al retirarla.
Estado global
GlobalState es una state bag compartida por todo el servidor y todos los clientes. Úsala para ajustes de servidor como clima, hora del día, flags de evento o modificadores económicos. Cuando el servidor fija GlobalState.weather = 'rain', todos los clientes conectados reciben la actualización y pueden reaccionar. Es más eficiente que broadcastear eventos a todos los jugadores porque las state bags gestionan las nuevas conexiones automáticamente. Un jugador que entra a mitad de partida recibe al instante el estado global actual sin necesidad de un evento de sincronización aparte.
Handlers de state bag
Puedes reaccionar a los cambios de state bag registrando handlers con AddStateBagChangeHandler. Esta función acepta un filtro por clave, un filtro por bag y un callback que se dispara cuando cambia el estado especificado. El handler recibe el nombre de la bag, la clave, el valor y otros metadatos. Usa handlers para disparar efectos visuales cuando un jugador entra de servicio, actualizar la UI cuando cambian los datos de inventario o registrar modificaciones de estado para depurar. Los handlers funcionan tanto en cliente como en servidor, dándote flexibilidad sobre dónde procesar las actualizaciones.
Buenas prácticas y limitaciones
Las state bags no están pensadas para actualizaciones de alta frecuencia. Fijar valores dispara sincronización por red, así que evita actualizarlas en cada frame. Úsalas para datos que cambian de forma ocasional como flags de estado, valores de configuración y metadatos, no para valores que cambian constantemente como posición o velocidad. Mantén los valores almacenados pequeños y serializables, porque viajan por la red. Cuando necesites objetos complejos, aplánalos a pares clave-valor sencillos o usa cadenas JSON. Fija siempre el estado desde el servidor cuando los datos deban ser autoritativos para evitar manipulación desde el cliente.