PersistentComponent struct in Thread

Marks an entity as part of the saved world. Its existence, its transform and its components are written to the save file and restored on load — under its own id, so the thing that comes back is the same thing that left.

Properties

Categorystd::stringFree-form and optional. Lets a game group saved objects ("building", "loot") without inventing a parallel tagging scheme.

The save is a difference, not a snapshot

This is the design decision everything else follows from. The save file does not contain the world; it contains what the world does not match about the authored scene:

  • entities the authored map has that the save says are gone, and
  • entities the save carries that the map does not, or carries differently.

The alternative — writing the whole level into the save — freezes a player's world at the version they first loaded. A patch that fixes a hole in the terrain, moves a quest giver or adds a building would never reach anyone who had already started, because their save would keep overwriting it. A difference lets the authored map keep improving underneath a player who is fifty hours in.

The consequence to design around: an entity's id is its identity across sessions. Restoring works by id, so anything the save must be able to find again has to keep the same one. Prefab instantiation mints fresh ids on purpose, which is exactly right for a new wall and exactly wrong for a hand-placed landmark.

Usage

// Anything the player creates at runtime should be saved.
Entity wall = serializer.InstantiatePrefab("assets/blueprints/wall.prefab");
wall.AddOrReplaceComponent<PersistentComponent>().Category = "building";

BuilderComponent does exactly this for everything it places, which is what makes a built wall outlive quitting.

Mark children too. Restoring an entity destroys and rebuilds its whole subtree, so a persistent parent with unmarked children comes back without them.

Notes

The clean baseline is captured at the moment Play begins, so the difference is measured against the authored map rather than against whatever the world had already become. That ordering is what makes an entity created during play read as an addition rather than as part of the map.

A missing save file is a new game, not an error, and the load reports it as such — a first run and a corrupt file should not look the same to a player or to a log.

See also WorldStreamingComponent for worlds too large to hold at once; persistence and streaming are independent, and a streamed cell's entities can be persistent like any others.

PersistentComponent struct w Thread

Oznacza encję jako część zapisanego świata. Jej istnienie, transformacja i komponenty trafiają do pliku zapisu i wracają przy wczytaniu — pod jej własnym id, więc to, co wraca, jest tym samym, co odeszło.

Właściwości

Categorystd::stringDowolna i opcjonalna. Pozwala grze grupować zapisane obiekty ("building", "loot") bez wymyślania równoległego systemu tagów.

Zapis to różnica, nie migawka

To decyzja projektowa, z której wynika cała reszta. Plik zapisu nie zawiera świata; zawiera to, czym świat różni się od sceny przygotowanej w edytorze:

  • encje, które mapa ma, a według zapisu zniknęły, oraz
  • encje, które zapis ma, a mapa nie — albo ma je inaczej.

Alternatywa — zapisywanie całego poziomu — zamraża świat gracza w wersji, którą pierwszy raz wczytał. Patch, który łata dziurę w terenie, przestawia zleceniodawcę albo dodaje budynek, nigdy nie dotarłby do nikogo, kto już zaczął, bo jego zapis ciągle by to nadpisywał. Różnica pozwala mapie dalej się poprawiać pod graczem, który ma za sobą pięćdziesiąt godzin.

Konsekwencja, wokół której trzeba projektować: id encji to jej tożsamość między sesjami. Przywracanie działa po id, więc wszystko, co zapis ma odnaleźć, musi zachować to samo id. Tworzenie prefabów celowo nadaje nowe id — co jest dokładnie tym, czego chcesz dla nowej ściany, i dokładnie tym, czego nie chcesz dla ręcznie postawionego punktu orientacyjnego.

Użycie

// Wszystko, co gracz tworzy w trakcie gry, powinno być zapisane.
Entity wall = serializer.InstantiatePrefab("assets/blueprints/wall.prefab");
wall.AddOrReplaceComponent<PersistentComponent>().Category = "building";

BuilderComponent robi dokładnie to dla wszystkiego, co stawia — dlatego postawiona ściana przetrwa wyjście z gry.

Oznaczaj też dzieci. Przywrócenie encji niszczy i odbudowuje całe jej poddrzewo, więc trwały rodzic z nieoznaczonymi dziećmi wraca bez nich.

Uwagi

Czysty punkt odniesienia jest zapamiętywany w chwili startu Play, więc różnica liczona jest względem mapy z edytora, a nie względem tego, czym świat już się stał. Ta kolejność sprawia, że encja utworzona w trakcie gry czyta się jako dodatek, a nie jako część mapy.

Brak pliku zapisu to nowa gra, a nie błąd, i wczytywanie tak to zgłasza — pierwsze uruchomienie i uszkodzony plik nie powinny wyglądać tak samo ani dla gracza, ani w logu.

Zobacz też WorldStreamingComponent dla światów zbyt dużych, by trzymać je w całości; trwałość i streaming są niezależne, a encje strumieniowanej komórki mogą być trwałe jak każde inne.