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 asAsset
) - 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 representationbuilder
(2) is the compact immutable description (3) is the mutable state handle orlabel
.
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
Copyright © 2021 Nicola Papale
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 machinesStateMachines
: is a compact description of multiple interacting state machineslabel::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.
Modules
Builder describing multiple interacting state machines
State of a state machine and Hierarchical state machine.
Structs
Enums
Traits
Behavior to adopt when in a state
Decider for state transition