O que são bolsas estaduais?
State bags são um recurso integrado do FiveM para sincronizar dados entre o servidor e os clientes sem escrever manipuladores de eventos personalizados. Eles fornecem um armazenamento de valores-chave anexado a entidades, participantes ou ao estado global que replica automaticamente as alterações em toda a rede. Quando o servidor define um valor em um pacote de estado do jogador, todos os clientes que precisam dessa informação a recebem automaticamente. Isso substitui o padrão comum de acionamento manual de eventos para sincronizar dados e reduz significativamente o código padrão.
Sacos de estado do jogador
Cada jogador conectado possui um state bag acessível através de Player(source).state no servidor e LocalPlayer.state no cliente. Você pode definir qualquer par de valores-chave no estado do player e ele será sincronizado automaticamente com os clientes relevantes. Isso é perfeito para dados como status de dever, cargo, afiliação a gangues ou indicadores de status personalizados que outros jogadores ou recursos precisam ler. Defina valores no servidor para segurança e leia-os no cliente para renderizar elementos da IU ou ajustar o comportamento com base no estado do jogador.
Sacos de estado de entidade
Além dos jogadores, todas as entidades em rede no FiveM podem ter dados de bolsa de estado anexados a ela. Acesse o estado da entidade com Entity(entityHandle).state no cliente e no servidor. Isso é útil para armazenar metadados sobre veículos, como nível de combustível, status de bloqueio ou propriedade, sem manter tabelas de rastreamento separadas. Quando um jogador se aproxima de um veículo, o cliente pode ler sua bolsa de estado para exibir o nível de combustível em um HUD sem solicitar dados do servidor. Os sacos de estado da entidade persistem enquanto a entidade existir e são limpos automaticamente quando a entidade é removida.
Estado Global
GlobalState é um pacote de estados compartilhado por todo o servidor e todos os clientes. Use-o para configurações de todo o servidor, como clima, hora do dia, sinalizadores de eventos ou modificadores de economia. Quando o servidor define GlobalState.weather = 'rain', cada cliente conectado recebe esta atualização e pode reagir de acordo. Isso é mais eficiente do que transmitir eventos para todos os jogadores porque os state bags tratam automaticamente das conexões de novos jogadores. Um jogador que entra no meio da sessão recebe imediatamente o estado global atual sem precisar de um evento de sincronização separado.
Manipuladores de Bagagens Estaduais
Você pode reagir às mudanças de estado do bag registrando manipuladores com AddStateBagChangeHandler. Esta função usa um filtro de chave, um filtro de saco e um retorno de chamada que é acionado sempre que o estado especificado muda. O manipulador recebe o nome do pacote, a chave, o valor e outros metadados. Use manipuladores para acionar efeitos visuais quando um jogador entra em serviço, atualizar a interface do usuário quando os dados do inventário mudam ou registrar modificações de estado para depuração. Os manipuladores funcionam tanto no cliente quanto no servidor, proporcionando flexibilidade no processamento de atualizações de estado.
Práticas recomendadas e limitações
Os pacotes estaduais não são projetados para atualizações de alta frequência. Definir valores de estado aciona a sincronização da rede, portanto, evite atualizá-los a cada quadro. Use-os para dados que mudam ocasionalmente, como sinalizadores de status, valores de configuração e metadados, em vez de valores que mudam constantemente, como posição ou velocidade. Mantenha os valores armazenados pequenos e serializáveis, pois eles trafegam pela rede. Quando você precisar de objetos complexos, nivele-os em pares simples de chave-valor ou use strings JSON. Sempre defina o estado do servidor quando os dados precisarem ser autoritativos para evitar a manipulação do lado do cliente.