HierarchicalStateMachine transitionTo()

Definition

Transitions the state machine to a specified state.

template<class TContext>
void transitionTo(HierarchicalStateMachine<TContext>::State& state, bool immediate = false);

Type Parameters

• TContext: The type of the context, which holds data or behavior relevant to the state machine.

Parameters

• state: The state to transition to.
• immediate: Indicates whether the transition should happen immediately or in the next update cycle.

Remarks

The immediate parameter controls whether the transition occurs instantly or waits for the next update() call.
The current state's exit logic and the next state's enter logic are queued as part of the transition.
NOTE: if used within a callback function, multiple calls of transitionTo will result in only the last function call being the next state to transition to.

Usage

1. simple transitionTo usage

struct FooContext
{
...
// state hierarchy: S1 (root) -> S2 -> S3
static HierarchicalStateMachine<FooContext>::State state1;
static HierarchicalStateMachine<FooContext>::State state2;
static HierarchicalStateMachine<FooContext>::State state3;

HierarchicalStateMachine<FooContext>* hsm = nullptr;
...
};

auto ctx = FooContext();
auto hsm = HierarchicalStateMachine<FooContext>(&ctx);

ctx.hsm = &hsm;

hsm.transitionTo(FooContext::state3, true); // immediately transitions to state1, without the need to queue and wait for the next update cycle

and the result code above is:

S1 ENTER
S2 ENTER
S3 ENTER
S1 UPDATE
S2 UPDATE
S3 UPDATE

2. for deep transition, it only occurs when you are transitioning from a lower state up to the higher state, which re-enters the transition. let's say the current state is S3 and you want to transition to S1, then the order of transition will be:

S3 UPDATE -> TRANSITION TO S1
S3 EXIT
S2 EXIT
S1 EXIT    // this line will not be visible if deep transition is disabled
S1 ENTER   // this line will not be visible if deep transition is disabled
S1 UPDATE

3. another usage of transitionTo if used within a callback function:

// if used within a callback, it's best to only use a single call of 'transitionTo()'
static void update(FooContext* const ctx)
{
    ...
    ctx->hsm->transitionTo(FooContext::state1); // transitions to state1
    ...
}

// Multiple transitions controlled by a conditional statement is fine.
static void update(FooContext* const ctx)
{
    ...

    if (boolFlag)
    {
        ctx->hsm->transitionTo(FooContext::state1); // transitions to state1 if boolFlag is true
    }
    else
    {
        ctx->hsm->transitionTo(FooContext::state2); // transitions to state2 if boolFlag is false
    }

    ...
}

// Consecutive transitions will result to only the last transition being applied, so it's best avoid this case.
static void update(FooContext* const ctx)
{
    ...

    ctx->hsm->transitionTo(FooContext::state1); // state 1 will be overridden with state2 in the next line
    ctx->hsm->transitionTo(FooContext::state2); // state 2 is now the next state to transition

    ...
}

TODO

• show order of transitions