Skip to content

Saving and Loading States

Saving works by retrieving all active state GUIDs. State machines have helper methods to achieve this, but it is your job to serialize them to disk. On load you can pass in the GUIDs to the state machine before you start it.

Saving Active States

Call GetAllActiveStateGuids from a state machine instance to retrieve all active state GUIDs. You will probably want to serialize these to disk.

Restoring Active States

Call LoadFromMultipleStates from a state machine instance and pass in the GUIDs retrieved from GetAllActiveStateGuids. This will set the temporary initial states of the instance so when you start it all previous active states will become active again.

The state machine must be initialized and stopped when states are loaded. The order of operations when loading should be as follows:

  1. Call Initialize on the component or the state machine instance. Components generally initialize automatically on begin play.
  2. Call LoadFromStates on the state machine instance and pass in the GUIDs.

  3. Call Start on the component or the state machine instance.

    • Initialize and Start should always be called on the component unless the state machine was created without a component through CreateStateMachineInstance.
    • For network usage see Connections and Actions and information relating to loading states.

FSMs With Only a Single Active State

GetSingleActiveStateGuid and LoadFromState are available, but will not work with parallel states. It is recommended to always use the methods that support multiple states because they work for all scenarios.

Switching to an Arbitrary State

As long as you have the GUID available you can switch to any state in the blueprint. Make sure to call Stop on the state machine if it is running, then one of the load methods above, then call Start.

GUID Calculation

The final GUID used at run-time is based on the state's path in the state machine blueprint. The path is each state machine node it takes to reach the state.

Each state has a NodeGuid that is assigned when a state is first created and should be unique per blueprint. If there is a duplicate the compiler will fix it.

Once the state machine is initialized the path to a state is calculated by combining relevant NodeGuids and hashing them to a PathGuid. This is what is returned from GetGuid.

GUIDs will stay consistent throughout modifications to the blueprint, providing the path of the state doesn't change. If you modify the scope of that state in the state machine-- such as move it to or from a nested state machine, or cut and paste the state, the path will change.

Benefits to this system:

  1. There will never be duplicates when using multiple state machine references or parent graph calls.
  2. Since the GUID is hashed from the path it's deterministic and will always be the same unless you change the path.
  3. Renaming a state won't impact the path.

Modifying GUIDs

If you need to modify the path of a GUID and maintain run-time save data, the Guid Redirect Map can be used on the primary state machine instance.

This accepts an old PathGuid as the key and the new PathGuid as the value. A PathGuid is the GUID that is returned from GetGuid at run-time. Whenever a method is used on the instance to locate a state by GUID, the redirect map will be searched first.

  • Guid Redirect Map needs to be maintained on the primary instance. When a state machine instance is used as a reference the individual PathGuids will be different than if it was used stand alone.

General Serialization

If you need to save variables you've added to the state machine blueprint you will need to implement your own serializer for this as you would with any other blueprint.