State Machine References

You can reference other state machine blueprints to allow for re-usability. They function the same as nested state machines.

Referencing a State Machine

1. From your state machine graph, right click on the graph and choose Add State Machine Reference.
2. Select the state machine blueprint you wish to reference.

Reference Behavior

• The context of the super state machine will be passed into the reference automatically.
• The reference will inherit the super state machine's replication settings.
• The system attempts to catch circular referencing, but ultimately it is up to you to make sure you don't run into an infinite loop. Doing so will fail to instantiate the state machine during initialization and throw a run-time error.

Intermediate Graphs

State machine references can optionally have an intermediate graph. This allows you to hook into entry points for when the reference starts, updates, or ends.

1. Right click on the state machine reference and choose Enable Intermediate Graph.
2. Then double click on the intermediate icon in the top right, or right click the node and select Go to Local Graph.

Changing the double click behavior

The default behavior when double clicking a reference is to open the reference blueprint, not the intermediate graph in the owning blueprint.

To change this, go to your Editor Preferences -> Logic Driver Editor and look for Reference Double Click Behavior. You can set it to prefer the local (intermediate) graph if you wish.

An optional node Get State Machine Reference node is available in this graph which allows you to set or read functions and variables on the reference.

Can I change the context of the reference?

Yes, you can pass in a new object to Start State Machine Reference. Although this practice is discouraged as an entire state machine should only have one owning object, and having multiple contexts may not work well with replication.

Dynamic References

It is possible to dynamically select the state machine class prior to initialization. This is done by assigning the Dynamic Class Variable to a variable on the state machine blueprint owning the reference. That variable is read during initialization to determine the class to use.

When a dynamic reference is useful

Say you have a state machine that handles generic combat for all characters and want it to branch out into character specific ability sub state machines. Ordinarily you would need to include all possible ability state machines filtered by transitions, or utilize inheritance and copy the entire state machine for each character, replacing the ability sub state machines as necessary.

With a dynamic reference you can simply design one state machine for all characters and utilize one dynamic reference which initializes to the correct ability state machine class for each character.

1. Add a variable of type State Machine Instance -> Class Reference to the owning state machine blueprint.
   • Use TSubclassOf<USMInstance> in C++.
2. Select the reference node and change Dynamic Class Variable to the variable you created.
3. Set the value of the variable before Initialize() is called on the primary state machine.
   • This could also be done in a state machine component's properties under the actor's class defaults.

Replication

If this is being used with replication it is important the variable is also replicated or the client may initialize with the wrong reference class.

Guid Calculations

Guid calculation for dynamic references will always occur at run-time, adding some overhead when initializing the state machine.

Changing the Dynamic Class

If you wish to change the dynamic class you will need to call Shutdown() on the owning state machine instance, change the dynamic class variable's value to the new class, then call Initialize() on the owning state machine again.

Converting State Machines In-Place to References

Sub state machines can be converted to a new state machine blueprint and referenced automatically.

1. Right click a sub state machine and select Convert to State Machine Reference.

2. Choose the parent class of the new reference.

   Choosing a Parent

   Before creating a reference you can choose the state machine parent. It will default to the current parent of the state machine you are in.

   There is also a Use Project Default check box. This uses the value of Default State Machine Blueprint Parent Class, located under Project Settings -> Logic Driver Editor.

3. Select the file location to save the reference.

Convert to Reference Behavior

Converting a state machine in-place will also look for any existing variables that are referenced and recreate them in the new blueprint. Any additional event graph logic or custom functions won't be copied.

Assigning Custom Node Classes

State machine references that have a template assigned may also have a node class assigned. This allows public variables to be exposed on the node.

1. First select the state machine reference node and choose Use Template. State machine instance properties will appear.
2. Select the state machine node class you wish to use from the Node Class drop down.

• The node instance can be accessed by calling GetRootStateMachineNodeInstance() from the reference and casting to your USMStateMachineInstance class.
  • This is how you access any exposed variables.
• A template and node class will automatically be assigned if the blueprint being referenced has a Node Class pre-assigned in its class defaults.
• Templates can be auto assigned if the Project Editor setting Enable Reference Templates by Default is true.

Properties

Use Template

• Creates a template based on reference class so default values may be loaded during run-time.

Allow Independent Tick

• Allows the state machine reference to tick on its own.

Call Tick on Manual Update

• The Update method will call Tick only if Update was not called by native Tick.