Debugging

Export

Use this guide when no State activates, the wrong transition wins, a State never finishes, or a Shared Variable has an unexpected value. Start with the Error Window, then diagnose active flow and data in Play Mode.

Start with the Error Window

Open Tools > Opsive > State Designer > Error Window, select the status-bar error count, or press Ctrl/Cmd+E. Select an error to identify its State or transition.

Resolve structural problems before Play Mode:

  1. Connect Start to the intended initial State.
  2. Assign required Actions, Conditions, Subgraphs, and fields.
  3. Confirm that every transition has a valid source and destination.
  4. Resolve missing Shared Variables and object references.
  5. Clear compiler errors that can remove node types or fields from the selectors.

A clean Error Window means the editor found no known structural or serialized-field problem. It does not prove that transition logic or runtime values are correct.

Follow active flow

Enter Play Mode with the editor open. Identify the active State, then inspect the transition that should leave it.

A State Designer graph highlights the active State during Play Mode.

If the State is wrong, trace from Start and inspect the first unexpected transition. If the State is correct but never changes, inspect its completion status, Evaluation Mode, and live Conditions. Pause when the problem is visible.

Inspect Actions, Conditions, and values

  • In an Action State, identify the first Action that remains Running or fails to complete.
  • On a transition, inspect Condition Mode, Evaluation Mode, disabled rows, and the live values used by each Condition.
  • In Shared Variables, confirm the intended name, type, scope, Internal/read-only state, and property binding.
  • For a Subgraph Reference, confirm the asset and every override mapping.

Use a field’s watch control to display a supported live value on the State. Do not create duplicate variables to hide a scope or binding problem.

Diagnose common symptoms

Symptom Check Fix
No State becomes active. Owner selection, enabled State Machine, Start connection, active GameObject, and compiler errors. Enable/select the correct owner, connect Start, and clear errors.
The wrong initial State runs. Start connection and selected state machine. Connect Start to the intended State and verify the operations-toolbar selection.
A State never finishes. Action execution mode and the first Action still Running. Correct the Action’s completion rule or use a transition that evaluates continuously.
A transition never evaluates. Evaluation Mode and State lifecycle. Use Continuous, On State Finished, or On Iteration Complete according to the source State.
The wrong transition wins. Competing valid Conditions and serialized transition order. Follow Transition Evaluation and Priority.
The graph flickers or loops. Always-true Conditions, Any, self-transition re-entry, and entry Actions that reverse the previous value. Add a stable state change, cooldown, consumed event, or narrower interrupt.
A value differs from the Inspector. Scope, Internal/read-only state, property binding, and scripts that write it. Inspect the owning variable and binding instead of creating a replacement.
A Subgraph uses the wrong object. Override names, types, source variables, and runtime replacement. Correct the Subgraph Reference mapping and retest in isolation.

Reduce the graph safely

Duplicate the owner or use a test scene. Disable one transition at a time, replace a project Action with Log, and use fixed values instead of live variables. Restore one dependency at a time after the smallest graph reproduces the issue.