> For the complete documentation index, see [llms.txt](https://fsm2.onepub.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fsm2.onepub.dev/master.md).

# Overview

## Finite State Machines

FSM2 is a partial implementation of the UML2 State Machine.

State Machines allow you to model the behaviour of a system by specifying the sequence of states that a system can be in, as well as the events that cause the system to move between states.

![](/files/-MODgOUJBL0diYEAyViA)

In the above FSM for Water we can see water has three states and we have modelled four events that causes Water to transition from one state to another.

FSM2 uses a builder model to create a state machine with support for both static and dynamic transitions.

## Sponsored by OnePub

Help support FSM2 by supporting [OnePub](https://onepub.dev/drive/e69aafe8-c7f4-4965-bfe1-1ad7dbe7b23f), the private Dart repository. 

OnePub allows you to privately share Dart packages across your Team and with your customers.

Try it for free and publish your first private package in seconds.

| ![](/files/xscFghR6xU2ahbqQlSAX) | <p>Publish a private package in five commands:</p><p><mark style="color:green;"><code>dart pub global activate onepub</code></mark></p><p><mark style="color:green;"><code>onepub login</code></mark></p><p><mark style="color:green;"><code>cd \<my package></code></mark></p><p><mark style="color:green;"><code>onepub pub private</code></mark> </p><p><mark style="color:green;"><code>dart pub publish</code></mark></p> |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

To make your life easier FSM2 is able to generate a graphical visualisation of your FSM using the [Graphwiz](http://www.graphviz.org/) dot notation. This makes designing and debugging your state machine much easier.

Let's have a look at the code required to generate the above model:

```dart
var machine = StateMachine.create((g) => g
          ..initialState<Solid>()
          ..state<Solid>((b) => b
            ..on<OnMelted, Liquid>(sideEffect: (e) => print('its melting')
            ..onEnter((s, e) => print('we are now solid')
            ..onExit((s, e) => print('bye bye solid existance'))
          ..state<Liquid>((b) => b
            ..on<OnFroze, Solid>(sideEffect: (e) => print('its getting cold'))
            ..on<OnVaporized, Gas>(sideEffect: (e) => print('its getting very hot'))
          ..state<Gas>((b) => b
            ..on<OnCondensed, Liquid>(sideEffect: (e) => print('move a little closer will you'))
        );
```

Your state machine will have an initial state of `Solid` and to transition to an new state you send the state machine an event.

```bash
machine.applyEvent(OnMelted);
```

Once you have applied all events (which are processed asynchronously) you need to call:

````
```dart
await machine.complete;
```
````

The call will only return once all events have been processed. Until `complete` returns the StateMachine is considered to be in an indeterminate state.

To create a visualization of the state machine:

```bash
machine.export('test.gv');
```

To view the FSM

```bash
apt install xdot
dotx test.gv
```

##

## Credits

Credit goes where credit is due.

FSM2 started out life as a fork of FSM by Kirill Bubochkin <https://github.com/ookami-kb/fsm> which in turn was inspired by [Tinder StateMachine library](https://github.com/Tinder/StateMachine).

All of the good bits are his, all of the mistakes are mine :)