Make a Save Rule
- In the Content Browser, Add > Rolly > Rolly Save Rule, and name it, such as
DA_Lamps. - Under Match, add what its actors have: a class, an interface, an actor tag or a gameplay tag.
- Tick what they save differently from Actor Defaults (see Save actors and their components), and pick properties with Pick Properties under Properties. What Saves lists Saving, the transform, visibility, physics velocity, physics sleep and movement ticks, Keep Destroyed and Respawn, then Instances, Destruction, PCG Values, Regenerate PCG and Save Level Instance State (see Save harvested foliage and instanced meshes, Keep broken destructibles broken, Save PCG worlds and Keep level instances unloaded), then Apply Timing and Group, in that order in Actor Defaults, the rule editor and the Rolly Save component.
The rule editor lists the rule’s problems at the top, each with its fix, as Data Validation words them; Overlapping Rules names the rules that share its classes or tags and whether they apply earlier or later; In Open Level counts the open level’s actors it matches, with Select.
Every enabled Save Rule in the project applies; nothing lists it. A game finds them when its game instance starts, and every cook takes them, so a rule made during a Play In Editor session counts from the next one; an edit of a rule counts at once. Enabled off keeps a rule without effect. Rules of a Game Feature, DLC or mod plugin mounted after the game started apply once the Reload Save Rules node completes; it loads them without a hitch, and a save or load in progress finishes with the rules it started with.
Match actors
| List | An actor passes it with |
|---|---|
| Classes | One of these classes, or a class made from one |
| Interfaces | One of these interfaces, implemented in C++ or in Class Settings |
| Actor Tags | One of these in Details > Actor > Tags, without case: the way to pick out single placed actors |
| Gameplay Tags | One of these gameplay tags or a tag below one |
| Gameplay Tag Query | Tags that satisfy the query, for all-of and none-of tests (advanced) |
- Match Mode All Lists, the default, needs every list with entries; Any List needs one of them, so “class BP_Door or tag Door” is one rule.
- Maps limits a rule to those maps. It is no condition alone: a rule needs a class, interface or tag too, and one without gives the setup error NoCondition and matches nothing.
- Except leaves an actor out when it passes one entry of any of its lists, such as every prop but those tagged Static; its Maps leave the rule out of those maps.
- Matching loads nothing: a class or interface that is not in memory has no actors.
Gameplay tags come from the Gameplay Tag Asset Interface on the actor or one of its components, such as an Ability System Component. Blueprint actors cannot implement it; name the Gameplay Tag Container or Gameplay Tag variables that hold their tags in Project Settings > Plugins > Rolly Save > Gameplay Tag Variables, such as OwnedTags, and they are read on the actor and its components. Rules see the tags an actor has when it saves and when its values load: a respawned actor has its class defaults then.
What wins
Per actor, in this order, each later source winning every tick it sets:
- Project Settings > Actor Defaults.
- Each enabled Save Rule that matches, by ascending Priority, then by asset path.
- The actor’s Rolly Save component.
A component with Use Save Rules off takes no rule; Ignored Rules drops chosen rules for that actor only. The component’s Effective Settings shows each value with the source it comes from, the rules that match in applying order, the disabled and ignored rules that would match, and every path and handler with its source.
Add the Rolly Save component in the Components panel or in C++, not from a construction script: an actor a load spawns again is judged before its construction script runs, so a component that script adds is not seen then.
Make actors save or not
Saving, in Actor Defaults, rules and the component:
| Value | The actor |
|---|---|
| With Saved State (default) | Saves when it or a component has a variable with SaveGame ticked, it has a Rolly Save component, something picks a property for it or attaches a Save Handler that has state to save, or it is a level instance whose level is unloaded, another than at the start, or holds actors that save |
| Always | Saves without them: its transform and other ticks, and whether it was destroyed. Each such actor adds a record to every save |
| Never | Is left out of saves and loads with its components and the child actors it hosts. A destroyed one comes back as placed, and an older save’s records of it are not applied (LeftOutByRule) |
A local player’s controller, own pawn and player state save as before under every value (see Save the player). Actor Defaults set to Never make a project save only the actors rules or components set otherwise; set to Always, every actor in your levels saves, about 1.3 KB each, which the setup warning EveryActorSaves names.
Set values after Begin Play or when asked
Apply Timing, in Actor Defaults, rules and the component, picks when a load that opens its map, or a level’s return, sets an actor’s saved values. Its components’ and attached handlers’ values wait with it, and On Rolly Save Loaded and the component’s On Loaded run after them. A spawned actor is spawned again at its saved place at once, its other values waiting. Keep Current Map sets them at once with every timing.
| Apply Timing | The values arrive | Use it for |
|---|---|---|
| Before Begin Play (default) | Before any Begin Play | Actors that read their state in Begin Play |
| After Begin Play | Once every actor’s Begin Play ran; saves wait until then | Actors whose Begin Play would overwrite them |
| When Asked | When your game calls Apply Saved Values for the actor | Actors that set themselves up later, such as after loading data or a network handshake |
Apply Saved Values (Rolly Save subsystem, server or standalone game) returns true when it applied values, then false; it returns false in a new game and on a client. Saves made before the ask write the actor’s waiting records back as they were loaded, and so do a level’s leave and return, travel and a restart of the map, so nothing is lost while the actor waits.
Save properties by path
Saved by Path saves engine and plugin properties that have no SaveGame tick. An entry names:
| Field | Means |
|---|---|
| Component | The component’s name as the Components panel shows it. None, with Component Class and Component Tag empty: the actor’s own property |
| Property | The property’s name in C++ or the Blueprint |
| Component Class | Every component of this class or one made from it, components added during play included. With Component set, only the one of that name |
| Component Tag | Only components with this in their Component Tags |
| Members | Members inside a struct property, outermost first, such as Collision Enabled inside Body Instance; at most 8 |
| Setter | A function of the component or actor that takes the value, called instead of the automatic choice, such as a plugin’s Set Speed; Pick Properties fills it from the property’s Blueprint setter. None: automatic |
The Rolly Save component has the same list for its own actor. A load gives the value back through the setter Rolly Save knows for it, so what depends on it updates:
| Property | Setter |
|---|---|
| A light’s Intensity, Light Color, Temperature | Set Intensity, Set Light Color, Set Temperature |
| A static mesh component’s Static Mesh | Set Static Mesh (bounds, collision and navigation update) |
| A mesh’s Override Materials | Set Material per element |
| A component’s Visible, Hidden in Game | Set Visibility, Set Hidden in Game |
| Body Instance > Collision Enabled, Collision Profile Name, Simulate Physics, Enable Gravity | Set Collision Enabled, Set Collision Profile Name, Set Simulate Physics, Set Enable Gravity |
Otherwise a property with a C++ setter takes the value through it; any other is written, redrawing a component. A value written that way can leave what depends on it stale: name a Setter, or refresh it in On Rolly Save Loaded. A Setter must take exactly one value of the property’s type, return nothing and be no network event; one that does not gives the setup error BadSetter, once, and loads use the automatic choice.
- Values apply in the order the entries are listed, sources by precedence.
- Of a path and a member of it, only the path saves (setup warning Overlap).
- What the ticks of What Saves save (transforms, attachment, hidden, velocities, movement modes) cannot be saved by path, nor a delegate, a fixed-size C++ array, or a C++ struct some of whose members lack SaveGame; each is refused once with CannotSave and its fix. A path deeper than 8 members, or longer than 1,023 characters with its members, is refused with TooLong.
- A Blueprint variable saves by path, but tick SaveGame on it instead: renaming it later loses a value saved by path without a property redirect (setup warning OfVariable).
- A value that holds an object the save cannot hold, such as a dynamic material instance, is left out with PathLeftOut, and a load keeps the live value.
- A load applies a value only to a property the actor’s rules and component pick then, of the type it was saved as; anything else is skipped with PathNotApplied. A value whose asset is missing keeps the live value (PathKeptLive), and the next save writes the live one.
Pick properties
Pick Properties, in the rule editor (for its Browse Class) and on a Rolly Save component (for its actor’s class), opens a window listing the class and its components, each with two groups:
- SaveGame: variables of Blueprints you can change. A tick sets SaveGame on the variable in its Blueprint, as its Details do, sets Cook Property GUIDs so a later rename keeps saved values in packaged games, and compiles the Blueprint; Ctrl+Z undoes it. The tick reaches every actor of that Blueprint, whichever rules match. Members of a Blueprint struct have ticks of their own, and Flag Every Member ticks them all at once.
- By path: other properties. A tick adds the entry to Saved by Path of the rule or component; each row says how a load gives the value back (the setter, refresh only, or written only).
Rows of other rules show where they come from: untick one to leave it out for this rule’s actors (a Not Saved entry). The Components of a Class node writes entries for every component of a class, such as one your game adds during play. Select a by-path row to set its Target and Apply With at the bottom. Saved Only lists only what saves, as a component lists over a hundred properties; Show All adds those neither Details nor Blueprint show. The window changes nothing during Play In Editor.
Attach Save Handlers
Handlers, in rules and the component, attaches Save Handlers to each matched actor, for state that is in no property; each entry holds the handler’s settings, and each actor gets its own copy, which Get Target Actor gives the actor (see Save what is not a variable). Removed Handlers drops a class earlier sources attach.
Leave things out
Not Saved removes what earlier sources pick, in rules and the component:
- A Saved by Path entry of an earlier rule; a later rule or the component can pick it again.
- A variable with SaveGame ticked, for the matched actors only: other actors of the class keep saving it.
- A whole component, by an entry without a property: it neither saves nor loads, its SaveGame variables included. With Component Class, every component of that class.
A Not Saved entry of a SaveGame variable or a whole component holds against later sources too; only Ignored Rules or Except drops it. A save made before the entry still holds the variable’s value, so the next load restores it once.
Old saves
Rules are not stored in save files: a load resolves each actor with the rules of the build that loads. A rule that changes an actor’s Apply Timing or Saving reaches saves made before it; values saved by path that no entry picks any more are skipped. A property or member renamed with +PropertyRedirects keeps its values saved by path; for one whose type changed, a migration step reads the old value with Get Path Value and writes the new type with Set Path Value (Rename saved data).
From C++
URollySaveRule (Rules/RollySaveRule.h) is the rule, with FRollySaveActorFilter and FRollySavePropertyPath; URollySaveComponent has bUseSaveRules, IgnoredRules, Properties, NotSaved, Handlers and RemovedHandlers. RollySaveRuleExplain::Explain (Rules/RollySaveRuleExplain.h) tells what one actor saves, each value’s source, the rules that match it and their state, the paths each source saves and leaves out, and the handlers attached and removed. URollySaveWorldSubsystem::ResolveActorSettings gives what a world’s actor resolves to now. URollySaveSubsystem::ApplySavedValues is Apply Saved Values; URollySaveSubsystem::ReloadSaveRules reloads the rules and calls a delegate once they apply.