Crate pure_hfsm

Crate pure_hfsm 

Source
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

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:

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
Builder describing multiple interacting state machines
label
State of a state machine and Hierarchical state machine.

Structs§

SHandle
State handle
SmHandle
StateMachine handle
StateMachines
A collection of state machines

Enums§

Error
Potental errors from running a state machine
Target
Result of a transition

Traits§

Behavior
Behavior to adopt when in a state
Transition
Decider for state transition

Type Aliases§

StateData