Używanie persystencji danych w Verse

Korzystając z persystencji danych, można śledzić i zapisywać dane dla każdego gracza między sesjami gry. Pozwala to na korzystanie z różnych progresywnych trybów gry, w których gracze mogą opuścić grę, a następnie powrócić do niej, aby wznowić realizację celów lub zobaczyć ten sam stan gry, w którym się znajdowali w momencie jej opuszczenia.

Persystencja danych działa na zasadzie przechowywania w Verse danych dla poszczególnych graczy, takich jak jego profil lub statystyki. Dane te mogą być następnie aktualizowane tyle razy, ile razy zmieni się ich wartość. Ponieważ dane te są możliwe do utrwalenia, będą utrzymywać się podczas sesji gry i będą dostępne za każdym razem, gdy gracz będzie online w grze.

Przetrwanie, tycoon, RPG i gry roguelite to tylko niektóre przykłady trybów gry, które wykorzystują dane możliwe do utrwalenia. Tego typu tryby wymagają od graczy gromadzenia przedmiotów, które spełniają długoterminowe cele napędzające rozgrywkę.

Możesz używać danych możliwych do utrwalenia w skryptach Verse do przechowywania informacji, które są zapisywane dla każdego gracza i dla każdego modułu. Możesz zaimplementować dane możliwe do utrwalenia w trybach gry, w których chcesz zatrzymać graczy na dłużej, motywując ich do ciągłych postępów.

Aby samodzielnie przećwiczyć wdrażanie persystencji danych, zapoznaj się z samouczkiem dotyczącym utrwalonych statystyk graczy.

Co oznacza persystencja danych w Verse

W Verse zmienna zdefiniowana w module ma charakter globalny dla każdej uruchomionej Instancji gry, w której zmienna należy do zakresu. Z wyjątkiem zmiennych z zakresem modułu powiązanych z session, zmienna z zakresem modułu wymaga persystencji, przechowywania danych przez okres dłuższy niż bieżąca gra. Z tego powodu istnieją ograniczenia dotyczące tego, jakie typy mogą być używane z zakresem modułu.

Obecnie można używać następujących typów z zakresem modułu:

Jeśli gracz opuści grę lub nie jest w bieżącej sesji, nie można już przechowywać ani uzyskiwać dostępu do jego danych w tej sesji gry. Jeśli gracz powróci lub ponownie zagra w tę samą grę, można uzyskać dostęp do jego danych i je zaktualizować.

Tworzenie w Verse danych możliwych do utrwalenia

Możesz tworzyć własne dane możliwe do utrwalenia dla poszczególnych graczy, które mogą być stale aktualizowane, przechowywane i przywoływane za każdym razem, gdy gracze ponownie dołączą do gry. Podczas dobierania graczy gra sprawdzi, czy dla nowego gracza istnieją dane możliwe do utrwalenia. Jeśli dla określonego gracza dostępne są dane możliwe do utrwalenia, zostaną one załadowane i będą dostępne dla skryptów Verse.

Aby utworzyć dane możliwe do utrwalenia w kodzie Verse, zdefiniuj globalną zmienną weak_map, która jako klucza używa typu player, a jako wartości używa typu możliwego do utrwalenia. Patrz Typy możliwe do utrwalenia, aby zapoznać się z pełną listą typów, które możliwe są do utrwalenia.

W poniższym przykładzie globalna zmienna 'weak_map' MySavedPlayerData używa typu gracza jako klucza i liczby całkowitej jako wartości. Przechowywanie wartości całkowitej dla gracza w tej zmiennej oznacza, że dane będą przechowywane przez wszystkie sesje gry i mogą być dostępne i aktualizowane w dowolnym momencie, gdy gracz jest w grze.

var MySavedPlayerData:weak_map(player, int) = map{}

Po zdefiniowaniu danych możliwych do utrwalenia należy zainicjować dane dla każdego gracza. Można to zrobić, sprawdzając, czy nie ma już zachowanych danych dla tego gracza, a następnie dodając gracza i wartość początkową do weak_map.

# Runs when the device is started in a running game
OnBegin<override>()<suspends>:void =
    InitialSavedPlayerData:int = 0
    Players := GetPlayspace().GetPlayers()
    for (Player : Players):
        if:
            not MySavedPlayerData[Player]
            set MySavedPlayerData[Player] = InitialSavedPlayerData

Poprzedni przykład przechowywał tylko jedną wartość całkowitą, ale można użyć innych typów, takich jak klasy i tablice, aby przechowywać więcej danych dla każdego gracza w weak_map. Patrz Typy możliwe do utrwalenia, aby zapoznać się z pełną listą typów, których możesz użyć.

Poniższy przykład Verse pokazuje, jak można zdefiniować niestandardowy profil gracza w klasie, która może być przechowywana, aktualizowana i dostępna później dla gracza. Klasa player_profile_data przechowuje informacje o graczu, takie jak zdobyte PD, ranga i ukończone zadania.

player_profile_data := class<final><persistable>:
    Version:int = 0
    Class:player_class = player_class.Villager
    XP:int = 0
    Rank:int = 0
    CompletedQuestCount:int = 0
    QuestHistory:[]string = array{}

var PlayerProfileDataMap:weak_map(player, player_profile_data) = map{}

Teraz, gdy już wiesz, jak stworzyć własne dane możliwe do utrwalenia i zainicjować je dla poszczególnych graczy, koniecznie sprawdź Dobre praktyki, aby poznać zalecane sposoby pracy z danymi możliwymi do utrwalenia w Verse!

Modyfikowanie danych między opublikowanymi wersjami wyspy

Po opublikowaniu bieżącej wersji wyspy, jeśli wprowadzisz zmiany w danych możliwych do utrwalenia, wszelkie przechowywane dane z poprzedniej wersji wyspy będą musiały być obsługiwane przez późniejsze wersje wyspy.

Aby to zapewnić, w UEFN uruchamiane jest sprawdzanie kompatybilności wstecznej, a kompilacja kończy się niepowodzeniem, jeśli kod Verse nie jest już zgodny z aktualnie opublikowaną wersją. To sprawdzenie kompatybilności wstecznej jest uruchamiane za każdym razem, gdy:

• Kliknij Uruchom sesję na pasku narzędzi UEFN.

• Na pasku narzędzi UEFN kliknij opcję Wyślij zmiany lub Wyślij zmiany Verse.

• Publikowanie wyspy po raz pierwszy.

• Aktywowanie nowej publicznej wersji wyspy.

To sprawdzenie kompatybilności wstecznej jest zasadniczo sprawdzeniem typu wartości zmiennej weak_map z zakresem modułu. W przypadku prostych typów, takich jak liczby całkowite, typ nie może zostać zmieniony po opublikowaniu wyspy. Obejmuje to struktury, w przypadku których nie można zmienić definicji struktury po opublikowaniu wyspy.

Obecnie jedynym typem możliwym do utrwalenia, do którego można dodać więcej danych po opublikowaniu wyspy, jest typ class, o ile nowe pola mają wartości domyślne. Oznacza to, że wczytanie zapisanych danych z poprzedniej wersji będzie zawierać nowe pola i ich wartości domyślne. Sprawdź dobre praktyki dotyczące używania klas jako danych możliwych do utrwalenia (persystentnych), aby uzyskać więcej szczegółów.

Resetowanie danych możliwych do utrwalenia dla wyspy

Jeśli zajdzie potrzeba wymuszenia resetu utrwalonych danych dla wyspy, można to zrobić w Verse, przypisując domyślną wartość danych możliwych do utrwalenia do weak_map dla gracza, gdy dołącza do wyspy.

Aby dowiedzieć się, czy dane gracza zostały już zresetowane, można dołączyć wartość Version dla swojej klasy i zaktualizować ją o nowe zmiany jako część danych możliwych do utrwalenia. To jedna z dobrych praktyk wymienionych poniżej, więc koniecznie sprawdź pozostałe!

Typy możliwe do utrwalenia w Verse

Poniżej przedstawiono typy możliwe do utrwalenia, których można użyć w zmiennej weak_map z zakresem modułu:

Testowanie z persystencją danych

Jeśli chcesz przetestować zachowanie utrwalonych danych przed opublikowaniem najnowszej wersji swojej wyspy, możesz ustawić następujące zachowanie na urządzeniu Ustawień wyspy zarówno dla ustawienia Zachowanie persystencji: Sesja testowa i Zachowanie persystencji: Sesja edycji:

Ustawienia zachowania utrwalonych danych są stosowane podczas testowania. Istnieją dwa różne scenariusze, w których można testować utrwalone dane:

• Edycja sesji: Ustawienia zachowania utrwalonych danych są stosowane podczas uruchamiania sesji z UEFN. Oznacza to, że dane możliwe do utrwalenia mogą być przechowywane w wielu grach w ramach pojedynczej sesji. Jeśli opuścisz sesję i ponownie uruchomisz nową sesję, utrwalone dane zostaną zresetowane, a ustawienia zachowania utrwalonych danych zostaną zastosowane ponownie.

• Sesja testu gry: Ustawienia zachowania utrwalonych danych są stosowane podczas konfigurowania testu gry w Portalu Twórcy, do którego tester dołącza za pomocą kodu testu gry lub prywatnego kodu linku. Ustawienia zachowania utrwalonych danych są stosowane tylko przy pierwszym dołączeniu gracza. Gdy gracz opuści test gry i ponownie do niego dołączy, jego dane będą utrzymywać się w różnych sesjach, a ustawienia zachowania utrwalonych danych nie zostaną ponownie zastosowane. Aby zresetować dane możliwe do utrwalenia, należy utworzyć nowy kod linku testowego.

W przypadku aktualizacji wyspy, które wpływają na sposób zarządzania danymi możliwymi do utrwalenia oraz ich aktualizacji, zalecamy przetestowanie obu scenariuszy, zarówno uruchamiając sesję z UEFN, jak testując grę po wykorzystaniu kodu linku. Pamiętaj, aby przetestować zmiany wprowadzone w danych możliwych do utrwalenia zarówno z aktualnymi danymi, jak i symulowanymi danymi nowych użytkowników. Pomoże to upewnić się, że aktualizacje działają zarówno dla aktualnych, jak i nowych graczy. Skutki publikowania nowych wersji wyspy Po opublikowaniu wyspy dla graczy tworzony jest rekord możliwy do utrwalenia, gdy ich dane są przechowywane w weak_map. Dane te będą następnie przechowywane i ładowane podczas kolejnych odwiedzin wyspy.

Jeśli zostaną opublikowane nowe wersje wyspy, dane możliwe do utrwalenia zostaną automatycznie scalone z nową wersją. Więcej informacji można znaleźć w sekcji Modyfikowanie danych między opublikowanymi wersjami wyspy.

Skutki wycofania opublikowanej wyspy

W przypadku przywrócenia wyspy do poprzedniej wersji za pośrednictwem Portalu Twórcy, dane możliwe do utrwalenia wszystkich użytkowników zostaną zresetowane.

Spowoduje to utratę ostatnich aktualizacji danych gracza, a nawet może spowodować całkowite zresetowanie tych danych. Dzieje się tak nawet wtedy, gdy wycofanie wewnętrznie nie obejmuje zmian w logice, które miałyby wpływ na dane możliwe do utrwalenia.

Ze względu na wpływ na dane możliwe do utrwalenia zalecamy korzystanie z funkcji wycofania tylko w ostateczności.

Ograniczenia

Poniżej przedstawiono ograniczenia dotyczące pracy z danymi możliwymi do utrwalenia w Verse.

Maksymalny rozmiar obiektu możliwego do utrwalenia

Istnieje limit ilości danych na gracza, które mogą być przechowywane w weak_map.

Rekord weak_map jest całkowitą ilością danych powiązanych z pojedynczym elementem weak_map. Pojedynczy rekord weak_map ma maksymalny rozmiar danych 256 kilobajtów (KB) na gracza.

Gdy zapisywana jest wartość 'weak_map', obliczana jest całkowita ilość pamięci wymagana do zapisania danych.

Poniżej znajduje się kilka przykładów danych, które przekraczają limit 256 KB:

• Około 24 000 wartości zmiennopozycyjnych lub liczb całkowitych.

• Około 200 000 znaków tekstu. Odpowiada to około 60 stronom tekstu w przeciętnej powieści.

Próba zapisania danych o rozmiarze większym niż 256 KB dla rekordu gracza zakończy się niepowodzeniem i wyświetlony zostanie błąd czasu wykonywania programu Verse.

Możesz uniknąć błędów zapisu, używając funkcji pomocniczej Verse FitsInPlayerMap. Funkcja FitsInPlayerMap pobiera kopię rekordu, który ma zostać zapisany, i sprawdza jego rozmiar. Jeśli rekord może zostać zapisany, wywołanie funkcji powiedzie się; w przeciwnym razie, jeśli rekord jest zbyt duży, nie powiedzie się.

Funkcja FitsInPlayerMap jest szczególnie przydatna, gdy pracujesz z dynamiczną tablicą lub mapą danych i dodajesz do nich nowe elementy. Aktualizacja wartości int, float, lub logic, które wcześniej znajdowały się w rekordzie możliwym do utrwalenia nie zmieni rozmiaru rekordu możliwego do utrwalenia.

Maksymalna liczba utrwalonych słabych map graczy na wyspę

Każda wyspa może mieć do czterech persystentnych zmiennych, czyli cztery zmienne weak_map z player jako typem klucza. Jest to wymuszone przez kompilator Verse.

Wymagana słaba mapa z typem klasy

Przynajmniej jedna wartość weak_map utrwalonej zmiennej musi być klasą, jeśli limit maksymalnej liczby zmiennych trwałych został osiągnięty. Ma to umożliwić dodanie do zmiennych większej liczby danych na późniejszym etapie, jednocześnie spełniając kompatybilność wsteczną przy kolejnych publikacjach wyspy.