Building Better State Machines in Modern C++: CXXStateTree

State machines are the backbone of countless software systems - from game AI and UI flows to embedded devices and network protocols. Yet, implementing them in C++ often feels like we’re stuck in the past: endless switch statements, tangled conditionals, and boilerplate that makes your eyes glaze over.

What if there was a better way?

🚀 Meet CXXStateTree

CXXStateTree is a modern, header-only C++20 library that brings elegance and performance to state machine development. It’s designed for developers who want clean, maintainable code without sacrificing the performance C++ is known for.

💡 Why Another State Machine Library?

Fair question! Here’s what makes CXXStateTree different:

⚡ Zero Heap Allocation

Every allocation counts in performance-critical applications. CXXStateTree is designed with a zero-allocation philosophy - everything stays on the stack where possible.

🔧 Fluent Builder API

No more fighting with complex constructors or configuration objects. Build your state machine the way you’d draw it on a whiteboard:

#include <iostream>
#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 << "🚀 Starting engine..." << std::endl;
});
})
.state("Running", [](State& s) {
s.on("Stop", "Idle", nullptr, []() {
std::cout << "🛑 Stopping engine..." << std::endl;
});
})
.build();

machine.send("Start");  // Output: 🚀 Starting engine...
machine.send("Stop");   // Output: 🛑 Stopping engine...
}

Clean. Readable. Self-documenting.

🛡️ Guards and Actions

Real-world state machines need conditional logic. CXXStateTree lets you attach guards (conditions) and actions to transitions:

auto doorMachine = StateTree::Builder()
.initial("Closed")
.state("Closed", [](State& s) {
s.on("Open", "Open",
[]() {
// Guard: only open if unlocked
return !isDoorLocked();
},
[]() {
// Action: perform the opening
std::cout << "🚪 Opening door..." << std::endl;
}
);
})
.state("Open", [](State& s) {
s.on("Close", "Closed", nullptr, []() {
std::cout << "🚪 Closing door..." << std::endl;
});
})
.build();

🌳 Hierarchical States (Available!)

One of the most powerful features - nested states for modeling complex behaviors:

Game Character
├── Alive
│   ├── Idle
│   ├── Walking
│   └── Running
└── Dead

This allows you to handle events at different levels of specificity, reducing code duplication and improving maintainability.

🎯 Real-World Use Cases

CXXStateTree shines in:

• 🎮 Game Development: Character AI, game flow, animation controllers
• 📱 UI Development: Form wizards, navigation flows, modal states
• 🤖 Embedded Systems: Protocol handlers, device state management
• 🌐 Network Programming: Connection state machines, protocol implementations
• 🦾 Robotics: Behavior trees, task scheduling

📦 Getting Started

Requirements

• C++20 compiler (GCC ≥ 10, Clang ≥ 11, MSVC ≥ 2019)
• CMake (for building)

Installation

Option 1: Single Header (Recommended)

git clone https://github.com/ZigRazor/CXXStateTree.git
cd CXXStateTree
cmake -S . -B build -DENABLE_SINGLE_HEADER=ON
cmake --build build

The single header file will be in single_include/CXXStateTree.hpp - just drop it into your project!

Option 2: Shared Library

cmake -S . -B build
cmake --build build

Quick Example: Traffic Light

Let’s build a simple traffic light system:

#include <iostream>
#include <thread>
#include <chrono>
#include "CXXStateTree/StateTree.hpp"

using namespace CXXStateTree;
using namespace std::chrono_literals;

int main() {
auto trafficLight = StateTree::Builder()
.initial("Red")
.state("Red", [](State& s) {
s.on("Timer", "Green", nullptr, []() {
std::cout << "🔴 -> 🟢 RED to GREEN" << std::endl;
});
})
.state("Green", [](State& s) {
s.on("Timer", "Yellow", nullptr, []() {
std::cout << "🟢 -> 🟡 GREEN to YELLOW" << std::endl;
});
})
.state("Yellow", [](State& s) {
s.on("Timer", "Red", nullptr, []() {
std::cout << "🟡 -> 🔴 YELLOW to RED" << std::endl;
});
})
.build();

// Simulate traffic light cycle
for (int i = 0; i < 6; i++) {
std::this_thread::sleep_for(2s);
trafficLight.send("Timer");
}

return 0;
}

🏗️ Project Quality

CXXStateTree isn’t just elegant code - it’s built with professional software engineering practices:

• ✅ Google Test Integration - Comprehensive unit test suite
• ✅ Codecov Integration - Track test coverage
• ✅ GitHub Actions CI/CD - Every commit is validated
• ✅ Modern CMake - Easy integration into existing projects

🗺️ Roadmap

The project has an exciting future ahead:

Status	Version	Features
✅	v0.1.0	Basic state machine with transitions
✅	v0.2.0	Guards and actions
✅	v0.3.0	Nested hierarchical states
✅	v0.4.0	Graphviz export
🚧	v0.5.0	Coroutine/async support
📋	v1.0.0	Full test coverage, benchmarks, docs

🤝 Contributing

CXXStateTree is open source under the MPL 2.0 license and welcomes contributions!

Ways to contribute:

• 🐛 Report bugs and issues
• 💡 Suggest new features
• 🔧 Submit pull requests
• 📚 Improve documentation
• ⚡ Share performance benchmarks

🎓 Learning Resources

Want to dive deeper? Check out:

• GitHub Repository
• Examples Directory
• Test Suite - Great for understanding usage patterns

💭 Final Thoughts

State machines don’t have to be a pain in C++. With CXXStateTree, you get:

1. Developer Productivity - Write less, express more
2. Maintainability - Clear structure that scales
3. Performance - Zero-overhead abstractions
4. Modern C++ - Built for C++20 and beyond
5. Active Development - Regular updates and improvements

Whether you’re building a game, an embedded system, or a complex business application, CXXStateTree provides a solid foundation for managing state transitions cleanly and efficiently.

🚀 Try It Today

git clone https://github.com/ZigRazor/CXXStateTree.git

Give it a star ⭐ if you find it useful, and share your experience in the comments below!

---

What kind of state machines are you building? Drop a comment and let’s discuss! 💬

---

Who Am I?