Bolsas de estado de FiveM: Entity(entity).state, GlobalState y manejadores

Quieres compartir un pequeño dato entre el servidor y cada cliente, por ejemplo que un vehículo está bloqueado, que un jugador está esposado, o el clima actual, y sigues escribiendo eventos que se disparan en cada cambio y se dessincronizan para los jugadores que se unen después. Las bolsas de estado son la respuesta integrada.

Este artículo cubre los tipos de bolsas de estado, cómo escribir y leer, cómo reaccionar a cambios, y cuándo un evento sigue siendo la mejor opción.

#¿Qué es una bolsa de estado?

Una bolsa de estado es un almacén tipo tabla de claves y valores adjunto a algo. El tiempo de ejecución lo sincroniza por ti, incluso para los jugadores que se conectan después de que se estableció el valor. FiveM te da tres tipos:

En todos ellos lees un valor como un campo normal:

local locked = Entity(vehicle).state.locked

#Escribiendo desde el servidor

En el servidor, establecer un valor lo replica a los clientes que pueden ver esa bolsa:

-- server
local veh = CreateVehicle(`adder`, 215.0, -810.0, 30.7, 90.0, true, true)
Entity(veh).state.locked = true

Player(source).state.cuffed = true

GlobalState.weather = 'RAIN'

Puedes usar el estilo de campo o la llamada explícita, que también te permite elegir si el valor se replica:

Entity(veh).state:set('locked', true, true)

:set(key, value, replicated) toma la clave, el valor y un booleano. Con true el valor se envía al otro lado, con false se queda en el lado que lo escribió.

Consejo: los valores pueden ser números, cadenas, booleanos y tablas. Una tabla se copia cuando la estableces, por lo que cambiar un campo en la tabla que lees no hace nada. Establece la tabla completa nuevamente para actualizarla.

#Escribiendo desde el cliente

Un cliente puede escribir en su propio jugador y en entidades que controla, pero una asignación simple permanece local:

-- client
LocalPlayer.state:set('inService', true, true)  -- replicated to the server
LocalPlayer.state.hasMask = true                -- local only

El servidor puede leer Player(source).state.inService después de eso. Trátalo como no confiable: un cliente modificado puede escribir cualquier valor que quiera. Usa estado escrito por cliente por conveniencia, como indicadores de interfaz de usuario, y mantén cualquier cosa con una ventaja adjunta (dinero, trabajo, permisos) en el servidor.

GlobalState es lo opuesto: el servidor lo escribe, cada cliente lo lee, y los clientes no pueden cambiarlo para otros.

-- client
local weather = GlobalState.weather

#Reaccionando a cambios

En lugar de sondear un valor en un bucle, registra un manejador que se ejecute cuando cambie una clave. Esta es la razón principal para usar bolsas de estado en el cliente:

-- AddStateBagChangeHandler(keyFilter, bagFilter, handler)
AddStateBagChangeHandler('locked', nil, function(bagName, key, value, reserved, replicated)
    local entity = GetEntityFromStateBagName(bagName)
    if entity == 0 then return end

    SetVehicleDoorsLocked(entity, value and 2 or 1)
end)

• keyFilter es la clave que te importa, o nil para cada clave.
• bagFilter limita la bolsa, por ejemplo una bolsa de jugador específica, o nil para todas.
• bagName se parece a entity:1234, player:5 o global. GetEntityFromStateBagName convierte una bolsa de entidad en un identificador, y GetPlayerFromStateBagName hace lo mismo para una bolsa de jugador.

En el cliente, la entidad puede no existir aún cuando se dispara el manejador, por ejemplo para un vehículo que aún se está transmitiendo. GetEntityFromStateBagName puede devolver 0 en ese caso, así que verifica si lo hace. Leer el estado nuevamente cuando la entidad se transmite es el hábito seguro.

La misma función existe en el servidor, donde es útil para reaccionar a un cliente que escribe un valor replicado.

#Bolsas de estado o eventos

Una buena regla: los eventos son para acciones, las bolsas de estado son para estado. Si un jugador que se une a mitad de camino necesitaría que se le dijera lo mismo nuevamente, es estado. Ver eventos del cliente y el servidor para el otro lado.

#Errores comunes

• Usarlo para datos grandes o que cambian rápidamente. Cada cambio se envía a través de la red. No escribas una posición en una bolsa de estado cada fotograma.
• Confiar en las escrituras del cliente. Valida cualquier cosa que un cliente establezca antes de actuar en ella en el servidor.
• Esperar que el manejador se ejecute antes de que exista la entidad. Verifica el identificador y lee el estado nuevamente cuando aparezca la entidad.
• Mutar una tabla en su lugar. Leer state.items, agregarle y no establecerlo nuevamente no cambia nada.
• Olvidar el reinicio. El estado en una entidad desaparece con la entidad, pero el estado en un jugador o GlobalState se queda hasta que lo limpies, así que establécelo en nil cuando hayas terminado.

Player(source).state.cuffed = nil

#Lista de verificación