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 asset 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 Key. 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 ScriptableObject asset with the inline StateProcess to run while the state is active.
A list of Transitions, each pairing a transition condition with a target Key.

Transitions reference other states by Key, not by index or string name. To wire two states together, drag the same Key asset into one state's identifier field and another state's transition target.

Why Keys?

Keys are ScriptableObjects, so they're refactor-safe (renaming the asset doesn't break references) and can be shared across systems — the same Key used to address a state can also drive DataStorage entries, inventories, or other Jungle systems.

Properties¶

Property	Type	Description
states	`List<StateNode>`	All states in this machine, each identified by a Key.
startingState	`Key`	Key of the 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`	`Key`	Key of the current state, or `null`.
`OnStateChanged`	`event Action<Key, Key>`	Fires with `(previousKey, newKey)` on transitions. A `null` key means no state.

Methods¶

Method	Description
`TransitionTo(Key, Action)`	Transition to the state with the given Key. Optional callback fires after the transition completes.
`HasState(Key)`	Returns `true` if a state with the given Key exists.
`GetState(Key)`	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.