How can I create a state machine using Flecs

[j-fdion]

Hi,

I recently read this blog post:
https://ajmmertens.medium.com/why-storing-state-machines-in-ecs-is-a-bad-idea-742de7a18e59

I found the approach really interesting and wanted to try it out myself. However, it looks like the Flecs API has changed since the article was written.

I came across the same example using union traits here:
https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html#union-trait

But there's a warning indicating that support for the Union trait will be deprecated and replaced by exclusive DontFragment relationships.

So, what's the recommended way to implement this kind of state machine in Flecs as of 2025?

I'm using the Rust bindings, and my entities can be in one of three states:

#[derive(Component)]
struct PreconditionState {}

#[derive(Component)]
struct WorkingState {
    t: i32,
}

#[derive(Component)]
struct ExecutionState {}

What would be the best way to model this, allowing transitions like:
Precondition -> Working -> Execution -> Precondition?

Thanks in advance for your help!

[anntnzrb]

Use exclusive relationships with DontFragment and Exclusive traits (replaces deprecated Union). Create a state relationship: let state = world.entity().add_trait::<flecs::DontFragment>().add_trait::<flecs::Exclusive>(). Define state entities, then add states via entity.add_id((state, current_state)). The Exclusive trait automatically removes the previous state when you add a new one, enabling clean state transitions. See docs/ComponentTraits.md for details.

[SanderMertens]

Yup this is the right answer! See here for more details on the breaking change: #466 (comment)