Your First State Machine

Export

Build a three-state loop that waits in Idle, enters Patrol, writes a Console message in Log, and returns to Idle. The graph provides a visible active-state sequence and one controlled value to change.

Before you begin

  • Complete Getting Started.
  • Confirm the project uses Unity 2022.3.11 or newer and Entities 1.3.8.
  • Use a saved scene outside the imported sample folder.

Create the graph owner

  1. Create an empty GameObject and name it FirstStateMachine.
  2. Open Tools > Opsive > State Designer > Editor.
  3. Keep FirstStateMachine selected.
  4. Right-click empty graph space and select Add State Machine, or use the operations-toolbar add button.

The editor should show the selected GameObject, its state machine, the Element Inspector, and the Shared Variables panel.

The State Designer editor is labeled with the graph, Element Inspector, operations toolbar, and debug toolbar.

Add the states

  1. Press Space and add an Idle state.
  2. Add an Action State, rename it Patrol, and add a Wait Action with a duration of 1 second.
  3. Add another Action State, rename it Log, and add a Log Action with the text State machine cycle complete.
  4. Connect Start to Idle.
  5. Connect Idle to Patrol, Patrol to Log, and Log back to Idle.

The resulting graph forms a left-to-right flow with a return transition below it.

Idle, Patrol, and Log states form a repeating State Designer loop.

Configure the transitions

  1. Select the Idle-to-Patrol transition.
  2. Replace State Finished with Timer and set its duration to 1 second.
  3. Keep Patrol-to-Log and Log-to-Idle on State Finished.
  4. Open the Error Window and resolve every missing state, transition, or required field.

The Idle-to-Patrol transition uses a Timer Condition with a configured duration.

Idle has no Action that finishes, so its Timer transition provides the exit. Patrol finishes after Wait. Log writes the message and finishes immediately, allowing its default State Finished transition to return to Idle.

Verify in Play Mode

  1. Clear the Unity Console and enter Play Mode.
  2. Watch Idle become active for one second.
  3. Watch Patrol remain active while its Wait Action runs.
  4. Confirm that Log activates, the Console prints State machine cycle complete, and the graph returns to Idle.
  5. Observe at least two complete cycles.

The Log state exposes the Text field used for the tutorial's Console message.

Pause Play Mode while Patrol is active if Log finishes too quickly to see. The active-state highlight and repeated Console message together prove that state entry, Action completion, and transition evaluation are all working.

Make one controlled change

Change the Idle Timer from one second to three seconds. The state order should stay the same while Idle remains active longer. If another part of the cycle changes, inspect the transition you edited and undo unrelated graph changes.

Troubleshooting

Symptom Check Fix
No state becomes active. Selected owner, enabled State Machine component, Start connection, and Console errors. Select or enable the correct owner, connect Start to Idle, and resolve compile errors.
The graph remains in Idle. Idle-to-Patrol Timer Condition and Evaluation Mode. Assign Timer, set a positive duration, and use Continuous evaluation.
Patrol never finishes. Wait duration and Action execution. Use a finite positive Wait and confirm the Action is enabled.
Log never activates. Patrol-to-Log connection and State Finished Condition. Restore the transition and its default Condition.
The graph loops too quickly. Timer and Wait values. Use visible one-second values before tuning the production graph.

Use Debugging when the first invalid state or transition is not clear.

Continue learning

  1. Use Transition Evaluation and Priority before adding competing transitions.
  2. Adapt a complete Common Graph.
  3. Use Shared Variables when Actions and Conditions need the same data.
  4. Use Subgraphs when a reusable region should become its own asset.