A standalone Lua module for implementing finite state machines with synchronous and asynchronous transitions.
Lua Finite State Machine is a lightweight library for implementing finite state machines in Lua. It enables developers to model complex stateful behavior through declarative configurations, supporting synchronous and asynchronous transitions with customizable callbacks. It solves the problem of managing state changes in applications like games, UIs, or workflows by providing a structured and event-driven approach.
Lua developers building applications that require state management, such as game developers for character or scene states, UI developers for interface state handling, or engineers implementing workflow or process automation in Lua.
Developers choose this library for its simplicity, minimal footprint, and powerful features like asynchronous transitions and flexible callbacks, all in a standalone module with no dependencies. It is heavily inspired by javascript-state-machine, bringing proven state machine patterns to the Lua ecosystem.
A finite state machine lua micro framework
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.
States and transitions are defined using intuitive Lua tables, making setup straightforward and readable, as demonstrated in the usage examples with events like 'warn' and 'panic'.
Supports asynchronous state changes by returning ASYNC from callbacks, allowing deferred transitions until operations complete, ideal for animations or async logic in games or UIs.
Offers before/after event and state entry/exit callbacks with shorthand notations (e.g., onpanic, ongreen), enabling custom logic at any point in the transition lifecycle.
A standalone Lua module with zero dependencies, making it easy to integrate into any Lua project without adding bloat or compatibility issues.
Lacks support for hierarchical state machines, which are common in complex applications, and doesn't include built-in visualization, debugging, or error-handling tools beyond basic callbacks.
The README is concise and assumes familiarity with state machine concepts or the inspiration from javascript-state-machine, which might hinder developers new to FSMs or Lua.
Asynchronous transitions require manual handling of the transition() method and cancellation, which can lead to error-prone code if not managed carefully, as noted in the async examples.