## DEV Community

Matt Eland

Posted on • Originally published at newdevsguide.com

# Diagramming Finite State Machines with Mermaid.js

In this article we'll take a look at how Mermaid.js can help you transform simple markdown into state diagrams suitable for illustrating a finite state machine, hierarchical state machine, or the standard complexities of software systems.

## What are Finite State Machines (FSMs)?

A year or two ago I built a small game prototype that featured a boss fight with a crab monster that was powered by a finite state machine. This monster waited for the player to enter its arena, then descended from the ceiling, roared a challenge, and began fighting the player.

The monster was only damageable after it finished descending. Taking enough damage would make the monster react in pain before it could attack again. Hurting the monster enough caused it to die.

So what is a finite state machine (FSM)?

A finite state machine is a set of inter-related states that reacts to events by moving between different states in a controlled manner.

In this example, the states the boss could be in included descending, attacking, reacting to pain, and dying.

This boss fight could be represented by the following Mermaid state machine:

In this state machine we start at the leftmost dark circle, move to the Descending state, and then move between states until we reach the Dead state and the double circle at the right edge of the diagram. Once we reach the final circle, the state machine terminates and is not evaluated further.

## Building Simple Finite State Machines with Mermaid.js

You can build a state machine like the one above fairly easily with Mermaid.js and markdown.

Using Mermaid.js, you use a mermaid-compatible environment such as GitHub markdown, Polyglot Notebooks, the online live editor, or Obsidian. Once in that environment, you can begin a code block and specify the programming language as `mermaid` and then enter in markdown like the following:

``````stateDiagram-v2
[*] --> Descending
Descending --> Attack
Attack --> Pain
Pain --> Attack
``````

This markdown generates the following Mermaid.js Finite State Machine diagram:

Here we declare that we want a state diagram by specifying `stateDiagram-v2`.

Next we declare the various transitions between states by writing the name of the state and the state it can transition to. States may transition to multiple other states. For example ,the `attack` state may transition to `pain` or to `dead`.

The first state is represented by using `[*]` to the left of the arrow and the last state is represented by `[*]` to the right of the arrow.

Note that this diagram is identical to the one we saw earlier, except that it is arranged from top to bottom instead of from left to right. If you want to generate a left to right Mermaid.js finite state machine diagram, you can add the line `direction LR` after the `stateDiagram-v2` line.

## Highlighting Relationships in Mermaid.js FSMs

If you want to be explicit about the reasons for transferring from one state to another, you can add optional descriptions to each transition by adding a `:` and then the additional comments to the right of the relationship as shown with the following markdown:

``````stateDiagram-v2
[*] --> Descending      : Player entered arena
Descending --> Attack   : After roar animation
Attack --> Pain         : Hurt a lot
Pain --> Attack         : Finished animation
Attack --> Dying        : Ran out of health
Pain --> Dying          : Ran out of health
Dying --> [*]           : After death animation
``````

These labels tend to produce busier diagrams, but the extra text can add valuable information as well.

## Building Hierarchical Finite State Machines (HFSM) with Mermaid.js

One problem with traditional finite state machines is that you can get an almost combinatorial explosion of relationships between states the more you add new states to your finite state machine.

To combat this, you can nest state machines inside of other state machines to create a hierarchy of sorts.

Due to the hierarchical nature of these state machines, we call these nested state machines hierarchical finite state machines or HFSMs for short.

Nesting finite state machines can make the different states much more easy to manage while also making larger transitions more apparent as shown in the diagram below:

Declaring hierarchical finite state machines in Mermaid.js is somewhat straightforward, though the syntax involved is a bit different:

``````stateDiagram-v2
direction LR

state intro {
[*] --> Descending
Descending --> Roar
Roar --> [*]
}
state combat {
[*] --> Attacking
Attacking --> Pain
Pain --> Attacking
}
state defeated {
[*] --> Dying
}

[*] --> intro
intro --> combat
combat --> defeated
defeated --> [*]
``````

Here we declare 3 large root-level states named intro, combat, and defeated.

Inside of each state we list the various states inside of that larger state and how they transition between each other.

We also list how the three states relate to one another at the bottom of the markdown. In this case the three states form a sequence, but states will often cycle between each other more frequently than this.

In the diagram above, each state linked to the state next in sequence, but you can also link to states inside of a parent state by mentioning them explicitly as shown in the following markdown:

``````stateDiagram-v2
direction LR

state intro {
Descending --> Roar
Roar --> Attacking
}
state combat {
Attacking --> Pain
Pain --> Attacking
}
state defeated {
}

[*] --> Descending
combat --> Dying

note left of combat: The boss is damageable in this state
``````

Here the various states appear significantly more simple because we're relying less on `[*]` nodes to communicate state entry and exit and more on direct transitions between states.

This diagram does still have a transition from the entire `combat` state to the `dying` state within `defeated`. This is to indicate that any state inside of `combat` can transition directly to `dying` if it needs to.

Also note that you can declare a `note` to the left or right of any state to annotate things that need special attention.

Finally, it is possible to use hierarchical finite state machines and messages for transitions between states in the same diagram, though the result gets a bit messy:

``````stateDiagram-v2
direction LR

state intro {
Descending --> Roar : Movement Finished
Roar --> Attacking  : Animation Finished
}
state combat {
Attacking --> Pain  : Took Enough Damage
Pain --> Attacking  : Animation Finished
}
state defeated {
Dying --> Dead      : Animation Finished
}

[*] --> Descending      : Spotted player
combat --> Dying        : Took enough damage
Dead --> [*]            : AI Stopped

note left of combat: The boss is damageable in this state
``````

## Final Thoughts

I think that Mermaid.js finite state machine diagrams are pretty interesting and help convey the possible states a system or agent might be in.

State machine diagrams in Mermaid.js can do more than just emulate finite state machines and hierarchical finite state machines and I'd encourage you to read the Mermaid.js documentation for features such as decisions, forking, and even concurrency.

If you like some of the features of these diagrams but want additional flexibility, you may want to check out Mermaid.js flowcharts instead.

As for me, I plan on using Mermaid.js for a state diagram the next time I design an AI agent or system with enough complexity in its states and state transitions.