Crate pure_hfsm[−][src]

Expand description

Pure HFSM

A finite state machine library with a clear separation between the machine definition and its changing state.

I developed this library for my bevy project. This is why I give generic lifetime parameters to Behavior::World, Behavior::Update and Transition::World types. This requires GATs, but I found it was the only way to get it to work with the horror that is SystemParam in bevy.

The goal of the library is to have the state machine description be completely independent from the state. From this, we get a lot of cool stuff that other state machine libraries do not let you do easily or trivially, such as:

Serialization and deserialization of state machines
Compact representation of both the state and the descriptions
Minimal mutable data, separate from the state machine. In bevy ECS, I can store it independently from the state machine, as a Component (while the state machines are loaded as Asset)
Shared state machines with as many instances as you want

There is a few downsides to know before using this library:

There is more boilerplate to write to get things to work
It’s not type safe! However, you will get an error when constructing the state machine if you are referring to non-existent states or machines in your builder::StateMachines! Which is far better than an error when running transitions, but still not as optimal as a compilation error.
There are three different StateMachines type you have to interact with in order to use this library (1) is the serialized representation builder (2) is the compact immutable description (3) is the mutable state handle or label.

For the serialized representation of the state machine to still be convenient and maintainable while having a compact internal representation, you will need to use builder::StateMachines for serde interface and convert it into a runnable state machine as a second step.

Features that may or may not be added in the future

serde cargo feature flag to be able to compile the library without serde
Better documentation
A version without the StateData Box<dyn Any>
Tests
A visual state machine editor

License

This software is licensed under either MIT or Apache 2.0 at your leisure. See LICENSE file for details.

How to use this library

This library is divided in three types of state machines:

builder::StateMachines: A serializable description of multiple interacting state machines
StateMachines: is a compact description of multiple interacting state machines
label::NestedMachine: is the running state of a state machine

You will need to first describe the state machine with builder::StateMachines, use it’s build method to get a StateMachines.

You will be able to control the execution of a Hierarchical Finite State Machine (aka HFSM) with the label::NestedMachine, passing it a StateMachines when necessary.