Local States

Keeping the logic near the data

An alternative to the state classes has been introduced in v1.2 of GC FSM. Instead of creating a separate class, you can have handle the state logic right in the event graph of the object running the FSM. In order to create an FSM Local State, right-click on the background of the event graph and select “FSM Local State” from the GC FSM category. You can immediately edit the name of the state.

The logic of a local state is limited to the OnEnter, OnTick and OnExit notifications. All three entry points have to be defined in a separate event graph page. In order to create a suitable page, just double-click on the local state node. GC FSM will automatically create a page with the three entry points, initially disabled.

If you want to re-use an existing graph, you can just select it in the combo box on the local state node.

You can rename a local state graph at any moment, the node will be automatically updated. If you delete the graph, the node will be invalidated.

Once an FSM local state node is assigned a graph, double clicking on the node will open the specified graph. The new graph is opened in the same editor tab, therefore replacing the current tab. This is a deliberate design choice of the Unreal editor and cannot be changed by GC FSM. If your mouse has a thumb button, you can get back to previous graph by pressing it. You can force the editor to open the graph in a new tab by pressing Shift while double-clicking the node.

When a local state is entered, the OnEnter handler is looked up in the specified graph and is executed. From then on, the OnTick handler, is executed every tick. When the state is exited, the OnExit handler is executed.

Notice that all these handler are called on the object that runs the FSM. This means that the local state handlers have complete access to all variables of the object.

Since local state handlers are called on the object that runs the FSM, launching an FSM from such handlers will launch the new FSM on that object. This new FSM is therefore at the same “level” as the original FSM and not a nested sub-FSM.

If two different FSMs on the same object enters two local states implemented by the same graph at the same time, you may get unexpected results. Don’t do that!

How to create new Local State node
A Local State node
Local State handlers are placed in a new graph
Here's a local state graph with all three handlers

Local State vs. State Classes

When should you use a “regular” state with a state class and when a local state? That depends. GC FSM provides both approaches to better suit your programming style and usage pattern. Here’s a list of the main differences, so that you can decide which is best for your use case:

State Slasses

  • Provide better encapsulation, since a new state object is instantiated before OnEntry and destroyed after OnExit
  • The implementation can be re-used on different context objects
  • Access to the context object is provided via the Context variable
  • De-couples the state implementation from the context object
  • An FSM launched from a state class nests, effectively running a sub-state machine
  • Allows multiple programmers to work simultaneously on two different states of a bigger FSM

Local States

  • The state implementation has direct access to the context object, including timeline components of actors
  • Keeps the logic near the data: you have one less class to maintain
  • An FSM launched from a local state does not nest: the FSM is run at the same “level” of the FSM that executed the handler
  • Only one programmer can work on the FSM at the same time

You can switch a state node from regular state node to local state node at any time, by right-clicking on the node an select the “Convert to Regular/Local State” command in the context menu