StateMachine¶

Event-driven state machine that manages keyed states and their transitions without per-frame polling.

Namespace: Jungle.Processes Inherits: ControllableComponent

Overview¶

StateMachine holds a list of states, each identified by a key and backed by a StateProcess. Transitions between states are condition-driven: when a state is entered, its transitions activate and the first one whose condition fires moves the machine to that transition's target state. No Update() polling is needed.

The machine is driven by its inherited execution frame. By default, it begins on OnEnable and ends on OnDisable, but the frame can be swapped for an event pair, an external trigger, or another component's cycle — see ControllableComponent.

Identifying States by Key¶

Each state in the list is a State Node containing:

A State Value that pairs a key, typed right on the state, with the inline StateProcess to run while the state is active.
A list of Transitions, each pairing a transition condition with a target state.

Transitions reference other states by key, not by index. To wire two states together, name the state, then pick it from the ▾ on the other state's transition target.

Why Keys?

Keys are matched by a stable id, so renaming a state never breaks a transition. A state key stays local to its machine; switch it to a Key asset only if something outside the machine must name that state.

Properties¶

Property	Type	Description
states	`List<StateNode>`	All states in this machine, each identified by a Key.
startingState	`SmartKey`	State to enter when the machine begins. Empty falls back to the first entry.

Runtime API¶

Member	Type	Description
`CurrentState`	`StateProcess`	The currently active state, or `null`.
`CurrentStateKey`	`SmartKey`	Key of the current state, or `SmartKey.None`.
`OnStateChanged`	`event Action<SmartKey, SmartKey>`	Fires with `(previousKey, newKey)` on transitions. An unset key means no state.

Methods¶

Method	Description
`TransitionTo(SmartKey, Action)`	Transition to the state with the given Key. Optional callback fires after the transition completes.
`HasState(SmartKey)`	Returns `true` if a state with the given Key exists.
`GetState(SmartKey)`	Returns the `StateProcess` for the given Key, or `null`.

Transition Conditions¶

Transitions live on each state and listen only while that state is active. Pick a condition type per transition:

Condition	Fires When
On Event (`EventTransitionCondition`)	A specified `IEvent` is raised. Subscribes on enter, unsubscribes on exit — no polling.
On Condition (`ConditionAdapter`)	A regular Jungle `Condition` becomes valid. Polls the condition each frame via `UpdateManager` while the state is active.
All Processes Done (`AllProcessesDoneCondition`)	The current state's processes have all completed naturally. Subscribes to the state's completion event.
Wait One Frame (`WaitOneFrameCondition`)	One frame after the state was entered. Useful for chaining states without sitting on an empty state.
Composite (`CompositeTransitionCondition`)	Combines child conditions with `All` (every child must fire) or `Any` (first child to fire wins).

The "On Event" condition mirrors the Reactor pattern: each transition subscribes to its own IEvent source and reacts to the next raise. Use this whenever a state should leave because something happened rather than because time passed or processes finished.