https://github.com/zigrazor/cxxstatetree
A C++ Header-Only Hierarchical State Tree Library
https://github.com/zigrazor/cxxstatetree
cpp cpp-library cpp20 gaming header-only-library state-machine statetrees
Last synced: 2 months ago
JSON representation
A C++ Header-Only Hierarchical State Tree Library
- Host: GitHub
- URL: https://github.com/zigrazor/cxxstatetree
- Owner: ZigRazor
- License: mpl-2.0
- Created: 2025-06-30T15:22:13.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-07-14T17:25:08.000Z (4 months ago)
- Last Synced: 2025-07-14T20:07:36.564Z (4 months ago)
- Topics: cpp, cpp-library, cpp20, gaming, header-only-library, state-machine, statetrees
- Language: C++
- Homepage:
- Size: 1.8 MB
- Stars: 55
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
CXXStateTree
Modern Hierarchical State Machine for C++20
## 🚀 Features
* 🔧 Fluent builder API with lambda-based DSL
* ⚡ Fast runtime performance with zero heap allocation
* 🛡️ Optional guards and actions for transitions
* 🔄 Event-based state transitions
* 🧪 Google Test integration
* 📈 Code coverage with Codecov
* 🌳 Designed for extensibility: nested states, DOT export coming soon
* 🔧 Deployed as Shared Library and as Single Header-Only library
---
## 🛠️ Quick Example
```cpp
#include
#include "CXXStateTree/StateTree.hpp"
using namespace CXXStateTree;
int main() {
auto machine = StateTree::Builder()
.initial("Idle")
.state("Idle", [](State& s) {
s.on("Start", "Running", nullptr, []() {
std::cout << "Idle -> Running" << std::endl;
});
})
.state("Running", [](State& s) {
s.on("Stop", "Idle", nullptr, []() {
std::cout << "Running -> Idle" << std::endl;
});
})
.build();
machine.send("Start");
machine.send("Stop");
}
```
---
## 🛠️ Building Shared Library
```bash
cmake -S . -B build
cmake --build build
```
After these command the Shared Library can be found in `build` directory
Please Note: in future release cmake will have the ability to install the library automatically, for now it is necessary to do it manually
---
## 🛠️ Building Single Header-Only Library
```bash
cmake -S . -B build -DENABLE_SINGLE_HEADER=ON
cmake --build build
```
After these command the Single Header-Only Library can be found in `single_include` directory with the name CXXStateTree.hpp
Please Note: in future release cmake will have the ability to install the library automatically, for now it is necessary to do it manually
---
## 🧪 Running Tests
```bash
cmake -S . -B build -DENABLE_TEST=ON -DENABLE_COVERAGE=ON
cmake --build build
cd build && ctest
```
---
## 📦 Dependencies
* C++20 compiler (GCC >= 10, Clang >= 11, MSVC >= 2019)
* [GoogleTest](https://github.com/google/googletest) (auto-downloaded via CMake)
---
## 📈 Code Coverage
[](https://codecov.io/gh/ZigRazor/CXXStateTree)
---
## 📂 Directory Structure
```
CXXStateTree/
├── include/CXXStateTree/ # Public header-only API
├── examples/ # Usage examples
├── tests/ # Google Test suite
├── CMakeLists.txt # Project build
└── .github/workflows/ci.yml # GitHub Actions CI
```
---
## 📋 License
MPL2.0 License — see [LICENSE](LICENSE) for details.
---
## 🌟 Coming Soon
* Nested (hierarchical) state support
* DOT/Graphviz state diagram export
* Transitions with context/parameters
| Completed | Milestone | Features |
| :-: | :--------- | ------------------------------------------------------------------ |
| :heavy_check_mark: | v0.1.0 | Basic state machine with `send()`, transitions, and state tracking |
| :heavy_check_mark: | v0.2.0 | Guards and actions |
| :heavy_check_mark: | v0.3.0 | Nested (hierarchical) states |
| :heavy_check_mark: | v0.4.0 | Graphviz export |
| :memo: | v0.5.0 | Coroutine/async support (optional) |
| :memo: | v1.0.0 | Full unit test coverage, benchmarks, and docs |
---
## 👋 Contributions Welcome
Issues, feature suggestions, and PRs are welcome!