Save and load
Pulse Build does not depend on a save system. The building world and the builders save themselves as bytes (IPulseByteSaveable of PulseFoundation); PulseSave keeps them without a bridge (PulseSave), another save system calls the functions below.
The building world
On the authority:
| Function | What it does |
|---|---|
ExportSaveData(OutData) | All pieces (FPulseBuildSaveData: id, the definition id of the piece, transform, owner, tier, saved states, actor data) and the extras of other systems |
ImportSaveData(Data, OutReport) | Replaces all pieces with the saved ones; ids stay the same, definitions are found by their ids, unknown ones are skipped and listed in the FPulseImportReport (code MissingPiece, with the id) |
SaveToBytes(OutBytes), LoadFromBytes(Bytes, OutReport) | The same as versioned bytes (Pulse::Serialization); empty bytes leave the world as it is, data of another version than the current one (5) is refused with an error |
What is saved:
- pieces with their ids, the definition ids of what they are (
PulseBuildPiece:<asset name>, see Pieces), owners, tiers; - construction sites with their progress and paid stages, health of damaged pieces, spline points;
- zones and claims (extras of the zone subsystem);
- what the actors of actor pieces and their components save of themselves (
IPulseByteSaveable, for example the items of a chest), see Actor pieces; - other data of actor pieces through
OnSavePieceActor/OnLoadPieceActor.
Dismantling is not saved (the piece is saved as it was), and neither is the undo history.
Loading finds the definition of every piece by its id through the definitions of PulseFoundation (Pulse::Build::Pieces::LoadPieceSynchronous: a piece the game registered at runtime, else the piece asset, loaded at once on the authority). A save never holds the path of an asset, so moving a piece asset into another folder keeps saves working; renaming it changes its id (add a Primary Asset Id Redirect, see Pieces).
Loading replaces the pieces through RemoveAllPieces first. During that, IsClearingPieces() is true, so other systems know that these removals are no gameplay removals (no refunds, no dropped chest contents); OnPieceEndedNative passes them as Cleared. While a save is applied, IsLoadingSaveData() is true and the messages Pulse.Message.Build.Placed and .Removed carry CatchUp = Load, so message triggers and toasts leave the load out.
The building world saves itself through a save carrier of PulseFoundation (APulseSaveCarrier, spawned when the world begins play on the authority), because save systems collect actors and components: save identity Pulse.Build.Save.World, save scope World, load priority 100 (before most objects, so what keeps piece ids finds its pieces).
Actor pieces
The building world saves what the actor of an actor piece and its components save of themselves (IPulseByteSaveable of PulseFoundation: an inventory, the recipe of a machine) with the piece, in FPulseBuildSavedPiece::Components: one entry per object, with the name of the component (none for the actor) and its bytes. On load the actor is spawned, then each entry goes to the component of the same name (LoadFromBytes), before OnLoadPieceActor. A component that is no longer on the actor is listed in the import report (code MissingActorComponent).
- Only objects that want to be saved now (
ShouldSaveBytes) are saved. Objects that save over several frames (GetSaveTimingAsynchronous) are left to the save system, with a warning. - Name the components of piece actors in the class (default subobjects keep their names); a component added at runtime is found again only under the same name.
- Save systems that collect every
IPulseByteSaveableof the world themselves (the byte collector of PulseSave) would save these objects a second time: leave them out withPulse::Build::Save::IsSavedWithPiece(Object).
Builders
UPulseBuildComponent saves itself as bytes too (SaveToBytes / LoadFromBytes, FPulseBuildBuilderSaveData, version 2; another version is refused): build points, favorites, hotbar and recent pieces, the pieces by their definition ids. Its save identity Pulse.Build.Save.Builder (SaveIdentity) makes the key Player.<player id>.Pulse.Build.Save.Builder on the player state, pawn or controller, so a player gets them back in the next session. The build points are set on the authority; favorites, hotbar and recent pieces are kept by the machine that loads (a standalone game or the host of a listen server). The undo history is not saved.
Data of other systems
OnSaveExtras(TArray<FInstancedStruct>&)/OnLoadExtras(const TArray<FInstancedStruct>&, FPulseImportReport&): add one struct per system to the world’s data.OnSavePieceActor(Piece, Actor, States)/OnLoadPieceActor(Piece, Actor, States): other data of the actor of an actor piece, kept inFPulseBuildSavedPiece::ActorState(what the actor saves of itself is saved by the building world, see Actor pieces).OnLoadPieceActorruns after the actor’s own bytes are applied, and only for a piece with such entries.OnSaveDataAppliedNative(Report): the saved data is in place (every piece added,OnLoadExtrasdone). It still runs inside the load (IsLoadingSaveData()is true), so work a system held back while pieces came and went (links, navigation updates) runs here instead of on the next tick.
Piece states (FPulseBuildPieceState) decide themselves whether they are saved (ShouldSave) and copied into blueprints (ShouldCopy).
Builders
ExportUserData / ImportUserData give favorites, hotbar and recent pieces as FPulseBuildUserData (the definition ids of the pieces; an empty hotbar slot is an invalid id). ImportUserData takes the pieces that are ready at once and loads the others; each takes its place when it arrives, and an id no piece answers to is left out with a warning. The build points are NetState.BuildPoints (SaveGame; read them with GetBuildPoints); on the authority restore them with SetBuildPoints(Saved).