Statemachine - CBATeam/CBA_A3 GitHub Wiki

Theory

A state machine consists of a set of states which are connected by transitions. Each state machine starts at a defined initial state and will transition to another state, if the transition's condition is fulfilled. If it cannot transition, it simply stays at its current state.

Implementation

State machines can either be predefined through config or can be dynamically created through function calls. Upon creation, a list the state machine iterates over is defined and afterwards states and transitions are added which have code attached to them. The state machines themselves run in a "clockwork": every tick (frame), all state machines get "executed" but only process one element each.

  • every tick an item of the state machine's list gets chosen
  • the onState function gets executed with said item
  • if any of the transitions conditions returns true, the transition is chosen
    • the onStateLeaving function gets executed
    • the onTransition function gets executed
    • the current state gets set to the transition's target state
    • the onStateEntered function gets executed
  • the next state machine gets executed by the clockwork

The list can either update itself automatically (just pass code as the list argument), be static or get updated manually. The automatic update happens when the list was fully iterated over, the manual update can be done by calling a function.

Use cases

Although this was made with AI systems in mind, this can be used for anything. You can write whole addons only with this. The advantage of this whole system is that you can iterate over large lists of things and execute code depending on their status or a certain condition - whilst being extremly performant. This isn't perfect for frame critical tasks, however this isn't an issue most of the time. Even with 60 list elements, all elements will processed within one second (at 60fps).

Functions

cba_statemachine_fnc_create
cba_statemachine_fnc_createFromConfig
cba_statemachine_fnc_delete

cba_statemachine_fnc_addState
cba_statemachine_fnc_getCurrentState

cba_statemachine_fnc_addTransition
cba_statemachine_fnc_addEventTransition
cba_statemachine_fnc_manualTransition

Examples

This is an example for a script that uses the CBA state machine system. In this case, we're "sharpening the senses" of AI units that got attacked before. Once they had contact, they stay alert. This would simulate units that did not expect an attack, but are now aware that they might come under fire again.

You can test this example by executing the following code in the debug console:

[] call compile preprocessFileLineNumbers "\x\cba\addons\statemachine\example.sqf"

This is an example for a CBA state machine config that can be read by the CBA_statemachine_fnc_createFromConfig function. This example would result in the same state machine as the one from example.sqf.

BI FSM Editor config

This is a config that allows you to create and edit CBA Statemachines using the Arma Tools FSM editor for increased readability and expandability.