Choose which actors save
- With no setup, an actor saves when its class or the class of one of its components has a variable with SaveGame ticked, implements the Rolly Save Interface, or has a Rolly Save component. Each of its components with such a variable saves too.
- Saving, in Actor Defaults, a Save Rule or the component, makes an actor save without those (Always) or never (Never); see Choose what saves.
- Actors of the persistent level, of streaming levels, level instances and World Partition cells save, also those that stream in during play (Save streamed levels and World Partition worlds).
- The Game Mode, the Game State and the Level Blueprint save by their roles (see Save and load your game). HUDs, game sessions, camera managers, the world settings and AI controllers never save as actors.
- A local player’s controller, own pawn and player state save with the player, not as actors (see Save the player). A pawn the player possesses besides its own, such as a vehicle, saves as an actor. Players who joined a server from another machine are not saved.
- An actor registered with Register Object for Saving saves under its name instead.
- Project Settings > Plugins > Rolly Save > What Saves > Actors turns actor saving off: no actor is saved or loaded, and the next save drops what an earlier save held for actors.
Pick what an actor keeps
Project Settings > Plugins > Rolly Save > Actor Defaults sets what every actor that saves keeps beside its variables:
| Setting | Keeps |
|---|---|
| Save Transform | Location, rotation, scale, what it is attached to, and for a pawn of an AI controller the direction the controller faces. A placed actor whose root is not Movable stays where its level puts it; a spawned actor always keeps its transform |
| Save Visibility | Whether it is hidden in game |
| Save Physics Velocity | How fast its root moves and spins while it simulates physics |
| Save Physics Sleep | Whether its simulating root sleeps, so a crate that came to rest stays at rest; set after its velocity. A body touching a moving one wakes |
| Save Movement | Its movement components’ velocity and a character’s movement mode |
| Keep Destroyed | A placed actor destroyed during play stays destroyed |
| Respawn | A spawned actor comes back after a load |
| Save Level Instance State | For a level instance: whether its level is loaded and which level it shows (see Keep level instances unloaded) |
| Apply Timing | Before Begin Play: the actor has its saved values when its Begin Play runs. After Begin Play: they are set once every actor’s Begin Play ran |
| Saving | With Saved State, Always or Never, as above |
To change them for a group of actors, such as every lamp, make a Save Rule (see Choose what saves). To change them for one actor, add a Rolly Save component to it (Add Component, Rolly group) and tick the box beside a setting: that setting then takes the component’s value, the others follow its Save Rules and Actor Defaults. The component’s values are not saved, so set them in the editor, not during play.
An actor’s owner (Set Owner) saves too, when the owner comes back after a load: another saved actor, the Game Mode or the Game State, or a local player’s controller, pawn or player state, which a load with Open Saved Map sets as the owner once the player’s pawn is there.
Run code when an actor is saved and loaded
A Rolly Save component on the actor gives three events (select the component, Details > Events):
| Event | Runs |
|---|---|
| On Pre Save | Right before the actor is saved, and before its level is remembered as the player leaves it. Copy state that is not in a variable with SaveGame ticked into one here |
| On Saved | Once a save that holds the actor is written; not after a failed save, and not when its level is only remembered |
| On Loaded | Once the actor and every other object of the same load, or of its level’s return, have their saved values, so references between them are set |
Without the component, add the Rolly Save Interface in Class Settings > Implemented Interfaces: its events On Rolly Save Pre Save, On Rolly Save Saved and On Rolly Save Loaded run at the same moments, on any Blueprint whose objects save. A custom event of one of those names does the same without the interface. The events run on the server or in a standalone game only.
A save runs, per actor, the component’s On Pre Save, the actor’s On Rolly Save Pre Save, then writes the actor, then each of its saving components’ On Rolly Save Pre Save and record. Once the file is written, On Rolly Save Saved runs on each of them in the same order, then each component’s On Saved, then the save node’s Success and On Save Finished. A load sets every saved value first, then runs On Rolly Save Loaded, then each component’s On Loaded.
| Case | Values set | On Rolly Save Loaded and On Loaded |
|---|---|---|
| Open Saved Map, placed or spawned actor | Before its Begin Play | Before its Begin Play |
| Open Saved Map or a remembered level, Apply Timing After Begin Play | Once every actor’s Begin Play ran | Right after its values |
| Keep Current Map, placed actor | At once | At once |
| Keep Current Map, actor spawned again | Before its Begin Play, which runs while it spawns | After its Begin Play |
| Return to a remembered level | Before its Begin Play | Before its Begin Play |
| The player’s pawn, controller and player state | See Save the player | Right after their values |
| A component that appears after the load | The frame after it appears, after its Begin Play | Right after its values |
Keep destroyed actors destroyed
Every placed actor destroyed during play stays destroyed after a load, also one without saved variables, such as a pickup. Clear Keep Destroyed in its Rolly Save component for one that should come back: it comes back as placed, without the values an earlier save gave it. A child actor always comes back with its Child Actor Component.
- In a standalone game, a load removes such an actor before it begins play: it runs no Begin Play, End Play or Event Destroyed, so a crate that drops loot when destroyed does not drop it again.
- On a listen or dedicated server, a replicated placed actor runs Begin Play, End Play and Event Destroyed once before it goes, so clients see it go, and a load with Keep Current Map runs End Play and Event Destroyed. Is Removed by Load is true there: check it before dropping loot or counting a kill.
- One that does not replicate goes before Begin Play on the server but stays on clients, and the Message Log says so once per class (DestroyedNotReplicated): tick Replicates on placed actors that can be destroyed.
Bring spawned actors back
A spawned actor that saves comes back after a load with its class, transform, saved values, components and child actors, and keeps its save ID. With Open Saved Map all of it is set before its Begin Play; with Keep Current Map see Load into the current map. A class renamed with +ClassRedirects in Core Redirects spawns as the new class.
- Its saved values are set before its construction script runs: a construction script that sets a variable with SaveGame ticked overwrites the saved value.
- Clear Respawn for actors your game spawns again itself, such as in Begin Play: they are not saved, so a load does not double them.
- A record whose class is gone, abstract, deprecated, not an actor or one the engine makes on every map load is not spawned. The load says so (RespawnRefused) and keeps its values for the next save.
Give an actor an ID of its own
A placed actor saves under its level and name, such as /Game/Maps/Tavern:Chest_2; its outliner label does not count. Moving it to another sublevel, replacing it or copying it gives it another name, so it loses its saved state.
Fill in Custom Save ID (the Rolly Save component’s advanced settings) to keep its state across such changes: it then saves under /Game/Maps/Tavern:#FrontDoor. Use 1 to 128 letters, digits, _, - and ., unique in the map; IDs that differ only in capital letters count as one. An ID that cannot be used, or that two actors share, gives a setup error, and the actor saves under its name.
Get Save ID gives the ID of any object a save holds, for logs and your own records. A spawned actor gets a GUID the first time it is saved or asked for and keeps it after loads.
Save components added during play
Components of the actor’s class and its construction script are found by name. A component that the details panel, an Add Component node in an event graph or Add Instance Component added, and a Rolly Save component added during play, is created again under its saved name, with its values.
- A component that C++ code or a Game Feature adds is made by its creator, not by a load. When its creator makes it after the load under its saved name, it takes its saved values the frame after it appears, then runs On Rolly Save Loaded. Until then the load keeps its values for the next save.
- A Game Feature action that gives components automatic names gives them no name to find them by after a load: name them after their class.
- A Blueprint that adds a component in Begin Play every session has two after a load, the saved one and its own: check Was Restored by Load first.
Attachments and child actors
An attached actor saves its parent and socket, its transform relative to the parent and where it was in the level; after a load it is attached again, to a placed or a spawned parent. When the parent is gone, such as a placed parent destroyed after the save, or refuses the actor, the actor goes where it was in the level when it was saved, and the load’s Issues say so (UnresolvedReference or NotApplied).
A child actor saves through its Child Actor Component, which makes it again, also when the component belongs to a spawned actor or gets its class in the construction script; its values then apply to it. A child actor of an actor that does not come back is not saved.
Load into the current map
With Keep Current Map:
- Placed actors take their saved values at once; those the save holds as destroyed go at once, running End Play and Event Destroyed.
- A spawned actor that is there takes its values in place. One that is not is spawned again; its Begin Play runs while it spawns, after its own values and its C++ components’ values are set, and before its construction-script components, its child actors and the components the load creates get theirs. All of them have their values before On Rolly Save Loaded runs.
- In the map the save was made in, spawned actors that save but that the save does not hold are removed, so repeated quick loads never pile up copies. Spawned actors that do not save stay, and in another map no spawned actor is removed.
- A placed actor destroyed after the save stays destroyed, since only loading its level makes it again: the load’s Issues list it as DestroyedSinceSave, and a load with Open Saved Map brings it back.
Check whether a load restored an actor
Was Restored by Load is true from the moment an object takes saved values, from a load or from its level’s memory when the player returns, until the world’s next load, so Begin Play can skip setting up what the save restored. It is false for objects placed or spawned since that save, and on clients.
In a network game
- Only the server saves and loads; a save or load called on a client fails with NotAuthority. What a load changes on the server reaches clients as replication does: replicated actors spawned again, moved or removed appear so on clients.
- Placed actors a load removes: see Keep destroyed actors destroyed.
- The listen server’s host is a local player and saves as one; players who joined from other machines are not saved, and neither are their pawns.
- Get Save ID, Was Restored by Load and Is Removed by Load answer false on clients, and the events run on the server only.
From C++
URollySaveWorldSubsystem (Game/RollySaveWorldSubsystem.h) gives ResolveActorSettings, what an actor keeps after its Save Rules and its component’s overrides, GetSaveId, WasRestoredByLoad and IsRemovedByLoad. A C++ class declares OnRollySavePreSave, OnRollySaveSaved and OnRollySaveLoaded as its own UFUNCTIONs, without parameters or a return value, instead of implementing URollySaveInterface (Record/RollySaveInterface.h); URollySaveComponent (Actor/RollySaveComponent.h) has the events as OnPreSave, OnSaved and OnLoaded. RollySaveActorIds (Actor/RollySaveActorIds.h) builds and reads the ID texts, and RollySaveActorSections (Actor/RollySaveActorSections.h) the fields of the ACTR and COMP record sections, for tools that read saves.