Poradnik po FiveM State Bags: synchronizuj dane bez eventów

Czym są State Bags?

State bagi to wbudowana funkcja FiveM do synchronizacji danych między serwerem a klientami bez pisania własnych handlerów eventów. Zapewniają magazyn klucz-wartość dołączony do bytów, graczy lub stanu globalnego, który automatycznie replikuje zmiany w sieci. Gdy serwer ustawia wartość w state bagu gracza, wszyscy klienci potrzebujący tej informacji otrzymują ją automatycznie. Zastępuje to powszechny wzorzec ręcznego wywoływania eventów w celu synchronizacji danych i znacząco redukuje boilerplate w kodzie.

State bags gracza

Każdy połączony gracz ma state bag dostępny poprzez Player(source).state na serwerze i LocalPlayer.state po stronie klienta. Możesz ustawić dowolną parę klucz:wartość w stanie gracza, a zsynchronizuje się ona automatycznie z odpowiednimi klientami. Jest to idealne rozwiązanie dla danych takich jak status na służbie, stanowisko, przynależność do gangu czy niestandardowe wskaźniki statusu, które muszą odczytywać inni gracze lub zasoby. Ustawiaj wartości na serwerze ze względów bezpieczeństwa i odczytuj je na kliencie, aby renderować elementy UI lub dostosowywać zachowanie na podstawie stanu gracza.

Entity State Bags

Poza graczami każdy sieciowy entity w FiveM może mieć przypisane dane state bag. Uzyskaj dostęp do stanu entity za pomocą Entity(entityHandle).state zarówno po stronie klienta, jak i serwera. Jest to przydatne do przechowywania metadanych pojazdów, takich jak poziom paliwa, stan zamka czy własność, bez konieczności prowadzenia osobnych tabel śledzenia. Gdy gracz zbliża się do pojazdu, klient może odczytać jego state bag, aby wyświetlić poziom paliwa na HUD bez żądania danych z serwera. State bags encji istnieją tak długo, jak sama encja, i są automatycznie czyszczone po jej usunięciu.

Stan globalny

GlobalState to state bag współdzielony przez cały serwer i wszystkich klientów. Używaj go do ustawień ogólnoserwerowych, takich jak pogoda, pora dnia, flagi wydarzeń czy modyfikatory ekonomii. Kiedy serwer ustawia GlobalState.weather = 'rain', każdy połączony klient otrzymuje tę aktualizację i może odpowiednio zareagować. Jest to bardziej wydajne niż rozsyłanie zdarzeń do wszystkich graczy, ponieważ state bags automatycznie obsługują nowe połączenia graczy. Gracz dołączający w trakcie sesji natychmiast otrzymuje bieżący stan globalny bez konieczności osobnego zdarzenia synchronizacji.

Handlery state bagów

Możesz reagować na zmiany state bagów, rejestrując handlery za pomocą AddStateBagChangeHandler. Ta funkcja przyjmuje filtr klucza, filtr bag oraz callback wywoływany przy każdej zmianie określonego stanu. Handler otrzymuje nazwę bag, klucz, wartość i inne metadane. Używaj handlerów do wyzwalania efektów wizualnych, gdy gracz wchodzi na służbę, aktualizowania UI przy zmianie danych w ekwipunku lub logowania modyfikacji stanu na potrzeby debugowania. Handlery działają zarówno po stronie klienta, jak i serwera, dając elastyczność w przetwarzaniu aktualizacji stanu.

Dobre praktyki i ograniczenia

State bagi nie są zaprojektowane do aktualizacji o wysokiej częstotliwości. Ustawianie wartości state baga wyzwala synchronizację sieciową, dlatego unikaj aktualizowania ich w każdej klatce. Używaj ich do danych zmieniających się sporadycznie, takich jak flagi statusu, wartości konfiguracyjne i metadane, a nie do stale zmieniających się wartości, takich jak pozycja czy prędkość. Utrzymuj przechowywane wartości małe i serializowalne, ponieważ przesyłane są przez sieć. Gdy potrzebujesz złożonych obiektów, spłaszcz je do prostych par klucz-wartość lub użyj ciągów JSON. Zawsze ustawiaj stan z poziomu serwera, gdy dane muszą być autorytatywne, aby zapobiec manipulacjom po stronie klienta.